Using WASI interfaces from C/C++

Golem implements and exports a subset of the WASI (opens in a new tab) interfaces, as well as its own runtime interfaces.

The previous sections already introduced how to use a subset of these interfaces to control durability settings, make HTTP requests, and control retries or use promises.

WIT specifications

The full set of WIT specifications Golem implements is available in the following public repository:

https://github.com/golemcloud/golem-wit/tree/main/wit/deps (opens in a new tab)

The following table lists all packages provided by Golem:

Package	Description
`golem:api`	Golem's Runtime API
`golem:rpc`	Provides support for Worker to Worker communication
`wasi:blobstore`	Interface for storing and retrieving large binary data
`wasi:cli`	Interface for environment variables and standard I/O
`wasi:clocks`	Interface for querying the system time
`wasi:filesystem`	Interface for working with files and directories
`wasi:http`	Interface for making HTTP requests
`wasi:io`	Interface for working with futures and streams
`wasi:keyvalue`	Interface for storing and retrieving key-value pairs - only partially implemented
`wasi:logging`	Interface for logging messages
`wasi:random`	Interface for generating random numbers
`wasi:sockets`	Interface for working with TCP and UDP sockets (currently not supporting durable execution)

Additional Golem runtime APIs

This section describes some additional Golem-specific functionalities which are available through the Golem runtime API.

Generate an idempotency key

Golem provides a function to generate an idempotency key (an UUID) which can be passed to external systems to ensure that the same request is not processed multiple times.

It is guaranteed that this idempotency key will always be the same (per occurrence) even if the worker is restarted due to a crash.

To generate the idempotency key:

golem_api_host_uuid_t key;
golem_api_host_generate_idempotency_key(&key);

Get worker metadata

It is possible to query metadata for Golem workers. This metadata is defined by the following WIT record:

record worker-metadata {
    worker-id: worker-id,
    args: list<string>,
    env: list<tuple<string, string>>,
    status: worker-status,
    component-version: u64,
    retry-count: u64
}
 
enum worker-status {
    /// The worker is running an invoked function
    running,
    /// The worker is ready to run an invoked function
    idle,
    /// An invocation is active but waiting for something (sleeping, waiting for a promise)
    suspended,
    /// The last invocation was interrupted but will be resumed
    interrupted,
    /// The last invocation failed and a retry was scheduled
    retrying,
    /// The last invocation failed and the worker can no longer be used
    failed,
    /// The worker exited after a successful invocation and can no longer be invoked
    exited,
}

There are two exported functions to query worker metadata:

get_self_metadata returns the metadata for the current worker
get_worker_metadata returns the metadata for a specific worker given by it's golem_api_host_worker_id_t

Enumerate workers

Worker enumeration is a feature of Golem available both through the public HTTP API and using the WIT interfaces.

⚠️

Enumerating workers of a component is a slow operation and should not be used as part of the application logic.

Update a worker

To trigger update for a given worker from one component version to another, use the golem_api_host_update_worker function:

golem_api_host_worker_id_t worker_id;
// .. set up worker_id ..
golem_api_host_update_worker(&worker_id, target_version, GOLEM_API_HOST_UPDATE_MODE_AUTOMATIC);

To learn more about updating workers, see the updating workers page.

The WASI Key-Value store interface

Although Golem workers can store their state completely in their own memory, it is possible to use the wasi:keyvalue interface to store key-value pairs in a Golem managed key value storage.

This can be useful if state needs to be shared between different workers or if the size of this state is too large to be stored in memory.

The WASI Blob Store interface

The wasi:blobstore interface provides a way to store and retrieve large binary data. This can be useful for storing large files or other binary data that is too large to be stored in the worker's memory.

Updating Workers Worker to Worker Communication