git.ozlabs.org Git - ccan/blob - ccan/coroutine/coroutine.h

   1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
   2 #ifndef CCAN_COROUTINE_H
   3 #define CCAN_COROUTINE_H
   4 /*#define CCAN_COROUTINE_DEBUG 1*/
   5 #include "config.h"
   6
   7 #include <stddef.h>
   8 #include <stdint.h>
   9 #include <stdbool.h>
  10 #include <assert.h>
  11
  12 #include <ccan/compiler/compiler.h>
  13 #include <ccan/typesafe_cb/typesafe_cb.h>
  14
  15 /**
  16  * struct coroutine_stack
  17  *
  18  * Describes a stack suitable for executing a coroutine.  This
  19  * structure is always contained within the stack it describes.
  20  */
  21 struct coroutine_stack {
  22         uint64_t magic;
  23         size_t size;
  24         int valgrind_id;
  25 };
  26
  27 /**
  28  * struct coroutine_state
  29  *
  30  * Describes the state of an in-progress coroutine.
  31  */
  32 struct coroutine_state;
  33
  34 /*
  35  * Stack management
  36  */
  37
  38 /**
  39  * COROUTINE_STK_OVERHEAD - internal stack overhead
  40  *
  41  * Number of bytes of a stack which coroutine needs for its own
  42  * tracking information.
  43  */
  44 #define COROUTINE_STK_OVERHEAD  sizeof(struct coroutine_stack)
  45
  46 /**
  47  * COROUTINE_MIN_STKSZ - Minimum coroutine stack size
  48  *
  49  * Contains the minimum size for a coroutine stack (not including
  50  * overhead).  On systems with MINSTKSZ, guaranteed to be at least as
  51  * large as MINSTKSZ.
  52  */
  53 #define COROUTINE_MIN_STKSZ             2048
  54
  55 /**
  56  * COROUTINE_STACK_MAGIC - Magic number for coroutine stacks
  57  */
  58 #define COROUTINE_STACK_MAGIC           0xc040c040574c574c
  59
  60
  61 /**
  62  * coroutine_stack_init - Prepare a coroutine stack in an existing buffer
  63  * @buf: buffer to use for the coroutine stack
  64  * @bufsize: size of @buf
  65  * @metasize: size of metadata to add to the stack (not including
  66  *            coroutine internal overhead)
  67  *
  68  * Prepares @buf for use as a coroutine stack, returning a
  69  * coroutine_stack *, allocated from within the buffer.  Returns NULL
  70  * on failure.
  71  *
  72  * This will fail if the bufsize < (COROUTINE_MIN_STKSZ +
  73  * COROUTINE_STK_OVERHEAD + metasize).
  74  */
  75 struct coroutine_stack *coroutine_stack_init(void *buf, size_t bufsize,
  76                                              size_t metasize);
  77
  78 /**
  79  * coroutine_stack_release - Stop using a coroutine stack
  80  * @stack: coroutine stack to release
  81  * @metasize: size of metadata
  82  *
  83  * This releases @stack, making it no longer suitable for use as a
  84  * coroutine stack.  @metasize must be equal to the metasize passed to
  85  * coroutine_stack_init.
  86  */
  87 void coroutine_stack_release(struct coroutine_stack *stack, size_t metasize);
  88
  89 /**
  90  * coroutine_stack_check - Validate and return a coroutine stack
  91  * @stack: stack to check
  92  * @abortstr: the location to print on aborting, or NULL.
  93  *
  94  * Debugging check if @stack doesn't appear to be a valid coroutine
  95  * stack, and @abortstr is non-NULL it will be printed and the
  96  * function will abort.
  97  *
  98  * Returns @stack if it appears valid, NULL if not (it can never
  99  * return NULL if @abortstr is set).
 100  */
 101 struct coroutine_stack *coroutine_stack_check(struct coroutine_stack *stack,
 102                                               const char *abortstr);
 103
 104 /**
 105  * coroutine_stack_to_metadata - Returns pointer to user's metadata
 106  *                               allocated within the stack
 107  * @stack: coroutine stack
 108  * @metasize: size of metadata
 109  *
 110  * Returns a pointer to the metadata area within @stack.  This is of
 111  * size given at initialization time, and won't be overwritten by
 112  * coroutines executing on the stack.  It's up to the caller what to
 113  * put in here. @metasize must be equal to the value passed to
 114  * coroutine_stack_init().
 115  */
 116 static inline void *coroutine_stack_to_metadata(struct coroutine_stack *stack,
 117                                                 size_t metasize)
 118 {
 119 #if HAVE_STACK_GROWS_UPWARDS
 120         return (char *)stack - metasize;
 121 #else
 122         return (char *)stack + COROUTINE_STK_OVERHEAD;
 123 #endif
 124 }
 125
 126 /**
 127  * coroutine_stack_from_metadata - Returns pointer to coroutine stack
 128  *                                 pointer given pointer to user metadata
 129  * @metadat: user metadata within a stack
 130  * @metasize: size of metadata
 131  *
 132  * Returns a pointer to the coroutine_stack handle within a stack.
 133  * The argument must be a pointer returned by
 134  * coroutine_stack_to_metadata() at an earlier time. @metasize must be
 135  * equal to the value passed to coroutine_stack_init().
 136  */
 137 static inline struct coroutine_stack *
 138 coroutine_stack_from_metadata(void *metadata, size_t metasize)
 139 {
 140 #if HAVE_STACK_GROWS_UPWARDS
 141         return (struct coroutine_stack *)((char *)metadata + metasize);
 142 #else
 143         return (struct coroutine_stack *)((char *)metadata
 144                                           - COROUTINE_STK_OVERHEAD);
 145 #endif
 146 }
 147
 148 /**
 149  * coroutine_stack_size - Return size of a coroutine stack
 150  * @stack: coroutine stack
 151  *
 152  * Returns the size of the coroutine stack @stack.  This does not
 153  * include the overhead of struct coroutine_stack or metdata.
 154  */
 155 size_t coroutine_stack_size(const struct coroutine_stack *stack);
 156
 157 /*
 158  * Coroutine switching
 159  */
 160
 161 #if HAVE_UCONTEXT
 162 #include <ucontext.h>
 163 #define COROUTINE_AVAILABLE             1
 164 #else
 165 #define COROUTINE_AVAILABLE             0
 166 #endif
 167
 168 struct coroutine_state {
 169 #if HAVE_UCONTEXT
 170         ucontext_t uc;
 171 #endif /* HAVE_UCONTEXT */
 172 };
 173
 174 #if COROUTINE_AVAILABLE
 175
 176 /**
 177  * coroutine_init - Prepare a coroutine for execution
 178  * @cs: coroutine_state structure to initialize
 179  * @fn: function to start executing in the coroutine
 180  * @arg: argument for @fn
 181  * @stack: stack to use for the coroutine
 182  *
 183  * Prepares @cs as a new coroutine which will execute starting with
 184  * function @fn, using stack @stack.
 185  */
 186 void coroutine_init_(struct coroutine_state *cs,
 187                      void (*fn)(void *), void *arg,
 188                      struct coroutine_stack *stack);
 189 #define coroutine_init(cs, fn, arg, stack)                              \
 190         coroutine_init_((cs),                                           \
 191                         typesafe_cb(void, void *, (fn), (arg)),         \
 192                         (arg), (stack))
 193
 194 /**
 195  * coroutine_jump - Irreversibly switch to executing a coroutine
 196  * @to: coroutine to switch to
 197  *
 198  * Immediately jump to executing coroutine @to (at whatever point in
 199  * execution it was up to).  Never returns.
 200  */
 201 void NORETURN coroutine_jump(const struct coroutine_state *to);
 202
 203 /**
 204  * coroutine_switch - Switch coroutines
 205  * @from: coroutine in which to store current execution state
 206  * @to: coroutine to switch to
 207  *
 208  * Stop executing the current routine, saving its state in @from, and
 209  * switch to executing the coroutine @to.  Returns only when something
 210  * switches or jumps back to @from.
 211  */
 212 void coroutine_switch(struct coroutine_state *from,
 213                       const struct coroutine_state *to);
 214
 215 #else
 216
 217 static inline void coroutine_init(struct coroutine_state *cs,
 218                                   void (*fn)(void *), void *arg,
 219                                   struct coroutine_stack *stack)
 220 {
 221         assert(0);
 222 }
 223
 224 static inline void NORETURN coroutine_jump(const struct coroutine_state *to)
 225 {
 226         assert(0);
 227 }
 228
 229 static inline void coroutine_switch(struct coroutine_state *from,
 230                                     const struct coroutine_state *to)
 231 {
 232         assert(0);
 233 }
 234
 235 #endif /* !COROUTINE_AVAILABLE */
 236
 237 #endif /* CCAN_COROUTINE_H */