minicoro Documentation

A coroutine is an independent "green" thread of execution that only suspends when explicitly told to via a yield function.

• Creation: Use mco_create with an mco_desc structure. This returns a handle but does not start execution.
• Execution: Use mco_resume to start or continue a coroutine. It runs until it either terminates or calls mco_yield.
• Suspension: Use mco_yield to suspend execution. The mco_resume call that triggered the coroutine will return immediately, even if the yield occurs deep within nested function calls.
• Resumption: Calling mco_resume on the same handle will pick up execution exactly where it last yielded.
• Data Association: You can attach persistent data to a coroutine using user_data in the mco_desc and retrieve it via mco_get_user_data.

mco_desc desc = mco_desc_init(coro_entry, 0);
mco_coro* co;
mco_create(&co, &desc);
mco_resume(co);
mco_yield(co);
mco_resume(co);

You can customize the library's behavior by defining specific macros before including the header or via compiler flags.

To pass data between the caller and the coroutine, use mco_push inside the coroutine (or in the caller) and mco_pop to retrieve it. This is useful for sending parameters into a coroutine or receiving results from a mco_yield.

In the example below, the coroutine receives a max value via mco_pop, calculates Fibonacci numbers, and sends them back to the caller using mco_push before yielding.

#define MINICORO_IMPL
#include "minicoro.h"
#include <stdio.h>
#include <stdlib.h>

static void fail(const char* message, mco_result res) {
  printf("%s: %s\n", message, mco_result_description(res));
  exit(-1);
}

static void fibonacci_coro(mco_coro* co) {
  unsigned long m = 1;
  unsigned long n = 1;

  /* Retrieve max value. */
  unsigned long max;
  mco_result res = mco_pop(co, &max, sizeof(max));
  if(res != MCO_SUCCESS)
    fail("Failed to retrieve coroutine storage", res);

  while(1) {
    /* Yield the next Fibonacci number. */
    mco_push(co, &m, sizeof(m));
    res = mco_yield(co);
    if(res != MCO_SUCCESS)
      fail("Failed to yield coroutine", res);

    unsigned long tmp = m + n;
    m = n;
    n = tmp;
    if(m >= max)
      break;
  }

  mco_push(co, &m, sizeof(m));
}

int main() {
  mco_coro* co;
  mco_desc desc = mco_desc_init(fibonacci_coro, 0);
  mco_result res = mco_create(&co, &desc);
  if(res != MCO_SUCCESS)
    fail("Failed to create coroutine", res);

  unsigned long max = 1000000000;
  mco_push(co, &max, sizeof(max));

  int counter = 1;
  while(mco_status(co) == MCO_SUSPENDED) {
    res = mco_resume(co);
    if(res != MCO_SUCCESS)
      fail("Failed to resume coroutine", res);

    unsigned long ret = 0;
    res = mco_pop(co, &ret, sizeof(ret));
    if(res != MCO_SUCCESS)
      fail("Failed to retrieve coroutine storage", res);
    printf("fib %d = %lu\n", counter, ret);
    counter = counter + 1;
  }

  res = mco_destroy(co);
  if(res != MCO_SUCCESS)
    fail("Failed to destroy coroutine", res);
  return 0;
}

The minicoro library provides functions for managing coroutine lifecycles, controlling execution flow, and passing data via a storage interface.

Coroutine Lifecycle

• mco_desc_init(func, stack_size): Initializes a mco_desc structure. If stack_size is 0, MCO_DEFAULT_STACK_SIZE is used.
• mco_init(co, desc): Initializes an existing mco_coro using a description.
• mco_uninit(co): Uninitializes a coroutine (fails if not dead or suspended).
• mco_create(out_co, desc): Allocates and initializes a new coroutine.
• mco_destroy(co): Uninitializes and deallocates a coroutine.

Execution Control

• mco_resume(co): Starts or continues coroutine execution.
• mco_yield(co): Suspends the current coroutine.
• mco_status(co): Returns the current mco_state.
• mco_running(): Returns the mco_coro currently running in the calling thread.

Storage Interface (Data Passing)

Use these to pass bytes between mco_yield and mco_resume:

• mco_push(co, src, len): Pushes bytes into coroutine storage.
• mco_pop(co, dest, len): Pops bytes from storage (consumes them).
• mco_peek(co, dest, len): Peeks at bytes without consuming them.
• mco_get_bytes_stored(co): Returns available bytes for popping.
• mco_get_storage_size(co): Returns total storage size.

/* Structure used to initialize a coroutine. */
typedef struct mco_desc {
  void (*func)(mco_coro* co); /* Entry point function for the coroutine. */
  void* user_data;            /* Coroutine user data, can be get with `mco_get_user_data`. */
  /* Custom allocation interface. */
  void* (*alloc_cb)(size_t size, void* allocator_data); /* Custom allocation function. */
  void  (*dealloc_cb)(void* ptr, size_t size, void* allocator_data);     /* Custom deallocation function. */
  void* allocator_data;       /* User data pointer passed to `alloc`/`dealloc` allocation functions. */
  size_t storage_size;        /* Coroutine storage size, to be used with the storage APIs. */
  /* These must be initialized only through `mco_init_desc`. */
  size_t coro_size;           /* Coroutine structure size. */
  size_t stack_size;           /* Coroutine stack size. */
} mco_desc;

/* Coroutine functions. */
mco_desc mco_desc_init(void (*func)(mco_coro* co), size_t stack_size);
 mco_result mco_init(mco_coro* co, mco_desc* desc);
 mco_result mco_uninit(mco_coro* co);
 mco_result mco_create(mco_coro** out_co, mco_desc* desc);
 mco_result mco_destroy(mco_coro* co);
 mco_result mco_resume(mco_coro* co);
 mco_result mco_yield(mco_coro* co);
 mco_state mco_status(mco_coro* co);
 void* mco_get_user_data(mco_coro* co);

/* Storage interface functions */
mco_result mco_push(mco_coro* co, const void* src, size_t len);
 mco_result mco_pop(mco_coro* co, void* dest, size_t len);
 mco_result mco_peek(mco_coro* co, void* dest, size_t len);
 size_t mco_get_bytes_stored(mco_coro* co);
 size_t mco_get_storage_size(mco_coro* co);

/* Misc functions. */
mco_coro* mco_running(void);
 const char* mco_result_description(mco_result res);