Lely core libraries
2.2.5
|
Go to the source code of this file.
Data Structures | |
struct | ev_fiber_mtx_t |
A synchronization primitive (similar to the standard C11 mutex) that can be used to protect shared data from being simultaneously accessed by multiple fibers. More... | |
struct | ev_fiber_cnd_t |
A synchronization primitive (similar to the standard C11 condition variable) that can be used to block one or more fibers until another fiber or thread both modifies the shared variable (the condition), and notifies the condition variable. More... | |
Enumerations | |
enum | { ev_fiber_success, ev_fiber_error, ev_fiber_timedout, ev_fiber_busy, ev_fiber_nomem } |
enum | { ev_fiber_mtx_plain, ev_fiber_mtx_timed, ev_fiber_mtx_recursive } |
Functions | |
int | ev_fiber_thrd_init (int flags, size_t stack_size, size_t max_unused) |
Initializes the calling thread for use by fiber executors. More... | |
void | ev_fiber_thrd_fini (void) |
Finalizes the calling thread and prevents further use by fiber executors. More... | |
ev_exec_t * | ev_fiber_exec_create (ev_exec_t *inner_exec) |
Creates a fiber executor. More... | |
void | ev_fiber_exec_destroy (ev_exec_t *exec) |
Destroys a fiber executor. More... | |
ev_exec_t * | ev_fiber_exec_get_inner_exec (const ev_exec_t *exec) |
Returns a pointer to the inner executor of a fiber executor. | |
void | ev_fiber_await (ev_future_t *future) |
Suspends a currently running fiber until the specified future becomes ready (or is cancelled). More... | |
int | ev_fiber_mtx_init (ev_fiber_mtx_t *mtx, int type) |
Creates a fiber mutex object with properties indicated by type, which must have one of the four values: More... | |
void | ev_fiber_mtx_destroy (ev_fiber_mtx_t *mtx) |
Releases any resources used by the fiber mutex at mtx. More... | |
int | ev_fiber_mtx_lock (ev_fiber_mtx_t *mtx) |
Suspends the currently running fiber until it locks the fiber mutex at mtx. More... | |
int | ev_fiber_mtx_trylock (ev_fiber_mtx_t *mtx) |
Endeavors to lock the fiber mutex at mtx. More... | |
int | ev_fiber_mtx_unlock (ev_fiber_mtx_t *mtx) |
Unlocks the fiber mutex at mtx. More... | |
int | ev_fiber_cnd_init (ev_fiber_cnd_t *cond) |
Creates a fiber condition variable. More... | |
void | ev_fiber_cnd_destroy (ev_fiber_cnd_t *cond) |
Releases all resources used by the fiber condition variable at cond. More... | |
int | ev_fiber_cnd_signal (ev_fiber_cnd_t *cond) |
Unblocks one of the fibers that are blocked on the fiber condition variable at cond at the time of the call. More... | |
int | ev_fiber_cnd_broadcast (ev_fiber_cnd_t *cond) |
Unblocks all of the fibers that are blocked on the fiber condition variable at cond at the time of the call. More... | |
int | ev_fiber_cnd_wait (ev_fiber_cnd_t *cond, ev_fiber_mtx_t *mtx) |
Atomically unlocks the fiber mutex at mtx and endeavors to block until the fiber condition variable at cond is signaled by a call to ev_fiber_cnd_signal() or to ev_fiber_cnd_broadcast(). More... | |
This header file is part of the event library; it contains the fiber executor, mutex and condition variable declarations.
The fiber executor ensures that each task runs in a fiber, or stackful coroutine. Since it is platform-dependent whether fibers can be migrated between threads, the (inner) executor from which the fibers are resumed MUST be single-threaded.
To limit the creation overhead, fibers are reused once they finish executing a task. The implementation maintains a list of unused fibers, up to a user-defined limit.
The fiber mutex and condition variable are similar to the standard C11 mutex and condition variable, except that they suspend the currently running fiber instead of the thread.
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_exec.h.
anonymous enum |
Definition at line 43 of file fiber_exec.h.
anonymous enum |
Definition at line 65 of file fiber_exec.h.
int ev_fiber_thrd_init | ( | int | flags, |
size_t | stack_size, | ||
size_t | max_unused | ||
) |
Initializes the calling thread for use by fiber executors.
This function MUST be invoked at least once in each thread that will resume a suspended fiber. This function can be invoked more than once by the same thread. Only the first invocation initializes the thread.
flags | the flags used to initialize the internal fiber of the calling thread (see fiber_thrd_init()) and any subsequent fibers created by a fiber executor. flags can be any supported combination of FIBER_SAVE_MASK, FIBER_SAVE_FENV, FIBER_SAVE_ERROR and FIBER_GUARD_STACK. |
stack_size | the size (in bytes) of the stack frame to be allocated for the fibers. If 0, the default size (LELY_FIBER_STKSZ) is used. The size of the allocated stack is always at least LELY_FIBER_MINSTKSZ bytes. |
max_unused | the maximum number of unused fibers kept alive for future tasks. If 0, the default number (LELY_EV_FIBER_MAX_UNUSED) used. |
Definition at line 203 of file fiber_exec.c.
void ev_fiber_thrd_fini | ( | void | ) |
Finalizes the calling thread and prevents further use by fiber executors.
This function MUST be called once for each successful call to ev_fiber_thrd_init(). Only the last invocation finalizes the thread.
Definition at line 229 of file fiber_exec.c.
Creates a fiber executor.
This function MUST be called from the thread used by the inner executor.
inner_exec | a pointer to the inner executor used to resume suspended fibers (which execute tasks). This MUST be a single-threaded executor. |
Definition at line 316 of file fiber_exec.c.
void ev_fiber_exec_destroy | ( | ev_exec_t * | exec | ) |
Destroys a fiber executor.
This function MUST be called from the thread on which the executor was created.
Definition at line 343 of file fiber_exec.c.
void ev_fiber_await | ( | ev_future_t * | future | ) |
Suspends a currently running fiber until the specified future becomes ready (or is cancelled).
If future is NULL, the fiber is suspended and immediately resubmitted to the inner executor.
This function MUST only be invoked from tasks submitted to a fiber executor.
Definition at line 360 of file fiber_exec.c.
int ev_fiber_mtx_init | ( | ev_fiber_mtx_t * | mtx, |
int | type | ||
) |
Creates a fiber mutex object with properties indicated by type, which must have one of the four values:
#ev_fiber_mtx_plain
for a simple non-recursive mutex,#ev_fiber_mtx_timed
for a non-recursive mutex that supports timeout,#ev_fiber_mtx_plain | #ev_fiber_mtx_recursive
for a simple recursive mutex, or#ev_fiber_mtx_timed | #ev_fiber_mtx_recursive
for a recursive mutex that supports timeout. Note that #ev_fiber_mtx_timed
is currently not supported.If this function succeeds, it sets the mutex at mtx to a value that uniquely identifies the newly created mutex.
Definition at line 369 of file fiber_exec.c.
void ev_fiber_mtx_destroy | ( | ev_fiber_mtx_t * | mtx | ) |
Releases any resources used by the fiber mutex at mtx.
No fibers can be blocked waiting for the mutex at mtx.
Definition at line 402 of file fiber_exec.c.
int ev_fiber_mtx_lock | ( | ev_fiber_mtx_t * | mtx | ) |
Suspends the currently running fiber until it locks the fiber mutex at mtx.
If the mutex is non-recursive, it SHALL not be locked by the calling fiber. Prior calls to ev_fiber_mtx_unlock() on the same mutex shall synchronize with this operation.
This function MUST be called from a task running on a fiber executor.
Definition at line 419 of file fiber_exec.c.
int ev_fiber_mtx_trylock | ( | ev_fiber_mtx_t * | mtx | ) |
Endeavors to lock the fiber mutex at mtx.
If the mutex is already locked, the function returns without blocking. If the operation succeeds, prior calls to ev_fiber_mtx_unlock() on the same mutex shall synchronize with this operation.
This function MUST be called from a task running on a fiber executor.
Definition at line 467 of file fiber_exec.c.
int ev_fiber_mtx_unlock | ( | ev_fiber_mtx_t * | mtx | ) |
Unlocks the fiber mutex at mtx.
The mutex at mtx SHALL be locked by the calling fiber.
This function MUST be called from a task running on a fiber executor.
Definition at line 516 of file fiber_exec.c.
int ev_fiber_cnd_init | ( | ev_fiber_cnd_t * | cond | ) |
Creates a fiber condition variable.
If it succeeds it sets the variable at cond to a value that uniquely identifies the newly created condition variable. A fiber that calls ev_fiber_cnd_wait() on a newly created condition variable will block.
Definition at line 557 of file fiber_exec.c.
void ev_fiber_cnd_destroy | ( | ev_fiber_cnd_t * | cond | ) |
Releases all resources used by the fiber condition variable at cond.
This function requires that no fibers be blocked waiting for the condition variable at cond.
Definition at line 581 of file fiber_exec.c.
int ev_fiber_cnd_signal | ( | ev_fiber_cnd_t * | cond | ) |
Unblocks one of the fibers that are blocked on the fiber condition variable at cond at the time of the call.
If no fibers are blocked on the condition variable at the time of the call, the function does nothing.
Definition at line 597 of file fiber_exec.c.
int ev_fiber_cnd_broadcast | ( | ev_fiber_cnd_t * | cond | ) |
Unblocks all of the fibers that are blocked on the fiber condition variable at cond at the time of the call.
If no fibers are blocked on the condition variable at cond at the time of the call, the function does nothing.
Definition at line 618 of file fiber_exec.c.
int ev_fiber_cnd_wait | ( | ev_fiber_cnd_t * | cond, |
ev_fiber_mtx_t * | mtx | ||
) |
Atomically unlocks the fiber mutex at mtx and endeavors to block until the fiber condition variable at cond is signaled by a call to ev_fiber_cnd_signal() or to ev_fiber_cnd_broadcast().
When the calling fiber becomes unblocked it locks the mutex at mtx before it returns. This function requires that the mutex at mtx be locked by the calling fiber.
This function MUST be called from a task running on a fiber executor.
Definition at line 643 of file fiber_exec.c.