diff options
Diffstat (limited to 'libcr/include')
-rw-r--r-- | libcr/include/libcr/coroutine.h | 38 |
1 files changed, 32 insertions, 6 deletions
diff --git a/libcr/include/libcr/coroutine.h b/libcr/include/libcr/coroutine.h index 589664f..f0e6e61 100644 --- a/libcr/include/libcr/coroutine.h +++ b/libcr/include/libcr/coroutine.h @@ -83,7 +83,15 @@ typedef void (*cr_fn_t)(void *args); /* managing coroutines ********************************************************/ /** - * Call `fn(args)` in a new coroutine with stack size `stack_size`. + * Call `fn(args)` in a new coroutine with the `full_stack_size`-sized + * block of memory `stack` as the coroutine stack. + * + * There may be CPU-specific requirements on the alignment of the + * `stack` pointer. + * + * If CONFIG_COROUTINE_PROTECT_STACK: The usable stack size will be + * slightly less than `full_stack_size`, in order to make room for a + * stack guard at each end. * * See the doc comment on c_fn_t for the requirements imposed on fn. * @@ -94,17 +102,35 @@ typedef void (*cr_fn_t)(void *args); * Returns the cid of the newly-created coroutine. May return 0 if * there are already COROUTINE_NUM active coroutines. */ -cid_t coroutine_add_with_stack_size(size_t stack_size, const char *name, cr_fn_t fn, void *args); +cid_t coroutine_add_with_stack(void *stack, size_t full_stack_size, const char *name, cr_fn_t fn, void *args); + +/** + * Like coroutine_add_with_stack(), but will use aligned_alloc() to + * allocate a block of memory to use as the stack. + * + * If CONFIG_COROUTINE_PROTECT_STACK: `usable_stack_size` does *not* + * include the size of the stack guard at each end; the amount of + * memory allocated for the stack will be slightly larger than + * `usable_stack_size`. + */ +cid_t coroutine_add_with_stack_size(size_t usable_stack_size, const char *name, 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. * - * Either define CONFIG_COROUTINE_STACK_SIZE_DEFAULT to use for all - * coroutines, or CONFIG_COROUTINE_STACK_SIZE_{fn} for each COROUTINE - * function. + * Either: + * - define CONFIG_COROUTINE_STACK_SIZE_DEFAULT to use for all + * coroutines; or + * - define/declare CONFIG_COROUTINE_STACK_SIZE_{fn} for each COROUTINE + * function; or + * - define CONFIG_COROUTINE_STACK_PREALLOCATE and then + * define/declare COROUTINE_STACK_{fn} and COROUTINE_STACK_{fn}_len + * for each COROUTINE function. */ -#ifdef CONFIG_COROUTINE_STACK_SIZE_DEFAULT +#if defined(CONFIG_COROUTINE_STACK_PREALLOCATE) +#define coroutine_add(name, fn, args) coroutine_add_with_stack(COROUTINE_STACK_##fn, COROUTINE_STACK_##fn##_len, name, fn, args) +#elif defined(CONFIG_COROUTINE_STACK_SIZE_DEFAULT) #define coroutine_add(name, fn, args) coroutine_add_with_stack_size(CONFIG_COROUTINE_STACK_SIZE_DEFAULT, name, fn, args) #else #define coroutine_add(name, fn, args) coroutine_add_with_stack_size(CONFIG_COROUTINE_STACK_SIZE_##fn, name, fn, args) |