fiber.h

Fibers are light, co-operative threads of execution. The fiber.h header defines a low-level API for manipulating Fibers in Emscripten. Fibers are implemented with Asynchronous Code, so you must link your program with ASYNCIFY if you intend to use them.

Fibers are intended as a building block for asynchronous control flow constructs, such as coroutines. They supersede the legacy coroutine API that was available in the fastcomp backend. This API is similar to, but distinct from, POSIX ucontext.

API Reference

Types

type emscripten_fiber_t

This structure represents a Fiber context continuation. The runtime does not keep references to these objects, they only contain information needed to perform the context switch. The switch operation updates some of the contents, however.

void *stack_base

Upper limit of the C stack region. The stack grows down, so this is the initial position of the stack pointer. Must be at least 16-byte aligned.

void *stack_limit

Lower limit of the C stack region. Must be below emscripten_fiber_t.stack_base.

void *stack_ptr

Current position of the stack pointer. Must be between emscripten_fiber_t.stack_base and emscripten_fiber_t.stack_limit.

em_arg_callback_func entry

Entry point. If not NULL, this function will be called when the fiber is switched into. Otherwise, emscripten_fiber_t.asyncify_data is used to rewind the call stack.

void *user_data

Opaque pointer, passed as-is to emscripten_fiber_t.entry.

asyncify_data_t asyncify_data

Asyncify data structure. Used to unwind and rewind the call stack when switching fibers.

type asyncify_data_t
void *stack_ptr

Current position of the Asyncify stack pointer.

The Asyncify stack is distinct from the C stack. It contains the call stack as well as the state of WASM locals. Unlike the C stack, it grows up.

void *stack_limit

Upper limit of the Asyncify stack region.

int rewind_id

Opaque handle to the function that needs to be called in order to rewind the call stack. This value is only meaningful to the runtime.

Warning

Rewind IDs are currently thread-specific. This makes it impossible to resume a fiber that has been started from a different thread.

Functions

void emscripten_fiber_init(emscripten_fiber_t *fiber, em_arg_callback_func entry_func, void *entry_func_arg, void *c_stack, size_t c_stack_size, void *asyncify_stack, size_t asyncify_stack_size)

Initializes a fiber context. It can then be entered by calling emscripten_fiber_swap().

Parameters:

  • fiber (emscripten_fiber_t*) – Pointer to the fiber structure.

  • entry_func (em_arg_callback_func) – Entry point function, called when the fiber is entered for the first time.

  • entry_func_arg (void*) – Opaque pointer passed to entry_func.

  • c_stack (void*) – Pointer to memory region to use for the C stack. Must be at least 16-byte aligned. This points to the lower bound of the stack, regardless of growth direction.

  • c_stack_size (size_t) – Size of the C stack memory region, in bytes.

  • asyncify_stack (void*) – Pointer to memory region to use for the Asyncify stack. No special alignment requirements.

  • asyncify_stack_size (size_t) – Size of the Asyncify stack memory region, in bytes.

Note

If entry_func returns, the entire program will end, as if main had returned. To avoid this, you can use emscripten_fiber_swap() to jump to another fiber.

void emscripten_fiber_init_from_current_context(emscripten_fiber_t *fiber, void *asyncify_stack, size_t asyncify_stack_size)

Partially initializes a fiber based on the currently active context. This is needed in order to switch back from a fiber into the thread’s original context.

This function sets up emscripten_fiber_t.stack_base and emscripten_fiber_t.stack_limit to refer to the current stack boundaries, sets emscripten_fiber_t.entry to NULL, and makes emscripten_fiber_t.asyncify_data refer to the provided Asyncify stack memory. Other fields are not changed.

Fibers initialized by this function are not complete. They are only suitable to pass as the first argument to emscripten_fiber_swap(). Doing that completes the continuation, making it possible to switch back to the original context with another emscripten_fiber_swap(), as with a normal fiber.

Parameters:

  • fiber (emscripten_fiber_t*) – Pointer to the fiber structure.

  • asyncify_stack (void*) – Pointer to memory region to use for the Asyncify stack. No special alignment requirements.

  • asyncify_stack_size (size_t) – Size of the Asyncify stack memory region, in bytes.

void emscripten_fiber_swap(emscripten_fiber_t *old_fiber, emscripten_fiber_t *new_fiber)

Performs a fiber context switch.

Parameters:

  • old_fiber (emscripten_fiber_t*) – Fiber representing the current context. It will be partially updated, such as that switching back into it via another call to emscripten_fiber_swap() would appear to return from the original call.

  • new_fiber (emscripten_fiber_t*) – Fiber representing the target context. If the fiber has an entry point, it will be called in the new context and set to NULL. Otherwise, emscripten_fiber_t.asyncify_data is used to rewind the call stack. If the fiber is invalid or incomplete, the behavior is undefined.