async2.h - asynchronous, stackful subroutines [alpha, currently in active-ish development]

Taking inspiration from protothreads, async.h, coroutines.h and async/await as found in python this is an async/await/fawait/event loop implementation for C based on Duff's device.

Features

1. It's 100% pure, portable C.
2. It uses 96 bytes of memory per state, but grants you seamless nesting abilities, error handling and stack management.
3. It's not dependent on an OS.
4. It's a bit simpler to understand than other implementations as async state/stack management is fully handled by the lib.
5. You can't preserve local variables across function calls, but the library provides a way to store them persistently (see practices)

The API will probably be deprecated because I'm currently rewriting a lot of parts from scratch and taking a different approach for state callbacks.

Don't use the current code to learn good practices or rely on it a lot since stuff might change A LOT.

API

Ownership of references system

(handled automatically by fawait/wait_for/gather coros, manual use only)

Some future api methods might use su_state as input coro type, explicitly indicating that it steals current ownership, in such case user mustn't access passed s_astate object or should INCREF ownership manually once more before transferring ownership to the method.

Practices

• How can I return value/values from the function?

Pass pointer to value as args when creating new coroutine with async_new. Then assign to pointer inside function body:

async f(state){
    async_begin(state);
    int *res = state->args; /* args here is a pointer to int a (can be a pointer to any c object) */
    *res = 42;
    ...
}
...
int a;
fawait(async_new(f, &a, ASYNC_NONE)){ 
    printf("error %s happened\n", async_strerror(async_errno));
}

We can replace int * with, say, struct * if we want multiple return values of different types. Any type pointer is fine.

• What should I do if I need local variables?

Just create a struct with all needed variables and then pass struct as a type when creating new coro. See examples/example.c and short example below.

Examples

A simple example to run two coroutines in parallel

#include <stdio.h>
#include "async2.h"

struct amain_stack {
    int i;
};

async amain(s_astate state) {
    struct amain_stack *locals = state->locals;
    char *args = state->args;
    async_begin(state);
            /* Note, that locals->i assignment to 0 is happening inside async_begin block. 
             * Don't assign them outside! */
            for (locals->i = 0; locals->i < 3; locals->i++) {
                printf("task %s: iteration №%d\n", args, locals->i + 1);
                /* Let other tasks run with yield. Similar to python's await asyncio.sleep(0) usage. */
                async_yield;
            }
    async_end;
}

int main(void) {
    struct async_event_loop *loop = async_get_event_loop();
    loop->init();
    async_create_task(async_new(amain, "task 1", struct amain_stack)); /* Allocate enough memory to hold locals of type struct amain_stack */
    async_create_task(async_new(amain, "task 2", struct amain_stack));
    loop->run_forever();
    loop->destroy();
}

Code inside braces only executes when coroutine returns with non-zero async_errno code

fawait(async_func(10)){
    if(async_errno == ASYNC_ENOMEM){
        /* Handle memory error... */
    }
} else {
    /* Coroutine finished without errors */
}

Manual task ownership and error check

locals->task = async_create_task(coro());
ASYNC_XINCREF(locals->task); /* Acquire ownership for task so it won't be immediately deleted after completion */
/* Do stuff... */
if(locals->task){
    await(async_done(locals->task));
    if(locals->task->err != ASYNC_OK){
        /* Handle task error manually */
    }
}

ASYNC_XDECREF(locals->task);

Don't create libraries with async_new usage!

• Always wrap coroutines in such way as asyncio_sleep or asyncio_wait_for so their use will be very simple(no need to use async_new on them as they prepare), such way you can provide custom async functions that can take any arguments, but return type still will be limited to s_astate. ASYNC_PREPARE and ASYNC_PREPARE_NOARGS are pretty helpful for such function wrapping.
• Use underlying dev methods as async_new_coro_ and async_alloc_ in order to overcome userland limitations in creating async functions
• Always wrap all the used tasks with ownership, otherwise you risk to get invalid pointer access. Remember: one INCREF - one DECREF
• Provide cancel functions for your friendly methods, so even cancelled function won't break ownership and coro will be properly deleted.
• Use async_alloc(_) to manage dynamic memory

Caveats

1. As with protothreads, you have to be very careful with switch statements and manually-created local variables(variables not stored in locals) within an async subroutine. Generally best to avoid them.
2. As with protothreads, you can't make blocking system calls and preserve the async semantics. These must be changed into non-blocking calls that test a condition.
3. You can't use setjump and longjump functions amid await because async2 alters usual function flow, so given code is fine:

setjmp(var);
... 
longjump(var);
...
await(global == 42);

but this one will be an undefined behavior:

setjmp(var);
... 
await(global == 42);
...
longjump(var);

That means no way you can use C exceptions libraries like exceptions4c to wrap fawait or await or yield calls, use async_errno and fawait braces instead.