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 {
28 * struct coroutine_state
30 * Describes the state of an in-progress coroutine.
32 struct coroutine_state;
39 * COROUTINE_STK_OVERHEAD - internal stack overhead
41 * Number of bytes of a stack which coroutine needs for its own
42 * tracking information.
44 #define COROUTINE_STK_OVERHEAD sizeof(struct coroutine_stack)
47 * COROUTINE_MIN_STKSZ - Minimum coroutine stack size
49 * Contains the minimum size for a coroutine stack (not including
50 * overhead). On systems with MINSTKSZ, guaranteed to be at least as
53 #define COROUTINE_MIN_STKSZ 2048
56 * COROUTINE_STACK_MAGIC - Magic number for coroutine stacks
58 #define COROUTINE_STACK_MAGIC 0xc040c040574c574c
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)
68 * Prepares @buf for use as a coroutine stack, returning a
69 * coroutine_stack *, allocated from within the buffer. Returns NULL
72 * This will fail if the bufsize < (COROUTINE_MIN_STKSZ +
73 * COROUTINE_STK_OVERHEAD + metasize).
75 struct coroutine_stack *coroutine_stack_init(void *buf, size_t bufsize,
79 * coroutine_stack_release - Stop using a coroutine stack
80 * @stack: coroutine stack to release
81 * @metasize: size of metadata
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.
87 void coroutine_stack_release(struct coroutine_stack *stack, size_t metasize);
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.
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.
98 * Returns @stack if it appears valid, NULL if not (it can never
99 * return NULL if @abortstr is set).
101 struct coroutine_stack *coroutine_stack_check(struct coroutine_stack *stack,
102 const char *abortstr);
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
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().
116 static inline void *coroutine_stack_to_metadata(struct coroutine_stack *stack,
119 #if HAVE_STACK_GROWS_UPWARDS
120 return (char *)stack - metasize;
122 return (char *)stack + COROUTINE_STK_OVERHEAD;
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
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().
137 static inline struct coroutine_stack *
138 coroutine_stack_from_metadata(void *metadata, size_t metasize)
140 #if HAVE_STACK_GROWS_UPWARDS
141 return (struct coroutine_stack *)((char *)metadata + metasize);
143 return (struct coroutine_stack *)((char *)metadata
144 - COROUTINE_STK_OVERHEAD);
149 * coroutine_stack_size - Return size of a coroutine stack
150 * @stack: coroutine stack
152 * Returns the size of the coroutine stack @stack. This does not
153 * include the overhead of struct coroutine_stack or metdata.
155 size_t coroutine_stack_size(const struct coroutine_stack *stack);
158 * Coroutine switching
162 #include <ucontext.h>
163 #define COROUTINE_AVAILABLE 1
165 #define COROUTINE_AVAILABLE 0
168 struct coroutine_state {
171 #endif /* HAVE_UCONTEXT */
174 #if COROUTINE_AVAILABLE
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
183 * Prepares @cs as a new coroutine which will execute starting with
184 * function @fn, using stack @stack.
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)), \
195 * coroutine_jump - Irreversibly switch to executing a coroutine
196 * @to: coroutine to switch to
198 * Immediately jump to executing coroutine @to (at whatever point in
199 * execution it was up to). Never returns.
201 void NORETURN coroutine_jump(const struct coroutine_state *to);
204 * coroutine_switch - Switch coroutines
205 * @from: coroutine in which to store current execution state
206 * @to: coroutine to switch to
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.
212 void coroutine_switch(struct coroutine_state *from,
213 const struct coroutine_state *to);
217 static inline void coroutine_init(struct coroutine_state *cs,
218 void (*fn)(void *), void *arg,
219 struct coroutine_stack *stack)
224 static inline void NORETURN coroutine_jump(const struct coroutine_state *to)
229 static inline void coroutine_switch(struct coroutine_state *from,
230 const struct coroutine_state *to)
235 #endif /* !COROUTINE_AVAILABLE */
237 #endif /* CCAN_COROUTINE_H */