Working with Golem Promises in C/C++

Golem promises provide a way for Golem workers to wait on an external condition. The worker creates the promise and somehow sends its identifier to the external system responsible for completing the promise. Then the worker can await the promise, being suspended until the external system completes the promise using Golem's REST API.

It is also possible to complete a promise from within a Golem worker using the Golem SDK.

When a promise is completed, an arbitrary byte array can be attached to it as a payload - this data is returned to the awaiting worker when is continues execution.

In C/C++ the promise API can be used by directly importing and using the Golem runtime API.

Adding as a dependency

To use Golem's runtime API, add all the WIT files from https://github.com/golemcloud/golem-wit/tree/main/wit/deps (opens in a new tab) in the project's wit/deps directory, and then importing this interface to the component's world:

world example {
    import golem:api/host@0.2.0;
    // ...
}

Creating a promise

To create a promise simply call the golem_api_host_create_promise function:

golem_api_host_promise_id_t promise_id;
golem_api_host_create_promise(&promise_id);

The returned value, golem_api_host_promise_id_t, is defined as the following:

// UUID
typedef struct golem_api_host_uuid_t {
  uint64_t   high_bits;
  uint64_t   low_bits;
} golem_api_host_uuid_t;
 
// Represents a Golem component
typedef struct golem_api_host_component_id_t {
  golem_api_host_uuid_t   uuid;
} golem_api_host_component_id_t;
 
// Represents a Golem worker
typedef struct golem_api_host_worker_id_t {
  golem_api_host_component_id_t   component_id;
  example_string_t   worker_name;
} golem_api_host_worker_id_t;
 
// A promise ID is a value that can be passed to an external Golem API to complete that promise
// from an arbitrary external source, while Golem workers can await for this completion.
typedef struct golem_api_host_promise_id_t {
  golem_api_host_worker_id_t   worker_id;
  golem_api_host_oplog_index_t   oplog_idx;
} golem_api_host_promise_id_t;

Deleting a promise

If a promise is no longer used, it has to be deleted with

golem_api_host_promise_id_t promise_id;
// .. set up promise_id ..
golem_api_host_delete_promise(&promise_id);

Awaiting a promise

To await a promise, use the golem_api_host_await_promise function:

golem_api_host_promise_id_t promise_id;
// .. set up promise_id ..
example_list_u8_t payload; // will be filled by the call
golem_api_host_await_promise(&promise_id, &payload);

The resulting payload is a struct containing a len length and a pointer to len number of bytes, containig the data attached to the promise on completion.

Completing a promise from within a worker

To complete a promise from within a worker, use the golem_api_host_complete_promise function:

golem_api_host_promise_id_t promise_id;
example_list_u8_t payload;
// .. set up promise_id and payload ..
golem_api_host_complete_promise(&promise_id, &payload);

Completing a promise from an external source

To see how to use the promise ID to complete a promise through the external REST API, check the REST API documentation.