Lely core libraries  2.2.5
fiber_exec.c File Reference

This file is part of the event library; it contains the implementation of the fiber executor functions. More...

#include "ev.h"
#include <lely/libc/threads.h>
#include <lely/ev/exec.h>
#include <lely/ev/fiber_exec.h>
#include <lely/ev/task.h>
#include <lely/util/errnum.h>
#include <lely/util/util.h>
#include <assert.h>
#include <stdint.h>
#include <stdlib.h>
Include dependency graph for fiber_exec.c:

Go to the source code of this file.

Data Structures

struct  ev_fiber_thrd
 The parameters used for creating fibers on this thread and the list of unused fibers. More...
 
struct  ev_fiber_exec
 The implementation of a fiber executor. More...
 
struct  ev_fiber_ctx
 The context of a fiber used for executing tasks. More...
 
struct  ev_fiber_mtx_impl
 The implementation of a fiber mutex. More...
 
struct  ev_fiber_cnd_wait
 The context of a wait operation on a fiber condition variable. More...
 
struct  ev_fiber_cnd_impl
 The implementation of a fiber condition variable. More...
 

Macros

#define LELY_EV_FIBER_MAX_UNUSED   16
 The maximum number of unused fibers per thread.
 

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_tev_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_tev_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...
 

Detailed Description

This file is part of the event library; it contains the implementation of the fiber executor functions.

See also
lely/ev/fiber_exec.h
Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

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.c.

Function Documentation

◆ ev_fiber_thrd_init()

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.

Parameters
flagsthe 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_sizethe 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_unusedthe maximum number of unused fibers kept alive for future tasks. If 0, the default number (LELY_EV_FIBER_MAX_UNUSED) used.
Returns
1 if the calling thread is already initialized, 0 if it has been successfully initialized, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 203 of file fiber_exec.c.

◆ ev_fiber_thrd_fini()

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.

◆ ev_fiber_exec_create()

ev_exec_t* ev_fiber_exec_create ( ev_exec_t inner_exec)

Creates a fiber executor.

This function MUST be called from the thread used by the inner executor.

Parameters
inner_execa pointer to the inner executor used to resume suspended fibers (which execute tasks). This MUST be a single-threaded executor.
Returns
a pointer to a new fiber executor, or NULL on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 316 of file fiber_exec.c.

◆ ev_fiber_exec_destroy()

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.

See also
ev_fiber_exec_create()

Definition at line 343 of file fiber_exec.c.

◆ ev_fiber_await()

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.

◆ ev_fiber_mtx_init()

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:

If this function succeeds, it sets the mutex at mtx to a value that uniquely identifies the newly created mutex.

Returns
ev_fiber_success on success, or ev_fiber_nomem if no memory could be allocated for the newly created mutex, or ev_fiber_error if the request could not be honored.

Definition at line 369 of file fiber_exec.c.

◆ ev_fiber_mtx_destroy()

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.

◆ ev_fiber_mtx_lock()

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.

Returns
ev_fiber_success on success, or ev_fiber_error if the request could not be honored.

Definition at line 419 of file fiber_exec.c.

◆ ev_fiber_mtx_trylock()

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.

Returns
ev_fiber_success on success, or ev_fiber_busy if the resource requested is already in use, or ev_fiber_error if the request could not be honored.

Definition at line 467 of file fiber_exec.c.

◆ ev_fiber_mtx_unlock()

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.

Returns
ev_fiber_success on success, or ev_fiber_error if the request could not be honored.

Definition at line 516 of file fiber_exec.c.

◆ ev_fiber_cnd_init()

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.

Returns
ev_fiber_success on success, or ev_fiber_nomem if no memory could be allocated for the newly created condition, or ev_fiber_error if the request could not be honored.

Definition at line 557 of file fiber_exec.c.

◆ ev_fiber_cnd_destroy()

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.

◆ ev_fiber_cnd_signal()

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.

Returns
ev_fiber_success.

Definition at line 597 of file fiber_exec.c.

◆ ev_fiber_cnd_broadcast()

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.

Returns
ev_fiber_success.

Definition at line 618 of file fiber_exec.c.

◆ ev_fiber_cnd_wait()

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.

Returns
ev_fiber_success on success, or ev_fiber_error if the request could not be honored.

Definition at line 643 of file fiber_exec.c.