… | |
… | |
75 | * 2011-06-08 maybe properly implement weird windows amd64 calling conventions. |
75 | * 2011-06-08 maybe properly implement weird windows amd64 calling conventions. |
76 | * 2011-07-03 rely on __GCC_HAVE_DWARF2_CFI_ASM for cfi detection. |
76 | * 2011-07-03 rely on __GCC_HAVE_DWARF2_CFI_ASM for cfi detection. |
77 | * 2011-08-08 cygwin trashes stacks, use pthreads with double stack on cygwin. |
77 | * 2011-08-08 cygwin trashes stacks, use pthreads with double stack on cygwin. |
78 | * 2012-12-04 reduce misprediction penalty for x86/amd64 assembly switcher. |
78 | * 2012-12-04 reduce misprediction penalty for x86/amd64 assembly switcher. |
79 | * 2012-12-05 experimental fiber backend (allocates stack twice). |
79 | * 2012-12-05 experimental fiber backend (allocates stack twice). |
|
|
80 | * 2012-12-07 API version 3 - add coro_stack_alloc/coro_stack_free. |
80 | */ |
81 | */ |
81 | |
82 | |
82 | #ifndef CORO_H |
83 | #ifndef CORO_H |
83 | #define CORO_H |
84 | #define CORO_H |
84 | |
85 | |
85 | #if __cplusplus |
86 | #if __cplusplus |
86 | extern "C" { |
87 | extern "C" { |
87 | #endif |
88 | #endif |
88 | |
89 | |
89 | #define CORO_VERSION 2 |
|
|
90 | |
|
|
91 | /* |
|
|
92 | * Changes since API version 1: |
|
|
93 | * replaced bogus -DCORO_LOOSE with gramatically more correct -DCORO_LOSER |
|
|
94 | */ |
|
|
95 | |
|
|
96 | /* |
90 | /* |
97 | * This library consists of only three files |
91 | * This library consists of only three files |
98 | * coro.h, coro.c and LICENSE (and optionally README) |
92 | * coro.h, coro.c and LICENSE (and optionally README) |
99 | * |
93 | * |
100 | * It implements what is known as coroutines, in a hopefully |
94 | * It implements what is known as coroutines, in a hopefully |
101 | * portable way. At the moment you have to define which kind |
95 | * portable way. |
102 | * of implementation flavour you want: |
96 | * |
|
|
97 | * All compiletime symbols must be defined both when including coro.h |
|
|
98 | * (using libcoro) as well as when compiling coro.c (the implementation). |
|
|
99 | * |
|
|
100 | * You can manually specify which flavour you want. If you don't define |
|
|
101 | * any of these, libcoro tries to choose a safe and fast default: |
103 | * |
102 | * |
104 | * -DCORO_UCONTEXT |
103 | * -DCORO_UCONTEXT |
105 | * |
104 | * |
106 | * This flavour uses SUSv2's get/set/swap/makecontext functions that |
105 | * This flavour uses SUSv2's get/set/swap/makecontext functions that |
107 | * unfortunately only newer unices support. |
106 | * unfortunately only some unices support, and is quite slow. |
108 | * |
107 | * |
109 | * -DCORO_SJLJ |
108 | * -DCORO_SJLJ |
110 | * |
109 | * |
111 | * This flavour uses SUSv2's setjmp/longjmp and sigaltstack functions to |
110 | * This flavour uses SUSv2's setjmp/longjmp and sigaltstack functions to |
112 | * do it's job. Coroutine creation is much slower than UCONTEXT, but |
111 | * do it's job. Coroutine creation is much slower than UCONTEXT, but |
113 | * context switching is often a bit cheaper. It should work on almost |
112 | * context switching is a bit cheaper. It should work on almost all unices. |
114 | * all unices. |
|
|
115 | * |
113 | * |
116 | * -DCORO_LINUX |
114 | * -DCORO_LINUX |
117 | * |
115 | * |
|
|
116 | * CORO_SJLJ variant. |
118 | * Old GNU/Linux systems (<= glibc-2.1) only work with this implementation |
117 | * Old GNU/Linux systems (<= glibc-2.1) only work with this implementation |
119 | * (it is very fast and therefore recommended over other methods, but |
118 | * (it is very fast and therefore recommended over other methods, but |
120 | * doesn't work with anything newer). |
119 | * doesn't work with anything newer). |
121 | * |
120 | * |
122 | * -DCORO_LOSER |
121 | * -DCORO_LOSER |
123 | * |
122 | * |
|
|
123 | * CORO_SJLJ variant. |
124 | * Microsoft's highly proprietary platform doesn't support sigaltstack, and |
124 | * Microsoft's highly proprietary platform doesn't support sigaltstack, and |
125 | * this automatically selects a suitable workaround for this platform. |
125 | * this selects a suitable workaround for this platform. It might not work |
126 | * (untested) |
126 | * with your compiler though - it has only been tested with MSVC 6. |
127 | * |
127 | * |
128 | * -DCORO_FIBER |
128 | * -DCORO_FIBER |
129 | * |
129 | * |
130 | * slower, but probably more portable variant for the Microsoft operating |
130 | * Slower, but probably more portable variant for the Microsoft operating |
131 | * system, using fibers. ignores your stack. |
131 | * system, using fibers. Ignores the passed stack and allocates it internally. |
|
|
132 | * Also, due to bugs in cygwin, this does not work with cygwin. |
132 | * |
133 | * |
133 | * -DCORO_IRIX |
134 | * -DCORO_IRIX |
134 | * |
135 | * |
|
|
136 | * CORO_SJLJ variant. |
135 | * SGI's version of Microsoft's NT ;) |
137 | * For SGI's version of Microsoft's NT ;) |
136 | * |
138 | * |
137 | * -DCORO_ASM |
139 | * -DCORO_ASM |
138 | * |
140 | * |
139 | * Handcoded assembly, known to work only on a few architectures/ABI: |
141 | * Hand coded assembly, known to work only on a few architectures/ABI: |
140 | * GCC + x86/IA32 and amd64/x86_64 + GNU/Linux and a few BSDs. |
142 | * GCC + x86/IA32 and amd64/x86_64 + GNU/Linux and a few BSDs. Fastest choice, |
|
|
143 | * if it works. |
141 | * |
144 | * |
142 | * -DCORO_PTHREAD |
145 | * -DCORO_PTHREAD |
143 | * |
146 | * |
144 | * Use the pthread API. You have to provide <pthread.h> and -lpthread. |
147 | * Use the pthread API. You have to provide <pthread.h> and -lpthread. |
145 | * This is likely the slowest backend, and it also does not support fork(), |
148 | * This is likely the slowest backend, and it also does not support fork(), |
146 | * so avoid it at all costs. |
149 | * so avoid it at all costs. |
147 | * |
150 | * |
148 | * If you define neither of these symbols, coro.h will try to autodetect |
151 | * If you define neither of these symbols, coro.h will try to autodetect |
149 | * the model. This currently works for CORO_LOSER only. For the other |
152 | * the best/safest model. To help with the autodetection, you should check |
150 | * alternatives you should check (e.g. using autoconf) and define the |
153 | * (e.g. using autoconf) and define the following symbols: HAVE_UCONTEXT_H |
151 | * following symbols: HAVE_UCONTEXT_H / HAVE_SETJMP_H / HAVE_SIGALTSTACK. |
154 | * / HAVE_SETJMP_H / HAVE_SIGALTSTACK. |
|
|
155 | */ |
|
|
156 | |
|
|
157 | /* |
|
|
158 | * Changes when the API changes incompatibly. |
|
|
159 | * This is ONLY the API version - there is no ABI compatibility between releases. |
152 | */ |
160 | * |
|
|
161 | * Changes in API version 2: |
|
|
162 | * replaced bogus -DCORO_LOOSE with grammatically more correct -DCORO_LOSER |
|
|
163 | * Changes in API version 3: |
|
|
164 | * introduced stack management (CORO_STACKALLOC) |
|
|
165 | */ |
|
|
166 | #define CORO_VERSION 3 |
|
|
167 | |
|
|
168 | #include <stddef.h> |
153 | |
169 | |
154 | /* |
170 | /* |
155 | * This is the type for the initialization function of a new coroutine. |
171 | * This is the type for the initialization function of a new coroutine. |
156 | */ |
172 | */ |
157 | typedef void (*coro_func)(void *); |
173 | typedef void (*coro_func)(void *); |
… | |
… | |
168 | * uninitialised coro_context, it expects a pointer to the entry function |
184 | * uninitialised coro_context, it expects a pointer to the entry function |
169 | * and the single pointer value that is given to it as argument. |
185 | * and the single pointer value that is given to it as argument. |
170 | * |
186 | * |
171 | * Allocating/deallocating the stack is your own responsibility. |
187 | * Allocating/deallocating the stack is your own responsibility. |
172 | * |
188 | * |
173 | * As a special case, if coro, arg, sptr and ssize are all zero, |
189 | * As a special case, if coro, arg, sptr and ssze are all zero, |
174 | * then an "empty" coro_context will be created that is suitable |
190 | * then an "empty" coro_context will be created that is suitable |
175 | * as an initial source for coro_transfer. |
191 | * as an initial source for coro_transfer. |
176 | * |
192 | * |
177 | * This function is not reentrant, but putting a mutex around it |
193 | * This function is not reentrant, but putting a mutex around it |
178 | * will work. |
194 | * will work. |
179 | */ |
195 | */ |
180 | void coro_create (coro_context *ctx, /* an uninitialised coro_context */ |
196 | void coro_create (coro_context *ctx, /* an uninitialised coro_context */ |
181 | coro_func coro, /* the coroutine code to be executed */ |
197 | coro_func coro, /* the coroutine code to be executed */ |
182 | void *arg, /* a single pointer passed to the coro */ |
198 | void *arg, /* a single pointer passed to the coro */ |
183 | void *sptr, /* start of stack area */ |
199 | void *sptr, /* start of stack area */ |
184 | long ssize); /* size of stack area */ |
200 | size_t ssze); /* size of stack area in bytes */ |
185 | |
201 | |
186 | /* |
202 | /* |
187 | * The following prototype defines the coroutine switching function. It is |
203 | * The following prototype defines the coroutine switching function. It is |
188 | * usually implemented as a macro, so watch out. |
204 | * sometimes implemented as a macro, so watch out. |
189 | * |
205 | * |
190 | * This function is thread-safe and reentrant. |
206 | * This function is thread-safe and reentrant. |
191 | */ |
207 | */ |
192 | #if 0 |
208 | #if 0 |
193 | void coro_transfer (coro_context *prev, coro_context *next); |
209 | void coro_transfer (coro_context *prev, coro_context *next); |
194 | #endif |
210 | #endif |
195 | |
211 | |
196 | /* |
212 | /* |
197 | * The following prototype defines the coroutine destroy function. It is |
213 | * The following prototype defines the coroutine destroy function. It |
198 | * usually implemented as a macro, so watch out. It also serves |
214 | * is sometimes implemented as a macro, so watch out. It also serves no |
199 | * no purpose unless you want to use the CORO_PTHREAD backend, |
215 | * purpose unless you want to use the CORO_PTHREAD backend, where it is |
200 | * where it is used to clean up the thread. You are responsible |
216 | * used to clean up the thread. You are responsible for freeing the stack |
201 | * for freeing the stack and the context itself. |
217 | * and the context itself. |
202 | * |
218 | * |
203 | * This function is thread-safe and reentrant. |
219 | * This function is thread-safe and reentrant. |
204 | */ |
220 | */ |
205 | #if 0 |
221 | #if 0 |
206 | void coro_destroy (coro_context *ctx); |
222 | void coro_destroy (coro_context *ctx); |
207 | #endif |
223 | #endif |
208 | |
224 | |
|
|
225 | /*****************************************************************************/ |
|
|
226 | /* optional stack management */ |
|
|
227 | /*****************************************************************************/ |
209 | /* |
228 | /* |
210 | * That was it. No other user-visible functions are implemented here. |
229 | * You can disable all of the stack management functions by |
|
|
230 | * defining CORO_STACKALLOC to 0. Otherwise, they are enabled by default. |
|
|
231 | * |
|
|
232 | * If stack management is enabled, you can influence the implementation via these |
|
|
233 | * symbols: |
|
|
234 | * |
|
|
235 | * -DCORO_USE_VALGRIND |
|
|
236 | * |
|
|
237 | * If defined, then libcoro will include valgrind/valgrind.h and register |
|
|
238 | * and unregister stacks with valgrind. |
|
|
239 | * |
|
|
240 | * -DCORO_GUARDPAGES=n |
|
|
241 | * |
|
|
242 | * libcoro will try to use the specified number of guard pages to protect against |
|
|
243 | * stack overflow. If n is 0, then the feature will be disabled. If it isn't |
|
|
244 | * defined, then libcoro will choose a suitable default. If guardpages are not |
|
|
245 | * supported on the platform, then the feature will be silently disabled. |
|
|
246 | */ |
|
|
247 | #ifndef CORO_STACKALLOC |
|
|
248 | # define CORO_STACKALLOC 1 |
|
|
249 | #endif |
|
|
250 | |
|
|
251 | #if CORO_STACKALLOC |
|
|
252 | |
|
|
253 | /* |
|
|
254 | * The only allowed operations on these struct members is to read the |
|
|
255 | * "sptr" and "ssze" members to pass it to coro_create, to read the "sptr" |
|
|
256 | * member to see if it is false, in which case the stack isn't allocated, |
|
|
257 | * and to set the "sptr" member to 0, to indicate to coro_stack_free to |
|
|
258 | * not actually do anything. |
|
|
259 | */ |
|
|
260 | |
|
|
261 | struct coro_stack |
|
|
262 | { |
|
|
263 | void *sptr; |
|
|
264 | size_t ssze; |
|
|
265 | #if CORO_USE_VALGRIND |
|
|
266 | int valgrind_id; |
|
|
267 | #endif |
|
|
268 | }; |
|
|
269 | |
|
|
270 | /* |
|
|
271 | * Try to allocate a stack of at least the given size and return true if |
|
|
272 | * successful, or false otherwise. |
|
|
273 | * |
|
|
274 | * The size is *NOT* specified in bytes, but in units of sizeof (void *), |
|
|
275 | * i.e. the stack is typically 4(8) times larger on 32 bit(64 bit) platforms |
|
|
276 | * then the size passed in. |
|
|
277 | * |
|
|
278 | * If size is 0, then a "suitable" stack size is chosen (usually 1-2MB). |
|
|
279 | */ |
|
|
280 | int coro_stack_alloc (struct coro_stack *stack, unsigned int size); |
|
|
281 | |
|
|
282 | /* |
|
|
283 | * Free the stack allocated by coro_stack_alloc again. It is safe to |
|
|
284 | * call this function on the coro_stack structure even if coro_stack_alloc |
|
|
285 | * failed. |
|
|
286 | */ |
|
|
287 | void coro_stack_free (struct coro_stack *stack); |
|
|
288 | |
|
|
289 | #endif |
|
|
290 | |
|
|
291 | /* |
|
|
292 | * That was it. No other user-serviceable parts below here. |
211 | */ |
293 | */ |
212 | |
294 | |
213 | /*****************************************************************************/ |
295 | /*****************************************************************************/ |
214 | |
296 | |
215 | #if !defined CORO_LOSER && !defined CORO_UCONTEXT \ |
297 | #if !defined CORO_LOSER && !defined CORO_UCONTEXT \ |
… | |
… | |
235 | |
317 | |
236 | #if CORO_UCONTEXT |
318 | #if CORO_UCONTEXT |
237 | |
319 | |
238 | # include <ucontext.h> |
320 | # include <ucontext.h> |
239 | |
321 | |
240 | struct coro_context { |
322 | struct coro_context |
|
|
323 | { |
241 | ucontext_t uc; |
324 | ucontext_t uc; |
242 | }; |
325 | }; |
243 | |
326 | |
244 | # define coro_transfer(p,n) swapcontext (&((p)->uc), &((n)->uc)) |
327 | # define coro_transfer(p,n) swapcontext (&((p)->uc), &((n)->uc)) |
245 | # define coro_destroy(ctx) (void *)(ctx) |
328 | # define coro_destroy(ctx) (void *)(ctx) |
246 | |
329 | |
247 | #elif CORO_SJLJ || CORO_LOSER || CORO_LINUX || CORO_IRIX |
330 | #elif CORO_SJLJ || CORO_LOSER || CORO_LINUX || CORO_IRIX |
248 | |
331 | |
249 | # if defined(CORO_LINUX) && !defined(_GNU_SOURCE) |
332 | # if defined(CORO_LINUX) && !defined(_GNU_SOURCE) |
250 | # define _GNU_SOURCE /* for linux libc */ |
333 | # define _GNU_SOURCE /* for glibc */ |
251 | # endif |
334 | # endif |
252 | |
335 | |
253 | # if !CORO_LOSER |
336 | # if !CORO_LOSER |
254 | # include <unistd.h> |
337 | # include <unistd.h> |
255 | # endif |
338 | # endif |
… | |
… | |
274 | # define coro_jmp_buf sigjmp_buf |
357 | # define coro_jmp_buf sigjmp_buf |
275 | # define coro_setjmp(env) sigsetjmp (env, 0) |
358 | # define coro_setjmp(env) sigsetjmp (env, 0) |
276 | # define coro_longjmp(env) siglongjmp ((env), 1) |
359 | # define coro_longjmp(env) siglongjmp ((env), 1) |
277 | # endif |
360 | # endif |
278 | |
361 | |
279 | struct coro_context { |
362 | struct coro_context |
|
|
363 | { |
280 | coro_jmp_buf env; |
364 | coro_jmp_buf env; |
281 | }; |
365 | }; |
282 | |
366 | |
283 | # define coro_transfer(p,n) do { if (!coro_setjmp ((p)->env)) coro_longjmp ((n)->env); } while (0) |
367 | # define coro_transfer(p,n) do { if (!coro_setjmp ((p)->env)) coro_longjmp ((n)->env); } while (0) |
284 | # define coro_destroy(ctx) (void *)(ctx) |
368 | # define coro_destroy(ctx) (void *)(ctx) |
285 | |
369 | |
286 | #elif CORO_ASM |
370 | #elif CORO_ASM |
287 | |
371 | |
288 | struct coro_context { |
372 | struct coro_context |
|
|
373 | { |
289 | void **sp; /* must be at offset 0 */ |
374 | void **sp; /* must be at offset 0 */ |
290 | }; |
375 | }; |
291 | |
376 | |
292 | void __attribute__ ((__noinline__, __regparm__(2))) |
377 | void __attribute__ ((__noinline__, __regparm__(2))) |
293 | coro_transfer (coro_context *prev, coro_context *next); |
378 | coro_transfer (coro_context *prev, coro_context *next); |
… | |
… | |
298 | |
383 | |
299 | # include <pthread.h> |
384 | # include <pthread.h> |
300 | |
385 | |
301 | extern pthread_mutex_t coro_mutex; |
386 | extern pthread_mutex_t coro_mutex; |
302 | |
387 | |
303 | struct coro_context { |
388 | struct coro_context |
|
|
389 | { |
304 | pthread_cond_t cv; |
390 | pthread_cond_t cv; |
305 | pthread_t id; |
391 | pthread_t id; |
306 | }; |
392 | }; |
307 | |
393 | |
308 | void coro_transfer (coro_context *prev, coro_context *next); |
394 | void coro_transfer (coro_context *prev, coro_context *next); |
309 | void coro_destroy (coro_context *ctx); |
395 | void coro_destroy (coro_context *ctx); |
310 | |
396 | |
311 | #elif CORO_FIBER |
397 | #elif CORO_FIBER |
312 | |
398 | |
313 | struct coro_context { |
399 | struct coro_context |
|
|
400 | { |
314 | void *fiber; |
401 | void *fiber; |
315 | /* only used for initialisation */ |
402 | /* only used for initialisation */ |
316 | coro_func coro; |
403 | coro_func coro; |
317 | void *arg; |
404 | void *arg; |
318 | }; |
405 | }; |
319 | |
406 | |
|
|
407 | void coro_transfer (coro_context *prev, coro_context *next); |
|
|
408 | void coro_destroy (coro_context *ctx); |
|
|
409 | |
320 | #endif |
410 | #endif |
321 | |
411 | |
322 | #if __cplusplus |
412 | #if __cplusplus |
323 | } |
413 | } |
324 | #endif |
414 | #endif |