jonroach
9 Sep 2025 13:14
1 contributor
| 1 | #ifndef COROUTINE_H |
| 2 | #define COROUTINE_H |
| 3 | |
| 4 | #include <stdbool.h> |
| 5 | |
| 6 | /////////////////////////////////////////////////////////////////////////////// |
| 7 | // Coroutine |
| 8 | // |
| 9 | // Coroutines for C, based on setjmp/longjmp. |
| 10 | // Thread safe - each thread has its own coroutine system |
| 11 | // Coroutines are cooperatively scheduled |
| 12 | // Coroutines have their own stack (currently 16K each) |
| 13 | // A coroutine can be continued, queried, or deleted on a different thread. |
| 14 | // |
| 15 | // Usage: |
| 16 | // Coroutine_StartSystem(); // call once per thread before using coroutines |
| 17 | // Coroutine *co = Coroutine_New(start_function); |
| 18 | // void *result = Coroutine_Run(co, initial_value); |
| 19 | // Coroutine_Delete(co); |
| 20 | // Coroutine_StopSystem(); // call once per thread when done with coroutines |
| 21 | // |
| 22 | // Inside the coroutine function: |
| 23 | // void *value = Coroutine_Yield(yield_value, on_yield, this); |
| 24 | // ... |
| 25 | // return return_value; |
| 26 | // |
| 27 | // To create a coroutine: |
| 28 | // Coroutine *co = Coroutine_New(start_function); |
| 29 | // To start or continue a coroutine: |
| 30 | // void *result = Coroutine_Continue(co, value, early); |
| 31 | // // early=true puts the coroutine at the head of the run queue |
| 32 | // // early=false puts the coroutine at the tail of the run queue |
| 33 | // To yield from inside a coroutine: |
| 34 | // void *value = Coroutine_Yield(yield_value, on_yield, this); |
| 35 | // // on_yield is called before the next coroutine is run |
| 36 | // // 'this' is passed to on_yield as its parameter |
| 37 | // // value is the value passed to Coroutine_Continue |
| 38 | // To delete a coroutine: |
| 39 | // Coroutine_Delete(co); |
| 40 | // To get the value yielded from, or returned by a corotuine: |
| 41 | // void *value = Coroutine_GetValue(co); |
| 42 | // To get the currently running coroutine (NULL if none): |
| 43 | // Coroutine *co = Coroutine_GetActive(); |
| 44 | // To check if a coroutine is currently running: |
| 45 | // bool running = Coroutine_IsRunning(co); |
| 46 | // |
| 47 | // Notes: |
| 48 | // Coroutine is not expected to be used directly, but as a foundation for |
| 49 | // higher level constructs such as Generators, Async, etc. |
| 50 | // |
| 51 | /////////////////////////////////////////////////////////////////////////////// |
| 52 | |
| 53 | |
| 54 | // The stack is used as follows: |
| 55 | // +------------------+ <- stack top |
| 56 | // | coroutine header | <- more claimed as needed in Coroutine_New |
| 57 | // +------------------+ <- |
| 58 | // | coroutine stack | <- |
| 59 | // +------------------+ <- |
| 60 | // | coroutine header | |
| 61 | // +------------------+ |
| 62 | // | coroutine stack | |
| 63 | // +------------------+ |
| 64 | // | coroutine header | |
| 65 | // +------------------+ |
| 66 | // | coroutine stack | |
| 67 | // +------------------+ |
| 68 | // | coroutine header | |
| 69 | // +------------------+ |
| 70 | // | coroutine stack | |
| 71 | // +------------------+ |
| 72 | // | coroutine header | |
| 73 | // +------------------+ |
| 74 | // | startup space | <- set aside by Coroutine_StartSystem |
| 75 | // +------------------+ |
| 76 | // | caller | <- This calls Coroutine_StartSystem etc |
| 77 | // +------------------+ |
| 78 | // | used stack | |
| 79 | // +------------------+ <- stack bottom |
| 80 | |
| 81 | // Each coroutine has this much stack: |
| 82 | #define COROUTINE_STACK_SIZE 16384 |
| 83 | |
| 84 | // When Coroutines is started, an amount of stack is set aside to give |
| 85 | // the caller of Coroutine_StartSystem a bit of room to work before calling |
| 86 | // Coroutine_Run(), that is this amount: |
| 87 | #define COROUTINE_STARTUP_STACK_SIZE 1024 |
| 88 | |
| 89 | typedef struct Coroutine Coroutine; |
| 90 | |
| 91 | typedef void (*Coroutine_YieldCallback)(void *this); |
| 92 | typedef void *(*Coroutine_Start)(void *); |
| 93 | |
| 94 | void Coroutine_StartSystem(); |
| 95 | void Coroutine_StopSystem(); |
| 96 | Coroutine *Coroutine_New(Coroutine_Start start); |
| 97 | void Coroutine_Run_Coroutine(Coroutine *cor, void *value); |
| 98 | void *Coroutine_Run(Coroutine_Start start, void *value); |
| 99 | void Coroutine_Delete(Coroutine *cor); |
| 100 | void Coroutine_Continue(Coroutine *cor, void *value, bool early); |
| 101 | void *Coroutine_Yield(void *value, Coroutine_YieldCallback on_yield, void *this); |
| 102 | void *Coroutine_GetValue(Coroutine *cor); |
| 103 | Coroutine *Coroutine_GetActive(); |
| 104 | bool Coroutine_IsRunning(Coroutine *cor); |
| 105 | |
| 106 | #endif |
| 107 |