Lely core libraries
2.3.4
|
Go to the source code of this file.
Macros | |
#define | FIBER_SAVE_MASK 0x1 |
A flag specifying a fiber to save and restore the signal mask (only supported on POSIX platforms). | |
#define | FIBER_SAVE_FENV 0x2 |
A flag specifying a fiber to save and restore the floating-point environment. | |
#define | FIBER_SAVE_ERROR 0x4 |
A flag specifying a fiber to save and restore the error values (i.e., errno and GetLastError() on Windows). | |
#define | FIBER_SAVE_ALL (FIBER_SAVE_MASK | FIBER_SAVE_FENV | FIBER_SAVE_ERROR) |
A combination of those flags in FIBER_SAVE_MASK, FIBER_SAVE_FENV and FIBER_SAVE_ERROR that are supported on the platform. | |
#define | FIBER_GUARD_STACK 0x8 |
A flag specifying a fiber to add a guard page when allocating the stack frame so that the kernel generates a SIGSEGV signal on stack overflow (only supported on those POSIX platforms where mmap() supports anonymous mappings). More... | |
Typedefs | |
typedef struct fiber | fiber_t |
The opaque fiber data type. | |
typedef fiber_t * | fiber_func_t(fiber_t *fiber, void *arg) |
The type of the function executed by a fiber. More... | |
Functions | |
int | fiber_thrd_init (int flags) |
Initializes the fiber associated with the calling thread. More... | |
void | fiber_thrd_fini (void) |
Finalizes the fiber associated with the calling thread. More... | |
fiber_t * | fiber_create (fiber_func_t *func, void *arg, int flags, size_t data_size, size_t stack_size) |
Creates a new fiber, allocates a stack and sets up a calling environment to begin executing the specified function. More... | |
void | fiber_destroy (fiber_t *fiber) |
Destroys the specified fiber. More... | |
void * | fiber_data (const fiber_t *fiber) |
Returns a pointer to the data region of the specified fiber, or of the calling fiber if fiber is NULL. More... | |
fiber_t * | fiber_resume (fiber_t *fiber) |
Equivalent to fiber_resume_with(fiber, NULL, NULL) . | |
fiber_t * | fiber_resume_with (fiber_t *fiber, fiber_func_t *func, void *arg) |
Suspends the calling fiber and resumes the specified fiber, optionally executing a function before resuming the suspended function. More... | |
This header file is part of the utilities library; it contains the fiber declarations.
Fibers are user-space threads. They provide cooperative multitasking and can be used as a primitive for implementing stackful coroutines.
The fiber implementation on Windows is based on CreateFiber()/SwitchToFiber() and allows fibers to be migrated between threads. All other platforms use mkjmp()/setjmp()/longjmp(). Since using longjmp() to restore an environment saved by setjmp() in a different thread is undefined behavior (according to 7.13.2.1), fibers can only be reliably resumed by the thread on which they were created.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Definition in file fiber.h.
#define FIBER_GUARD_STACK 0x8 |
A flag specifying a fiber to add a guard page when allocating the stack frame so that the kernel generates a SIGSEGV signal on stack overflow (only supported on those POSIX platforms where mmap() supports anonymous mappings).
This flag is not supported by fiber_thrd_init(), since a thread already has a stack.
The type of the function executed by a fiber.
This function can switch to other fibers by calling fiber_resume() or fiber_resume_with(). The function is not required to ever terminate, but if it does, it MUST return a pointer to the fiber to be resumed, or NULL. In the latter case, the (fiber associated with the) current thread resumes execution.
fiber | a pointer to the suspended fiber, i.e., the fiber that invoked fiber_resume() or fiber_resume_with() to start this fiber. If fiber is NULL, this fiber was resumed by the (fiber associated with the) current thread. |
arg | the argument supplied to fiber_create(). |
int fiber_thrd_init | ( | int | flags | ) |
Initializes the fiber associated with the calling thread.
This is necessary to start a fiber, since fiber_resume() and fiber_resume_with() can only be called from within a valid fiber. This function can be invoked more than once by the same thread. Only the first invocation initializes the fiber.
flags | any supported combination of FIBER_SAVE_MASK, FIBER_SAVE_FENV and FIBER_SAVE_ERROR. If the calling thread already has an associated fiber, this parameter is ignored. |
void fiber_thrd_fini | ( | void | ) |
Finalizes the fiber associated with the calling thread.
This function MUST be called once for each successful call to fiber_thrd_init(). Only the last invocation finalizes the fiber.
fiber_t* fiber_create | ( | fiber_func_t * | func, |
void * | arg, | ||
int | flags, | ||
size_t | data_size, | ||
size_t | stack_size | ||
) |
Creates a new fiber, allocates a stack and sets up a calling environment to begin executing the specified function.
The function is not executed until the fiber is resumed with fiber_resume() or fiber_resume_with().
func | the function to be executed by the fiber (can be NULL). |
arg | the second argument supplied to func. |
flags | any supported combination of FIBER_SAVE_MASK, FIBER_SAVE_FENV, FIBER_SAVE_ERROR and FIBER_GUARD_STACK. |
data_size | the size of the data region to be allocated for the fiber. A pointer to this region can be obtained with fiber_data(). |
stack_size | the size (in bytes) of the stack frame to be allocated for the fiber. If 0, the default size (LELY_FIBER_STKSZ) is used. The size of the allocated stack is always at least LELY_FIBER_MINSTKSZ bytes. |
void fiber_destroy | ( | fiber_t * | fiber | ) |
void* fiber_data | ( | const fiber_t * | fiber | ) |
fiber_t* fiber_resume_with | ( | fiber_t * | fiber, |
fiber_func_t * | func, | ||
void * | arg | ||
) |
Suspends the calling fiber and resumes the specified fiber, optionally executing a function before resuming the suspended function.
Note that this function MUST be called from a valid fiber created by fiber_create() or fiber_thrd_init().
fiber | a pointer to the fiber to be resumed. If fiber is NULL, the fiber associated with the calling thread is resumed. |
func | a pointer to the function to be executed in the context of fiber before the suspended function resumes. If not NULL, a pointer to the calling fiber is supplied as the first argument to func and the result of func is returned to the suspended function. |
arg | the argument to be supplied to func. |