diff options
Diffstat (limited to 'coroutine.h')
| -rw-r--r-- | coroutine.h | 131 |
1 files changed, 96 insertions, 35 deletions
diff --git a/coroutine.h b/coroutine.h index 13f9797..afe1b1a 100644 --- a/coroutine.h +++ b/coroutine.h @@ -1,68 +1,129 @@ -/* coroutine.h - Simple coroutine and request/response implementation +/* coroutine.h - Simple embeddable coroutine implementation * * Copyright (C) 2024 Luke T. Shumaker <lukeshu@lukeshu.com> * SPDX-Licence-Identifier: AGPL-3.0-or-later */ +/** + * A coroutine is a cooperatively-multitasked form of threading. + * + * This coroutine.{h,c} form a lightweight coroutine implementation + * for non-multithreaded environments (only one coroutine may be + * running at a time (so no m:n scheduling), coroutine_{add,main} may + * not be called concurrently with eachother). + * + * Unlike many other lightweight or embeddable coroutine + * implementations, coroutine.{h,c} allow coroutines to use the stack + * as normal C functions and do not forbid switch() blocks in + * coroutines. + * + * See also: coroutine_chan.h is a request/response system built on + * top of coroutine.{h,c}. + */ #ifndef _COROUTINE_H_ #define _COROUTINE_H_ #include <stddef.h> /* for size_t */ #include <stdbool.h> /* for bool */ +/* configuration **************************************************************/ + +#define COROUTINE_DEFAULT_STACK_SIZE (8*1024) + /* typedefs *******************************************************************/ -typedef size_t cid_t; /* 0=none; otherwise 1-indexed */ +/** + * A cid_t is a "coroutine ID", used to refer to a coroutine. + * + * May be reused if a coroutine exits. + * + * Valid IDs are `1 <= cid <= COROUTINE_NUM`; `0` is used for + * "none/invalid". + */ +typedef size_t cid_t; -#define COROUTINE __attribute__ ((noreturn, no_split_stack)) void +/** + * The root function for a coroutine; a coroutine function should be + * declared as + * + * COROUTINE myfunc(void *_args) { + * myargtype *args = args; + * cr_begin(); + * + * ... + * + * cr_end(); + * } + * + * The function MUST NOT ever return (GCC enforces this); call + * cr_exit() or cr_end() instead of returning. + * + * When creating a coroutine with coroutine_add(), the bit before + * cr_begin() runs before coroutine_add() returns; if `_args` points + * to a place on another coroutine's stack that may go away, then this + * is an opportunity to copy it to this coroutine's stack. Otherwise + * you shouldn't do anything else before calling cr_begin(). + * Specifically, coroutine_add() and + * cr_{yield,pause_and_yield,exit,end}() are explicitly forbidden to + * call from within a coroutine before cr_begin() (note that the + * cr_chan_*() macros call these functions). + */ typedef void (*cr_fn_t)(void *args); +#define COROUTINE __attribute__ ((noreturn, no_split_stack)) void /* managing coroutines ********************************************************/ -void coroutine_init(void); -cid_t coroutine_add(cr_fn_t fn, void *args); +/** + * Call `fn(args)` in a new coroutine with stack size `stack_size`. + * + * See the doc comment on c_fn_t for the requirements imposed on fn. + * + * May be called from outside any coroutine (before calling + * coroutine_main()) or from inside of a coroutine (after it cas + * called cr_begin()). + * + * Returns the cid of the newly-created coroutine. May return 0 if + * there are already COROUTINE_NUM active coroutines. + */ +__attribute__ ((no_split_stack)) cid_t coroutine_add_with_stack_size(size_t stack_size, cr_fn_t fn, void *args); + +/** + * Like coroutine_add_with_stack_size(), but uses a default stack size so + * you don't need to think about it. + */ +#define coroutine_add(fn, args) coroutine_add_with_stack_size(COROUTINE_DEFAULT_STACK_SIZE, fn, args) + +/** + * The main scheduler loop. + * + * "Should" never return, but will print a message to stderr and + * return if the program has deadlocked and there are no runnable + * coroutines. So be sure to call coroutine_add() at least once + * before calling this. + */ void coroutine_main(void); /* inside of coroutines *******************************************************/ +/** cr_begin() goes at the beginning of a coroutine, after it has initialized its stack. */ __attribute__ ((no_split_stack)) bool cr_begin( void); +/** cr_exit() terminates the currently-running coroutine. */ __attribute__ ((no_split_stack, noreturn)) void cr_exit(void); +/** cr_yield() switches to another coroutine (if there is another runnable coroutine to switch to). */ __attribute__ ((no_split_stack)) void cr_yield(void); +/** cr_pause_and_yield() marks the current coroutine as not-runnable and switches to another coroutine. */ __attribute__ ((no_split_stack)) void cr_pause_and_yield(void); +/** cr_unpause() marks a coroutine as runnable that has previously marked itself as non-runnable with cr_pause_and_yield(). */ __attribute__ ((no_split_stack)) void cr_unpause(cid_t); +/** cr_end() is a counterpart to cr_begin(), but is really just cr_exit(). */ #define cr_end cr_exit +/** cr_getcid() returns the cid of the currently-running coroutine. */ cid_t cr_getcid(void); -/* request/response channels **************************************************/ - -#define cr_chan_t(req_t, resp_t) struct { \ - cid_t requester; \ - cid_t responder; \ - req_t req; \ - resp_t resp; \ - } -#define cr_chan_req(ch, _resp_p, _req) do { \ - (ch)->requester = cr_getcid(); \ - (ch)->req = (_req); \ - if ((ch)->responder != 0) \ - cr_unpause((ch)->responder); \ - cr_pause_and_yield(); \ - if ((typeof(&(ch)->resp))(_resp_p)) \ - *((typeof(&(ch)->resp))(_resp_p)) = (ch)->resp; \ - } while (0) -#define cr_chan_have_req(ch) ((ch)->requester != 0) -#define cr_chan_recv_req(ch, _req_p) do { \ - (ch)->responder = cr_getcid(); \ - if ((ch)->requester == 0) \ - cr_pause_and_yield(); \ - *(_req_p) = (ch)->req; \ - } while (0) -#define cr_chan_send_resp(ch, _resp) do { \ - cr_unpause((ch)->requester); \ - (ch)->responder = 0; \ - (ch)->requester = 0; \ - (ch)->resp = (_resp); \ - } while (0) +/** + * It is not possible for one coroutine to kill another or to mark + * another as paused; a coroutine may only do those things to itself. + */ #endif /* _COROUTINE_H_ */ |