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*/
12 #include <ccan/compiler/compiler.h>
13 #include <ccan/typesafe_cb/typesafe_cb.h>
16 * struct coroutine_stack
18 * Describes a stack suitable for executing a coroutine. This
19 * structure is always contained within the stack it describes.
21 struct coroutine_stack;
24 * struct coroutine_state
26 * Describes the state of an in-progress coroutine.
28 struct coroutine_state;
35 * COROUTINE_STK_OVERHEAD - internal stack overhead
37 * Number of bytes of a stack which coroutine needs for its own
38 * tracking information.
40 #define COROUTINE_STK_OVERHEAD (sizeof(uint64_t) + sizeof(size_t))
43 * COROUTINE_MIN_STKSZ - Minimum coroutine stack size
45 * Contains the minimum size for a coroutine stack (not including
46 * overhead). On systems with MINSTKSZ, guaranteed to be at least as
49 #define COROUTINE_MIN_STKSZ 2048
52 * COROUTINE_STACK_MAGIC - Magic number for coroutine stacks
54 #define COROUTINE_STACK_MAGIC 0xc040c040574c574c
58 * coroutine_stack_init - Prepare a coroutine stack in an existing buffer
59 * @buf: buffer to use for the coroutine stack
60 * @bufsize: size of @buf
61 * @metasize: size of metadata to add to the stack (not including
62 * coroutine internal overhead)
64 * Prepares @buf for use as a coroutine stack, returning a
65 * coroutine_stack *, allocated from within the buffer. Returns NULL
68 * This will fail if the bufsize < (COROUTINE_MIN_STKSZ +
69 * COROUTINE_STK_OVERHEAD + metasize).
71 struct coroutine_stack *coroutine_stack_init(void *buf, size_t bufsize,
75 * coroutine_stack_release - Stop using a coroutine stack
76 * @stack: coroutine stack to release
77 * @metasize: size of metadata
79 * This releases @stack, making it no longer suitable for use as a
80 * coroutine stack. @metasize must be equal to the metasize passed to
81 * coroutine_stack_init.
83 void coroutine_stack_release(struct coroutine_stack *stack, size_t metasize);
86 * coroutine_stack_check - Validate and return a coroutine stack
87 * @stack: stack to check
88 * @abortstr: the location to print on aborting, or NULL.
90 * Debugging check if @stack doesn't appear to be a valid coroutine
91 * stack, and @abortstr is non-NULL it will be printed and the
92 * function will abort.
94 * Returns @stack if it appears valid, NULL if not (it can never
95 * return NULL if @abortstr is set).
97 struct coroutine_stack *coroutine_stack_check(struct coroutine_stack *stack,
98 const char *abortstr);
101 * coroutine_stack_to_metadata - Returns pointer to user's metadata
102 * allocated within the stack
103 * @stack: coroutine stack
104 * @metasize: size of metadata
106 * Returns a pointer to the metadata area within @stack. This is of
107 * size given at initialization time, and won't be overwritten by
108 * coroutines executing on the stack. It's up to the caller what to
109 * put in here. @metasize must be equal to the value passed to
110 * coroutine_stack_init().
112 static inline void *coroutine_stack_to_metadata(struct coroutine_stack *stack,
115 #if HAVE_STACK_GROWS_UPWARDS
116 return (char *)stack - metasize;
118 return (char *)stack + COROUTINE_STK_OVERHEAD;
123 * coroutine_stack_from_metadata - Returns pointer to coroutine stack
124 * pointer given pointer to user metadata
125 * @metadat: user metadata within a stack
126 * @metasize: size of metadata
128 * Returns a pointer to the coroutine_stack handle within a stack.
129 * The argument must be a pointer returned by
130 * coroutine_stack_to_metadata() at an earlier time. @metasize must be
131 * equal to the value passed to coroutine_stack_init().
133 static inline struct coroutine_stack *
134 coroutine_stack_from_metadata(void *metadata, size_t metasize)
136 #if HAVE_STACK_GROWS_UPWARDS
137 return (struct coroutine_stack *)((char *)metadata + metasize);
139 return (struct coroutine_stack *)((char *)metadata
140 - COROUTINE_STK_OVERHEAD);
145 * coroutine_stack_size - Return size of a coroutine stack
146 * @stack: coroutine stack
148 * Returns the size of the coroutine stack @stack. This does not
149 * include the overhead of struct coroutine_stack or metdata.
151 size_t coroutine_stack_size(const struct coroutine_stack *stack);
154 * Coroutine switching
158 #include <ucontext.h>
159 #define COROUTINE_AVAILABLE 1
161 #define COROUTINE_AVAILABLE 0
164 struct coroutine_state {
167 #endif /* HAVE_UCONTEXT */
170 #if COROUTINE_AVAILABLE
173 * coroutine_init - Prepare a coroutine for execution
174 * @cs: coroutine_state structure to initialize
175 * @fn: function to start executing in the coroutine
176 * @arg: argument for @fn
177 * @stack: stack to use for the coroutine
179 * Prepares @cs as a new coroutine which will execute starting with
180 * function @fn, using stack @stack.
182 void coroutine_init_(struct coroutine_state *cs,
183 void (*fn)(void *), void *arg,
184 struct coroutine_stack *stack);
185 #define coroutine_init(cs, fn, arg, stack) \
186 coroutine_init_((cs), \
187 typesafe_cb(void, void *, (fn), (arg)), \
191 * coroutine_jump - Irreversibly switch to executing a coroutine
192 * @to: coroutine to switch to
194 * Immediately jump to executing coroutine @to (at whatever point in
195 * execution it was up to). Never returns.
197 void NORETURN coroutine_jump(const struct coroutine_state *to);
200 * coroutine_switch - Switch coroutines
201 * @from: coroutine in which to store current execution state
202 * @to: coroutine to switch to
204 * Stop executing the current routine, saving its state in @from, and
205 * switch to executing the coroutine @to. Returns only when something
206 * switches or jumps back to @from.
208 void coroutine_switch(struct coroutine_state *from,
209 const struct coroutine_state *to);
213 static inline void coroutine_init(struct coroutine_state *cs,
214 void (*fn)(void *), void *arg,
215 struct coroutine_stack *stack)
220 static inline void NORETURN coroutine_jump(const struct coroutine_state *to)
225 static inline void coroutine_switch(struct coroutine_state *from,
226 const struct coroutine_state *to)
231 #endif /* !COROUTINE_AVAILABLE */
233 #endif /* CCAN_COROUTINE_H */