| Stackful coroutines in C. |
|
| * `Async` coroutines which can pause, waiting for a future. |
| * `Generator` coroutines used as generators for loops. |
| * `Coroutine` the coroutine engine used by `Async` and `Generator`. |
|
| Your code doesn't need to do anything special to be a coroutine, and only standard, or commonly available libraries are needed. |
|
|
|
|
|
|
|
|
|
| ## Prerequisites |
|
| The goal was to make a system which can be used 'out of the box'. These libraries rely on as much as possible on C's cross-platform comfort zone. C's standard libraries are used as far as possible, but, as `threads.h` is not usually supported, `pthread.h` has been used instead. |
|
| You will need to build & link the code as part of your system - `coroutine/async.c`, `coroutine/generator.c` and `coroutine/coroutine.c` - ensure the headers, `include/*`, are available on your include path. |
|
| ## Quick Start |
|
| ### Async |
|
| To run an Async program: |
|
| #include "async.h" |
| main(){ |
| Async_StartSystem(); |
| void *res = NULL; |
| bool canceled = Async_Run(asyncmain, ¶m, &res); |
| Async_StopSystem(); |
| } |
|
| Async runs tasks, switching between them when the current task waits on an `Async_Future`. `asyncmain()` is run as a task. The start function for any task looks like this: |
|
| bool mytask(void *param, void **res){ |
|
| // do your thing here |
|
| return canceled; |
| } |
|
| When `Task` returns from its start function, it returns whether it was canceled. Canceled `Task`s are assumed to have not finished what they were doing. |
|
| Within your async task, create `Async_Task`s and `Async_Task_Await()` them when you want to wait for their result: |
|
| Async_Task task1; |
| Async_Task_ctor(&task1, adifferenttask, &task1param); |
|
| void *result; |
| bool canceled = Async_Task_Await(&task1, &result); |
|
| Async_Task_dtor(&task1); |
|
| // use the result |
|
| When a task needs to wait for something, and wants to allow other tasks to run, it should use a `Future`: |
|
| Async_Future future; |
| Async_Future_ctor(&future); |
|
| // pass the future to the background-thing-which-might-take-a-while |
|
| bool canceled = Async_Future_Await(&future); |
| // get the result, if you want it, from the future |
|
| Async_Future_dtor(&future); |
|
| When the background-thing-which-might-take-a-while has a result: |
|
| Async_Future_SetResult(future, false, result); |
|
| ### Generators |
|
| The coroutine system needs to be started, either through `Async_StartSystem()`, or directly with `Coroutine_StartSystem()` if you don't want to do async things. |
|
| You will need a generator function: |
|
| void *yield_my_things(void *param){ |
| bool domore = true; |
|
| // loop/call functions to find more values to yield, and when you have one: |
| domore = Generator_Yield(thing); |
| // .. if domore is false, exit your generator - it is being destructed |
|
| // not actually used by generators, but this is a useful convention for bubbling |
| // the flag out to calling functions. |
| return (void *)domore; |
| } |
|
| And to use it: |
|
| Generator gen; |
| Generator_ctor(&gen, yield_my_things, ".."); |
| void *thing; |
| while(Generator_Next(&gen, &thing)){ |
| // use thing - a value yielded by your generator |
| } |
| Generator_dtor(&gen); |
|
| ### Coroutines |
|
| While you can use coroutines directly, it's designed as a system to support more useful patterns, like `Async` and `Generators`. |
|
| The Coroutines system must be started: |
|
| Coroutine_StartSystem(); |
| // use coroutines here |
| Coroutine_StopSystem(); |
|
| Your coroutine will need to have a start function: |
|
| void *start(void *param){ |
| ... |
| } |
|
| When there is no coroutine running, start your 'main' coroutine: |
|
| void *result = Coroutine_Run(comain, param); |
|
| Create other coroutines like this: |
|
| Coroutine *cor = Coroutine_New(start); |
|
| When you want a Coroutine to run, or to return from a yield: |
|
| Coroutine_Continue(cor, value, run_early); |
|
| `value` will be start function's parameter, or the value returned from the yield. |
|
| Within the Coroutine, to yield a value: |
|
| void *Coroutine_Yield(value, on_yield, void *me); |
|
| The on_yield function is called after the coroutine has been 'wait'ed, but before the next coroutine is resumed. |
|
| ## How it Works |
|
| The coroutine system uses the stack, divided into smaller stacks, for the coroutines. This means you may need to consider whether the coroutine stack size, set by `COROUTINE_STARTUP_STACK_SIZE`, is right for your coroutines, and whether your stack size is enough for the number of coroutines you might run concurrently. |
|
| As each of your thread has its own stack - the coroutine system can be run (or not) independantly on each of your threads. For some special cases, you may want to adjust each of your thread's stack sizes depending on how it is used. |
|
| ## Style |
|
| The style is influenced by C++. For example, where possible, a `Something *Something_New(a, b, c)` and `Something_Delete(Something *)`, where a `Something` is `malloc`ed, will have corresponding `Somthing_ctor(Somthing *, a, b, c)` and `Something_dtor(Something *)` to initialise and finalise a `Something` on the stack, or within another object. Using `.._ctor()` and `.._dtor()` will be faster as they avoid the `malloc()` and `free()`. |
|
| Something *oneofthem = Something_New(); |
| // use oneofthem |
| Something_Delete(oneofthem); |
|
| Can be also be done like this, and this will run faster: |
|
| Something oneofthem; |
| Something_ctor(&oneofthem); |
| // use oneofthem |
| Something_dtor(&oneofthem); |
|
| The exception is `Coroutine_New()` and `Coroutine_Delete()`. The returned `Coroutine` is somewhere on your thread's stack - its memory is managed by the coroutine system, and is allocated and freed quickly. |
|
| ## Usage |
|
| When you are using coroutines or generators: |
|
| void *myfunc(void *){ |
| // your function here |
| } |
|
| Coroutine_StartSystem(); |
| Coroutine_Run(myfunc, (void *)myparam); |
| Coroutine_StopSystem(); |
|
| If you also use async, then: |
|
| bool myfunc(void *myparam, void **res){ |
| // your async function here |
| } |
|
| Async_StartSystem(); |
| void *res = NULL; |
| bool canceled = Async_Run(myfunc, myparam, &res); |
| Async_StopSystem(); |
|
| While the system is started, you can make many calls to `Coroutine_Run()` or `Async_Run()`. A running system is thread local - each thread you want to use coroutines on will need to be `Coroutine_StartSystem()`ed or `Async_StartSystem()`ed. |
|
|
|
| # API |
|
| ## Generator |
|
| The pattern for a `Generator` is: |
|
| #### A loop which uses the `Generator` |
|
| Generator gen; |
| Generator_ctor(&gen, mygen, ¶m); |
|
| void *value; |
| while(Generator_Next(&gen, &value)){ |
| // use value here |
| } |
| // value is now the return value from the Generator |
|
| Generator_dtor(&gen); |
|
| Or: |
|
| Generator *gen = Generator_New(mygen, ¶m); |
|
| void *value; |
| while(Generator_Next(gen, &value)){ |
| // use value here |
| } |
|
| Generator_Delete(gen); |
|
| `Generator`s yield a series of `void *`s - what the `void *`s mean is up to you. `Generator_Next()` returns a `bool` to indicate whether the `Generator` has finished. |
|
| #### A generator function |
|
| void *mygen(void *param){ |
| bool domore = true; |
| // The parameter is a pointer to a string of chars |
| for (char *str = param; *str; ++str) { |
| // The value yielded is a pointer to a character in the string |
| domore = Generator_Yield(str); |
| if (!domore){ |
| break; |
| } |
| } |
|
| return (void *)domore; |
| } |
|
| The `bool` returned from `Generator_Yield()` indicates whether the generator function should yield more values. When it is `false` the `Generator` is being finalised - your generator function should close files, and release any other resources it has claimed, before exiting. |
|
| ### void Generator_ctor(Generator *gen, void *(*start)(void *), void *param) |
|
| Initialise a `Generator` |
|
| Generator gen; |
| Generator_ctor(&gen, mystart, ¶ms); |
|
| // Generator is used |
|
| // ... later: |
|
|
|
|
|
|
| Generator_dtor(&gen); |
|
| ### Generator *Generator_New(void *(*)(void *), void *) |
|
| `new` a `Generator` - malloc it and initialise it. |
|
| Generator *gen = Generator_New(mystart, ¶ms); |
|
| // Generator is used |
|
| // ... later: |
| Generator_Delete(gen); |
|
| ### void Generator_dtor(Generator *gen) |
|
| Finalise a `Generator`. Once a `Generator` is no longer needed, it must be finalised: |
|
| // earlier... |
| Generator gen; |
| Generator_ctor(&gen, mystart, ¶ms); |
|
| // Generator is used |
|
| // the Generator is no longer needed |
| Generator_dtor(&gen); |
|
|
| ### void Generator_Delete(Generator *) |
|
| Finalise then `free()` a `Generator`. Once a `new`ed `Generator` is no longer needed, it must be deleted: |
|
| // earlier... |
| Generator *gen = Generator_New(mystart, ¶ms); |
|
| // Generator is used |
|
| // the Generator is no longer needed |
| Generator_Delete(gen); |
|
|
| ### bool Generator_Next(Generator *, void **value) |
|
| Get the next value yielded by the `Generator`. |
|
| void *value; |
| while(Generator_Next(gen, &value)){ |
| // use value here |
| } |
|
| When `true` is returned, `value` is the value yielded by the `Generator`. When `false` is returned, `value` is the value returned when the `Generator` returned - the `Generator` has finished. |
|
| ### bool Generator_Yield(void *) |
|
| Yield a value from a `Generator` function. |
|
| bool domore = Generator_Yield(value); |
|
| `value` is then provided by `Generator_Next()` as the next value from the generator. The `bool` returned by `Generator_Yield()` indicates whether more values should be provided by your generator function. When `true` provide more values if possible. When `false` close files, free memory, free up any other resources and `return`. `false` is returned when the `Generator` is being finalised. |
|
| ## Coroutine |
|
| ### void Coroutine_StartSystem(); |
|
| Start the coroutine system on this thread. When you've finished with `Coroutine` call `Coroutine_Stop()`. `Coroutine` can be started & stopped many times on one thread. The total stack allowed for all coroutines running on a thread is the size of the call stack on that thread. |
|
| ### void Coroutine_StopSystem(); |
|
| Stop the coroutine system on this thread. |
|
| ### Coroutine_Start |
|
| void *(*)(void *param) |
|
| The entry function for a coroutine. The `param` is the value passed to `Coroutine_Continue`, and the `void *` return value can be accessed through the `Coroutine` object. |
|
| ### Coroutine *Coroutine_New(Coroutine_Start start) |
|
| Create a new `Coroutine`. The `Coroutine` system must be started to create a `Coroutine`. The stack size available to the coroutine will be `COROUTINE_STACK_SIZE` defined in `coroutine.h`. When you have finished with your `Coroutine`, use `Coroutine_Delete()` to delete it. |
|
| ### void Coroutine_Run_Coroutine(Coroutine *cor, void *value) |
|
| Run the `Coroutine` and return when it returns. This is how to start coroutines running in the coroutine system. It is an error for the run coroutine to return before all other coroutines have completed. |
|
| ### void *Coroutine_Run(Coroutine_Start start, void *value) |
|
| Convenience wrapper for `Coroutine_Run_Coroutine` which creates the `Coroutine` and retrieves its result. |
|
| ### void Coroutine_Delete(Coroutine *cor) |
|
| Use `Coroutine_Delete()` to delete a coroutine when it is no longer needed. |
|
| ### void Coroutine_Continue(Coroutine *cor, void *value, bool early) |
|
| Continue the given `Coroutine`. `value` is passed to the coroutine, as `param` to the `start` function, or as the return value from `Coroutine_Yield`. `early` determines whether the continued coroutine is added to the head of tail of the list of runable coroutines. |
|
| ### void *Coroutine_Yield(void *value, Coroutine_YieldCallback on_yield, void *this) |
|
| Yield `value` from the current coroutine; this coroutine is moved to the list of coroutines waiting to be continued. The next runable coroutine is run - either by its start routine being called with `value` as its `param`, or by `value`being returned from its `Coroutine_Yield()`. |
|
| ### void *Coroutine_GetValue(Coroutine *cor) |
|
| Return the `Coroutine`'s value - the value last yielded, or returned by its `start` routine. |
|
| ### Coroutine *Coroutine_GetActive() |
|
| Return whihc coroutine is currently running, ie the caller's `Coroutine`. |
|
| ### bool Coroutine_IsRunning(Coroutine *cor) |
|
| Return whether the given coroutine is still running - it may be running, ready to run, or waiting to be continued, but won't have returned from its `start` function. |
|
|
jonroach