This file contains all client-visible API functions for working with fibers. More...

#include <unistd.h>
#include <stdarg.h>
#include <stddef.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <assert.h>
#include <ev.h>

Data Structures
struct	fbr_context
	Library context structure, should be initialized before any other library calls will be performed. More...
struct	fbr_logger
	Logger structure. More...
struct	fbr_ev_base
	Base struct for all events. More...
struct	fbr_ev_watcher
	libev watcher event. More...
struct	fbr_ev_mutex
	fbr_mutex event. More...
struct	fbr_ev_cond_var
	fbr_cond_var event. More...

Macros
#define	FBR_CALL_STACK_SIZE 16
	Maximum allowed level of fbr_transfer nesting within fibers.
#define	FBR_STACK_SIZE (64 * 1024) /* 64 KB */
	Default stack size for a fiber of 64 KB.
#define	fbr_assert(context, expr)
	Fiber version of classic assert.
#define	fbr_container_of(ptr, type, member)
	Just for convenience we have container_of macro here.
#define	FBR_P struct fbr_context *fctx
	Utility macro for context parameter used in function prototypes.
#define	FBR_P_ FBR_P,
	Same as FBR_P, but with comma afterwards for use in functions that accept more that one parameter (which itself is the context pointer).
#define	FBR_A fctx
	Utility macro for context parameter passing when calling fbr_* functions.
#define	FBR_A_ FBR_A,
	Same as FBR_A, but with comma afterwards for invocations of functions that require more that one parameter (which itself is the context pointer).
#define	fbr_need_log(fctx, test_level) ((test_level) <= (fctx)->logger->level)
	Convenient macro to test if certain log level will actually be logged.
#define	fbr_set_log_level(fctx, desired_level) (fctx)->logger->level = (desired_level)
	Convenient macro to set current log level.
#define	fbr_ev_upcast(ptr, type_no_struct) fbr_container_of(ptr, struct type_no_struct, ev_base)
	Convenience macro to save some typing.

Typedefs
typedef __uint128_t	fbr_id_t
	Fiber ID type.
typedef void(*	fbr_fiber_func_t )(FBR_P_ void *_arg)
	Fiber's ``main'' function type.
typedef void(*	fbr_alloc_destructor_func_t )(FBR_P_ void ptr, void context)
	Destructor function type for the memory allocated in a fiber.
typedef void(*	fbr_log_func_t )(FBR_P_ struct fbr_logger logger, enum fbr_log_level level, const char format, va_list ap)
	Logger function type.
typedef void(*	fbr_logutil_func_t )(FBR_P_ const char *format,...)
	Logger utility function type.

Enumerations
enum	fbr_error_code { FBR_SUCCESS = 0, FBR_EINVAL, FBR_ENOFIBER, FBR_ESYSTEM, FBR_EBUFFERMMAP }
	Error codes used within the library. More...
enum	fbr_log_level { FBR_LOG_ERROR = 0, FBR_LOG_WARNING, FBR_LOG_NOTICE, FBR_LOG_INFO, FBR_LOG_DEBUG }
	Logging levels. More...
enum	fbr_ev_type { FBR_EV_WATCHER = 1, FBR_EV_MUTEX, FBR_EV_COND_VAR }
	Type of events supported by the library. More...

Functions
void	fbr_ev_watcher_init (FBR_P_ struct fbr_ev_watcher ev, ev_watcher w)
	Initializer for libev watcher event.
void	fbr_ev_mutex_init (FBR_P_ struct fbr_ev_mutex ev, struct fbr_mutex mutex)
	Initializer for mutex event.
void	fbr_ev_cond_var_init (FBR_P_ struct fbr_ev_cond_var ev, struct fbr_cond_var cond, struct fbr_mutex *mutex)
	Initializer for conditional variable event.
void	fbr_ev_wait_one (FBR_P_ struct fbr_ev_base *one)
	Event awaiting function (one event only wrapper).
struct fbr_ev_base *	fbr_ev_wait (FBR_P_ struct fbr_ev_base *events[])
	Event awaiting function (generic one).
int	fbr_transfer (FBR_P_ fbr_id_t to)
	Transfer of fiber context to another fiber.
void	fbr_init (struct fbr_context fctx, struct ev_loop loop)
	Initializes the library context.
void	fbr_destroy (FBR_P)
	Destroys the library context.
void	fbr_enable_backtraces (FBR_P, int enabled)
	Enables/Disables backtrace capturing.
const char *	fbr_strerror (FBR_P_ enum fbr_error_code code)
	Analog of strerror but for the library errno.
void	fbr_log_e (FBR_P_ const char *format,...) __attribute__((format(printf
	Utility log wrapper.
void void	fbr_log_w (FBR_P_ const char *format,...) __attribute__((format(printf
	Utility log wrapper.
void void void	fbr_log_n (FBR_P_ const char *format,...) __attribute__((format(printf
	Utility log wrapper.
void void void void	fbr_log_i (FBR_P_ const char *format,...) __attribute__((format(printf
	Utility log wrapper.
void void void void void	fbr_log_d (FBR_P_ const char *format,...) __attribute__((format(printf
	Utility log wrapper.
void void void void void fbr_id_t	fbr_create (FBR_P_ const char name, fbr_fiber_func_t func, void arg, size_t stack_size)
	Creates a new fiber.
int	fbr_disown (FBR_P_ fbr_id_t parent)
	Changes parent of current fiber.
fbr_id_t	fbr_parent (FBR_P)
	Find out current fiber's parent.
int	fbr_reclaim (FBR_P_ fbr_id_t fiber)
	Reclaims a fiber.
int	fbr_is_reclaimed (FBR_P_ fbr_id_t fiber)
	Tests if given fiber is reclaimed.
fbr_id_t	fbr_self (FBR_P)
	Returns id of current fiber.
struct fbr_fiber_arg	fbr_arg_i (int i)
	Utility function for creating integer fbr_fiber_arg.
struct fbr_fiber_arg	fbr_arg_v (void *v)
	Utility function for creating void pointer fbr_fiber_arg.
void	fbr_yield (FBR_P)
	Yields execution to other fiber.
void *	fbr_alloc (FBR_P_ size_t size)
	Allocates memory in current fiber's pool.
void	fbr_alloc_set_destructor (FBR_P_ void ptr, fbr_alloc_destructor_func_t func, void context)
	Sets destructor for a memory chunk.
void *	fbr_calloc (FBR_P_ unsigned int nmemb, size_t size)
	Allocates a set of initialized objects in fiber's pool.
void	fbr_free (FBR_P_ void *ptr)
	Explicitly frees allocated memory chunk.
void	fbr_free_nd (FBR_P_ void *ptr)
	Explicitly frees allocated memory chunk.
int	fbr_fd_nonblock (FBR_P_ int fd)
	Utility function to make file descriptor non-blocking.
ssize_t	fbr_read (FBR_P_ int fd, void *buf, size_t count)
	Fiber friendly libc read wrapper.
ssize_t	fbr_read_all (FBR_P_ int fd, void *buf, size_t count)
	Even more fiber friendly libc read wrapper.
ssize_t	fbr_readline (FBR_P_ int fd, void *buffer, size_t n)
	Utility function to read a line.
ssize_t	fbr_write (FBR_P_ int fd, const void *buf, size_t count)
	Fiber friendly libc write wrapper.
ssize_t	fbr_write_all (FBR_P_ int fd, const void *buf, size_t count)
	Even more fiber friendly libc write wrapper.
ssize_t	fbr_recvfrom (FBR_P_ int sockfd, void buf, size_t len, int flags, struct sockaddr src_addr, socklen_t *addrlen)
	Fiber friendly libc recvfrom wrapper.
ssize_t	fbr_sendto (FBR_P_ int sockfd, const void buf, size_t len, int flags, const struct sockaddr dest_addr, socklen_t addrlen)
	Fiber friendly libc sendto wrapper.
int	fbr_accept (FBR_P_ int sockfd, struct sockaddr addr, socklen_t addrlen)
	Fiber friendly libc accept wrapper.
ev_tstamp	fbr_sleep (FBR_P_ ev_tstamp seconds)
	Puts current fiber to sleep.
void	fbr_dump_stack (FBR_P_ fbr_logutil_func_t log)
	Prints fiber call stack to stderr.
struct fbr_mutex *	fbr_mutex_create (FBR_P)
	Creates a mutex.
void	fbr_mutex_lock (FBR_P_ struct fbr_mutex *mutex)
	Locks a mutex.
int	fbr_mutex_trylock (FBR_P_ struct fbr_mutex *mutex)
	Tries to locks a mutex.
void	fbr_mutex_unlock (FBR_P_ struct fbr_mutex *mutex)
	Unlocks a mutex.
void	fbr_mutex_destroy (FBR_P_ struct fbr_mutex *mutex)
	Frees a mutex.
struct fbr_cond_var *	fbr_cond_create (FBR_P)
	Creates a conditional variable.
void	fbr_cond_destroy (FBR_P_ struct fbr_cond_var *cond)
	Destroys a conditional variable.
int	fbr_cond_wait (FBR_P_ struct fbr_cond_var cond, struct fbr_mutex mutex)
	Waits until condition is met.
void	fbr_cond_broadcast (FBR_P_ struct fbr_cond_var *cond)
	Broadcasts a signal to all fibers waiting for condition.
void	fbr_cond_signal (FBR_P_ struct fbr_cond_var *cond)
	Signals to first fiber waiting for condition.
struct fbr_buffer *	fbr_buffer_create (FBR_P_ size_t size)
	Creates a circular buffer with pipe semantics.
void	fbr_buffer_free (FBR_P_ struct fbr_buffer *buffer)
	Frees a circular buffer.
void *	fbr_buffer_alloc_prepare (FBR_P_ struct fbr_buffer *buffer, size_t size)
	Prepares a chunk of memory to be committed to buffer.
void	fbr_buffer_alloc_commit (FBR_P_ struct fbr_buffer *buffer)
	Commits a chunk of memory to the buffer.
void	fbr_buffer_alloc_abort (FBR_P_ struct fbr_buffer *buffer)
	Aborts a chunk of memory in the buffer.
void *	fbr_buffer_read_address (FBR_P_ struct fbr_buffer *buffer, size_t size)
	Aborts a chunk of memory in the buffer.
void	fbr_buffer_read_advance (FBR_P_ struct fbr_buffer *buffer)
	Confirms a read of chunk of memory in the buffer.
void	fbr_buffer_read_discard (FBR_P_ struct fbr_buffer *buffer)
	Discards a read of chunk of memory in the buffer.
size_t	fbr_buffer_bytes (FBR_P_ struct fbr_buffer *buffer)
	Amount of bytes filled with data.
size_t	fbr_buffer_free_bytes (FBR_P_ struct fbr_buffer *buffer)
	Amount of free bytes.
struct fbr_cond_var *	fbr_buffer_cond_read (FBR_P_ struct fbr_buffer *buffer)
struct fbr_cond_var *	fbr_buffer_cond_write (FBR_P_ struct fbr_buffer *buffer)
void *	fbr_get_user_data (FBR_P_ fbr_id_t id)
	Gets fiber user data pointer.
int	fbr_set_user_data (FBR_P_ fbr_id_t id, void *data)
	Sets fiber user data pointer.

Detailed Description

This file contains all client-visible API functions for working with fibers.

Definition in file fiber.h.

Macro Definition Documentation

#define fbr_assert	(	context,
		expr
	)

Value:

do {                                                                                  \
                __typeof__(expr) ex = (expr);                                                 \
                if (ex)                                                                       \
                        (void)(0);                                                            \
                else {                                                                        \
                        fbr_dump_stack(context, fbr_log_e);                                   \
                        __assert_fail(__STRING(expr), __FILE__, __LINE__, __ASSERT_FUNCTION); \
                }                                                                             \
        } while (0)

Fiber version of classic assert.

Definition at line 173 of file fiber.h.

#define fbr_container_of	(	ptr,
		type,
		member
	)

Value:

({                       \
                const typeof( ((type *)0)->member ) *__mptr = (ptr); \
                (type *)( (char *)__mptr - offsetof(type,member) );  \
                })

Just for convenience we have container_of macro here.

Nothing specific. You can find the same one in the linux kernel tree.

Definition at line 190 of file fiber.h.

#define fbr_ev_upcast	(	ptr,
		type_no_struct
	)	fbr_container_of(ptr, struct type_no_struct, ev_base)

Convenience macro to save some typing.

Allows you to cast fbr_ev_base to some other event struct via fbr_container_of magic.

See Also: fbr_container_of; fbr_ev_base

Definition at line 381 of file fiber.h.

#define fbr_need_log	(	fctx,
		test_level
	)	((test_level) <= (fctx)->logger->level)

Convenient macro to test if certain log level will actually be logged.

Useful when you need to perform some processing before logging. Wrapping your processing in ``if'' statement based on this macros' result can perform the processing only if it's result will get logged.

Definition at line 305 of file fiber.h.

Typedef Documentation

typedef void(* fbr_alloc_destructor_func_t)(FBR_P_ void *ptr, void *context)

Destructor function type for the memory allocated in a fiber.

Parameters

[in]	ptr	memory pointer for memory to be destroyed
[in]	context	user data pointer passed via fbr_alloc_set_destructor

One can attach a destructor to a piece of memory allocated in a fiber. It will be called whenever memory is freed with original pointer allocated along with a user context pointer passed to it.

See Also: fbr_alloc; fbr_free; fbr_alloc_set_destructor

Definition at line 281 of file fiber.h.

typedef void(* fbr_fiber_func_t)(FBR_P_ void *_arg)

Fiber's ``main'' function type.

Fiber main function takes only one parameter — the context. If you need to pass more context information, you shall embed fbr_context into any structure of your choice and calculate the base pointer using container_of macro.

See Also: FBR_P; fbr_context

Definition at line 267 of file fiber.h.

typedef __uint128_t fbr_id_t

Fiber ID type.

For you it's just an opaque type.

Definition at line 199 of file fiber.h.

typedef void(* fbr_log_func_t)(FBR_P_ struct fbr_logger *logger, enum fbr_log_level level, const char *format, va_list ap)

Logger function type.

Parameters

[in]	logger	currently configured logger
[in]	level	log level of message
[in]	format	printf-compatible format string
[in]	ap	variadic argument list This function should log the message if log level suits the one configured in a non-blocking manner (i.e. it should not synchronously write it to disk).

See Also: fbr_logger; fbr_log_func_t

Definition at line 325 of file fiber.h.

typedef void(* fbr_logutil_func_t)(FBR_P_ const char *format,...)

Logger utility function type.

Parameters

[in] format printf-compatible format string

This function wraps logger function invocation.

See Also: fbr_logger; fbr_log_func_t

Definition at line 335 of file fiber.h.

Enumeration Type Documentation

enum fbr_error_code

Error codes used within the library.

These constants are returned via f_errno member of fbr_context struct.

See Also: fbr_context; fbr_strerror

Definition at line 214 of file fiber.h.

enum fbr_ev_type

Type of events supported by the library.

See Also: fbr_ev_wait

Enumerator:

FBR_EV_WATCHER	libev watcher event
FBR_EV_MUTEX	fbr_mutex event
FBR_EV_COND_VAR	fbr_cond_var event

Definition at line 352 of file fiber.h.

enum fbr_log_level

Logging levels.

See Also: fbr_logger; fbr_context

Definition at line 288 of file fiber.h.

Function Documentation

int fbr_accept	(	FBR_P_ int	sockfd,
		struct sockaddr *	addr,
		socklen_t *	addrlen
	)

Fiber friendly libc accept wrapper.

Parameters

[in]	sockfd	file descriptor to accept on
[in]	addr	client address
[in]	addrlen	size of addr

Returns: client socket fd on success, -1 in case of error and errno set

This function is used to accept a connection on a listening socket.

Possible errno values are described in accept man page. The only special case is EINTR which is handled internally and is returned to the caller only in case when non-root fiber called the fiber sitting in fbr_accept.

Definition at line 817 of file fiber.c.

void* fbr_alloc ( FBR_P_ size_t size )

Allocates memory in current fiber's pool.

Parameters

[in] size size of the requested memory block

Returns: allocated memory chunk

When a fiber is reclaimed, this memory will be freed. Prior to that a destructor will be called if any specified.

See Also: fbr_calloc; fbr_alloc_set_destructor; fbr_alloc_destructor_func_t; fbr_free

Definition at line 933 of file fiber.c.

void fbr_alloc_set_destructor	(	FBR_P_ void *	ptr,
		fbr_alloc_destructor_func_t	func,
		void *	context
	)

Sets destructor for a memory chunk.

Parameters

[in]	ptr	address of a memory chunk
[in]	func	destructor function
[in]	context	user supplied context pointer

Setting new destructor simply changes it without calling old one or queueing them.

You can allocate 0 sized memory chunk and never free it just for the purpose of calling destructor with some context when fiber is reclaimed. This way you can for example close some file descriptors or do some other required cleanup.

See Also: fbr_alloc; fbr_free

struct fbr_fiber_arg fbr_arg_i ( int i )

read

Utility function for creating integer fbr_fiber_arg.

Parameters

[in] i integer argument

Returns: integer fbr_fiber_arg struct.

struct fbr_fiber_arg fbr_arg_v ( void * v )

read

Utility function for creating void pointer fbr_fiber_arg.

Parameters

[in] v void pointer argument

Returns: void pointer fbr_fiber_arg struct

void fbr_buffer_alloc_abort ( FBR_P_ struct fbr_buffer * buffer )

Aborts a chunk of memory in the buffer.

Parameters

[in] buffer a pointer to fbr_buffer

This function aborts prepared chunk of memory previously reserved. It will not be committed and the next fiber may reuse it for it's own purposes.

See Also: fbr_buffer_alloc_prepare; fbr_buffer_alloc_commit

Definition at line 1192 of file fiber.c.

void fbr_buffer_alloc_commit ( FBR_P_ struct fbr_buffer * buffer )

Commits a chunk of memory to the buffer.

Parameters

[in] buffer a pointer to fbr_buffer

This function commits a chunk of memory previously reserved.

See Also: fbr_buffer_alloc_prepare; fbr_buffer_alloc_abort

Definition at line 1184 of file fiber.c.

void* fbr_buffer_alloc_prepare	(	FBR_P_ struct fbr_buffer *	buffer,
		size_t	size
	)

Prepares a chunk of memory to be committed to buffer.

Parameters

[in]	buffer	a pointer to fbr_buffer
[in]	size	required size

Returns: pointer to memory reserved for commit.

This function reserves a chunk of memory (or waits until there is one available, blocking current fiber) and returns pointer to it.

A fiber trying to reserve a chunk of memory after some other fiber already reserved it leads to the former fiber being blocked until the latter one commits or aborts.

See Also: fbr_buffer_alloc_commit; fbr_buffer_alloc_abort

Definition at line 1162 of file fiber.c.

size_t fbr_buffer_bytes ( FBR_P_ struct fbr_buffer * buffer )

Amount of bytes filled with data.

Parameters

[in] buffer a pointer to fbr_buffer

Returns: number of bytes written to the buffer

This function can be used to check if fbr_buffer_read_address will block.

See Also: fbr_buffer_free_bytes

struct fbr_buffer* fbr_buffer_create ( FBR_P_ size_t size )

read

Creates a circular buffer with pipe semantics.

Parameters

[in] size size hint for the buffer

Returns: fbr_buffer pointer on succes, NULL upon failure with f_errno set.

This allocates a buffer with pipe semantics: you can write into it and later read what you have written. The buffer will occupy size rounded up to page size in physical memory, while occupying twice this size in virtual process memory due to usage of two mirrored adjacent mmaps.

Definition at line 1132 of file fiber.c.

void fbr_buffer_free ( FBR_P_ struct fbr_buffer * buffer )

Frees a circular buffer.

Parameters

[in] buffer a pointer to fbr_buffer to free

This unmaps all mmaped memory for the buffer. It does not do any fancy stuff like waiting until buffer is empty etc., it just frees it.

Definition at line 1150 of file fiber.c.

size_t fbr_buffer_free_bytes ( FBR_P_ struct fbr_buffer * buffer )

Amount of free bytes.

Parameters

[in] buffer a pointer to fbr_buffer

Returns: number of free bytes in the buffer

This function can be used to check if fbr_buffer_alloc_prepare will block.

See Also: fbr_buffer_bytes

void* fbr_buffer_read_address	(	FBR_P_ struct fbr_buffer *	buffer,
		size_t	size
	)

Aborts a chunk of memory in the buffer.

Parameters

[in]	buffer	a pointer to fbr_buffer
[in]	size	number of bytes required

Returns: read address containing size bytes

This function reserves (or waits till data is available, blocking current fiber) a chunk of memory for reading. While a chunk of memory is reserved for reading no other fiber can read from this buffer blocking until current read is advanced or discarded.

See Also: fbr_buffer_read_advance; fbr_buffer_read_discard

Definition at line 1199 of file fiber.c.

void fbr_buffer_read_advance ( FBR_P_ struct fbr_buffer * buffer )

Confirms a read of chunk of memory in the buffer.

Parameters

[in] buffer a pointer to fbr_buffer

This function confirms that bytes obtained with fbr_buffer_read_address are read and no other fiber will be able to read them.

See Also: fbr_buffer_read_address; fbr_buffer_read_discard

Definition at line 1218 of file fiber.c.

void fbr_buffer_read_discard ( FBR_P_ struct fbr_buffer * buffer )

Discards a read of chunk of memory in the buffer.

Parameters

[in] buffer a pointer to fbr_buffer

This function discards bytes obtained with fbr_buffer_read_address. Next fiber trying to read something from a buffer may obtain those bytes.

See Also: fbr_buffer_read_address; fbr_buffer_read_advance

Definition at line 1226 of file fiber.c.

void* fbr_calloc	(	FBR_P_ unsigned int	nmemb,
		size_t	size
	)

Allocates a set of initialized objects in fiber's pool.

Parameters

[in]	nmemb	number of members
[in]	size	size of a single member

Returns: zero-filled allocated memory chunk

Same as fbr_alloc called with nmemb multiplied by size.

See Also: fbr_alloc; fbr_free

Definition at line 925 of file fiber.c.

void fbr_cond_broadcast ( FBR_P_ struct fbr_cond_var * cond )

Broadcasts a signal to all fibers waiting for condition.

All fibers waiting for a condition will be added to run queue (and will eventually be run, one per event loop iteration).

See Also: fbr_cond_create; fbr_cond_destroy; fbr_cond_wait; fbr_cond_signal

Definition at line 1099 of file fiber.c.

struct fbr_cond_var* fbr_cond_create ( FBR_P )

read

Creates a conditional variable.

Conditional variable is useful primitive for fiber synchronisation. A set of fibers may be waiting until certain condition is met. Another fiber can trigger this condition for one or all waiting fibers.

See Also: fbr_cond_destroy; fbr_cond_wait; fbr_cond_broadcast; fbr_cond_signal

void fbr_cond_destroy ( FBR_P_ struct fbr_cond_var * cond )

Destroys a conditional variable.

This just frees used resources. No signals are sent to waiting fibers.

See Also: fbr_cond_create; fbr_cond_wait; fbr_cond_broadcast; fbr_cond_signal

void fbr_cond_signal ( FBR_P_ struct fbr_cond_var * cond )

Signals to first fiber waiting for condition.

Exactly one fiber (first one) waiting for a condition will be added to run queue (and will eventually be run, one per event loop iteration).

See Also: fbr_cond_create; fbr_cond_destroy; fbr_cond_wait; fbr_cond_signal

Definition at line 1115 of file fiber.c.

int fbr_cond_wait	(	FBR_P_ struct fbr_cond_var *	cond,
		struct fbr_mutex *	mutex
	)

Waits until condition is met.

Current fiber is suspended until a signal is sent via fbr_cond_signal or fbr_cond_broadcast to the corresponding conditional variable.

A mutex must be acquired by the calling fiber prior to waiting for a condition. Internally mutex is released and reacquired again before returning. Upon successful return calling fiber will hold the mutex.

See Also: fbr_cond_create; fbr_cond_destroy; fbr_cond_broadcast; fbr_cond_signal

Definition at line 1087 of file fiber.c.

void void void void void fbr_id_t fbr_create	(	FBR_P_ const char *	name,
		fbr_fiber_func_t	func,
		void *	arg,
		size_t	stack_size
	)

Creates a new fiber.

Parameters

[in]	name	fiber name, used for identification it backtraces, etc.
[in]	func	function used as a fiber's ``main''.
[in]	stack_size	stack size (0 for default).
[in]	arg	user supplied argument to a fiber.

Returns: Pointer to the created fiber.

The created fiber is not running in any shape or form, it's just created and is ready to be launched.

Stack is anonymously mmaped so it should not occupy all the required space straight away. Adjust stack size only when you know what you are doing!

Allocated stacks are registered as stacks via valgrind client request mechanism, so it's generally valgrind friendly and should not cause any noise.

Fibers are organized in a tree. Child nodes are attached to a parent whenever the parent is creating them. This tree is used primarily for automatic reclaim of child fibers.

See Also: fbr_reclaim; fbr_disown; fbr_parent

Definition at line 867 of file fiber.c.

void fbr_destroy ( FBR_P )

Destroys the library context.

All created fibers are reclaimed and all of the memory is freed. Stopping the event loop is user's responsibility.

See Also: fbr_context; fbr_init; fbr_reclaim

Definition at line 293 of file fiber.c.

int fbr_disown ( FBR_P_ fbr_id_t parent )

Changes parent of current fiber.

Parameters

[in] parent new parent fiber

Returns: -1 on error with f_errno set, 0 upon success

This function allows you to change fiber's parent. You needs to pass valid id or 0 to indicate the root fiber.

This might be useful when some fiber A creates another fiber B that should survive it's parent being reclaimed, or vice versa, some fiber A needs to be reclaimed with fiber B albeit B is not A's parent.

Root fiber is reclaimed only when library context is destroyed.

See Also: fbr_create; fbr_destroy

Definition at line 903 of file fiber.c.

void fbr_dump_stack ( FBR_P_ fbr_logutil_func_t log )

Prints fiber call stack to stderr.

useful while debugging obscure fiber call problems.

Definition at line 957 of file fiber.c.

void fbr_enable_backtraces	(	FBR_P	,
		int	enabled
	)

Enables/Disables backtrace capturing.

Parameters

[in] enabled are backtraces enabled?

The library tries to capture backtraces at certain points which may help when debugging obscure problems. For example it captures the backtrace whenever a fiber is reclaimed and when one tries to call it dumps out the backtrace showing where was it reclaimed. But these cost quite a bit of cpu and are disabled by default.

void fbr_ev_cond_var_init	(	FBR_P_ struct fbr_ev_cond_var *	ev,
		struct fbr_cond_var *	cond,
		struct fbr_mutex *	mutex
	)

Initializer for conditional variable event.

This functions properly initializes fbr_ev_cond_var struct. You should not do it manually.

See Also: fbr_ev_cond_var; fbr_ev_wait

Definition at line 1061 of file fiber.c.

void fbr_ev_mutex_init	(	FBR_P_ struct fbr_ev_mutex *	ev,
		struct fbr_mutex *	mutex
	)

Initializer for mutex event.

This functions properly initializes fbr_ev_mutex struct. You should not do it manually.

See Also: fbr_ev_mutex; fbr_ev_wait

Definition at line 992 of file fiber.c.

struct fbr_ev_base* fbr_ev_wait ( FBR_P_ struct fbr_ev_base * events[] )

read

Event awaiting function (generic one).

Parameters

[in] events array of event base pointers

Returns: an event that has arrived.

This function waits until any event from events array arrives. Only one event can arrive at a time. It returns a pointer to the same event that was passed in events array.

See Also: fbr_ev_base; fbr_ev_wait_one

Definition at line 518 of file fiber.c.

void fbr_ev_wait_one ( FBR_P_ struct fbr_ev_base * one )

Event awaiting function (one event only wrapper).

Parameters

[in] one the event base pointer of the event to wait for

This functions wraps fbr_ev_wait passing only one event to it.

See Also: fbr_ev_base; fbr_ev_wait

Definition at line 555 of file fiber.c.

void fbr_ev_watcher_init	(	FBR_P_ struct fbr_ev_watcher *	ev,
		ev_watcher *	w
	)

Initializer for libev watcher event.

This functions properly initializes fbr_ev_watcher struct. You should not do it manually.

See Also: fbr_ev_watcher; fbr_ev_wait

Definition at line 611 of file fiber.c.

int fbr_fd_nonblock ( FBR_P_ int fd )

Utility function to make file descriptor non-blocking.

Parameters

[in] fd file descriptor to make non-blocking

Returns: -1 on error with f_errno set, 0 upon success

In case of failure FBR_ESYSTEM is set as f_errno ans user should consult system errno for details.

Definition at line 587 of file fiber.c.

void fbr_free ( FBR_P_ void * ptr )

Explicitly frees allocated memory chunk.

Parameters

[in] ptr chunk address

Explicitly frees a fiber pool chunk calling the destructor if any.

See Also: fbr_alloc; fbr_calloc; fbr_alloc_set_destructor

Definition at line 947 of file fiber.c.

void fbr_free_nd ( FBR_P_ void * ptr )

Explicitly frees allocated memory chunk.

Parameters

[in] ptr chunk address

Explicitly frees a fiber pool chunk without calling the destructor.

See Also: fbr_alloc; fbr_calloc; fbr_alloc_set_destructor

Definition at line 952 of file fiber.c.

void* fbr_get_user_data ( FBR_P_ fbr_id_t id )

Gets fiber user data pointer.

Parameters

[in] id fiber id

Returns: user data pointer on success, NULL on failure with f_errno set

This function allows you to retrieve user data pointer.

See Also: fbr_set_user_data

Definition at line 1251 of file fiber.c.

void fbr_init	(	struct fbr_context *	fctx,
		struct ev_loop *	loop
	)

Initializes the library context.

Parameters

[in]	fctx	pointer to the user allocated fbr_context.
[in]	loop	pointer to the user supplied libev loop.

It's user's responsibility to allocate fbr_context structure and create and run the libev event loop.

See Also: fbr_context; fbr_destroy

int fbr_is_reclaimed ( FBR_P_ fbr_id_t fiber )

Tests if given fiber is reclaimed.

Parameters

[in] fiber fiber pointer

Returns: 1 if fiber is reclaimed, 0 otherwise

void void void void void fbr_log_d	(	FBR_P_ const char *	format,
			...
	)

Utility log wrapper.

Wraps logv function of type fbr_log_func_t located in fbr_logger with log level of FBR_LOG_DEBUG. Follows printf semantics of format string and variadic argument list.

See Also: fbr_context; fbr_logger; fbr_log_func_t; fbr_logutil_func_t

void fbr_log_e	(	FBR_P_ const char *	format,
			...
	)

Utility log wrapper.

Wraps logv function of type fbr_log_func_t located in fbr_logger with log level of FBR_LOG_ERROR. Follows printf semantics of format string and variadic argument list.

See Also: fbr_context; fbr_logger; fbr_log_func_t; fbr_logutil_func_t

void void void void fbr_log_i	(	FBR_P_ const char *	format,
			...
	)

Utility log wrapper.

Wraps logv function of type fbr_log_func_t located in fbr_logger with log level of FBR_LOG_INFO. Follows printf semantics of format string and variadic argument list.

See Also: fbr_context; fbr_logger; fbr_log_func_t; fbr_logutil_func_t

void void void fbr_log_n	(	FBR_P_ const char *	format,
			...
	)

Utility log wrapper.

Wraps logv function of type fbr_log_func_t located in fbr_logger with log level of FBR_LOG_NOTICE. Follows printf semantics of format string and variadic argument list.

See Also: fbr_context; fbr_logger; fbr_log_func_t; fbr_logutil_func_t

void void fbr_log_w	(	FBR_P_ const char *	format,
			...
	)

Utility log wrapper.

Wraps logv function of type fbr_log_func_t located in fbr_logger with log level of FBR_LOG_WARNING. Follows printf semantics of format string and variadic argument list.

See Also: fbr_context; fbr_logger; fbr_log_func_t; fbr_logutil_func_t

struct fbr_mutex* fbr_mutex_create ( FBR_P )

read

Creates a mutex.

Returns: newly allocated mutex

Mutexes are helpful when your fiber has a critical code section including several fbr_* calls. In this case execution of multiple copies of your fiber may get mixed up.

See Also: fbr_mutex_lock; fbr_mutex_trylock; fbr_mutex_unlock; fbr_mutex_destroy

void fbr_mutex_destroy ( FBR_P_ struct fbr_mutex * mutex )

Frees a mutex.

Parameters

[in] mutex pointer to mutex created by fbr_mutex_create

Frees used resources. It does not unlock the mutex.

See Also: fbr_mutex_create; fbr_mutex_lock; fbr_mutex_unlock; fbr_mutex_trylock

void fbr_mutex_lock ( FBR_P_ struct fbr_mutex * mutex )

Locks a mutex.

Parameters

[in] mutex pointer to mutex created by fbr_mutex_create

Attempts to lock a mutex. If mutex is already locked then the calling fiber is suspended until the mutex is eventually freed.

See Also: fbr_mutex_create; fbr_mutex_trylock; fbr_mutex_unlock; fbr_mutex_destroy

Definition at line 1008 of file fiber.c.

int fbr_mutex_trylock ( FBR_P_ struct fbr_mutex * mutex )

Tries to locks a mutex.

Parameters

[in] mutex pointer to mutex created by fbr_mutex_create

Returns: 1 if lock was successful, 0 otherwise

Attempts to lock a mutex. Returns immediately despite of locking being successful or not.

See Also: fbr_mutex_create; fbr_mutex_lock; fbr_mutex_unlock; fbr_mutex_destroy

Definition at line 1017 of file fiber.c.

void fbr_mutex_unlock ( FBR_P_ struct fbr_mutex * mutex )

Unlocks a mutex.

Parameters

[in] mutex pointer to mutex created by fbr_mutex_create

Unlocks the given mutex. An other fiber that is waiting for it (if any) will be called upon next libev loop iteration.

See Also: fbr_mutex_create; fbr_mutex_lock; fbr_mutex_trylock; fbr_mutex_destroy

Definition at line 1026 of file fiber.c.

fbr_id_t fbr_parent ( FBR_P )

Find out current fiber's parent.

Returns: current fiber's parent

This function allows you to find out what fiber is considered to be parent for the current one.

See Also: fbr_create; fbr_disown

Definition at line 917 of file fiber.c.

ssize_t fbr_read	(	FBR_P_ int	fd,
		void *	buf,
		size_t	count
	)

Fiber friendly libc read wrapper.

Parameters

[in]	fd	file descriptor to read from
[in]	buf	pointer to some user-allocated buffer
[in]	count	maximum number of bytes to read

Returns: number of bytes read on success, -1 in case of error and errno set

Attempts to read up to count bytes from file descriptor fd into the buffer starting at buf. Calling fiber will be blocked until something arrives at fd.

Possible errno values are described in read man page. The only special case is EINTR which is handled internally and is returned to the caller only in case when non-root fiber called the fiber waiting in fbr_read.

See Also: fbr_read_all; fbr_read_line

Definition at line 617 of file fiber.c.

ssize_t fbr_read_all	(	FBR_P_ int	fd,
		void *	buf,
		size_t	count
	)

Even more fiber friendly libc read wrapper.

Parameters

[in]	fd	file descriptor to read from
[in]	buf	pointer to some user-allocated buffer
[in]	count	desired number of bytes to read

Returns: number of bytes read on success, -1 in case of error and errno set

Attempts to read exactly count bytes from file descriptor fd into the buffer starting at buf. Calling fiber will be blocked until the required amount of data or EOF arrive at fd. If latter occurs too early returned number of bytes will be less that required.

Possible errno values are described in read man page. Unlike fbr_read this function will never return -1 with EINTR and will silently ignore any attempts to call this fiber from other non-root fibers (call infos are still queued if the called desired to do so).

See Also: fbr_read; fbr_read_line

Definition at line 638 of file fiber.c.

ssize_t fbr_readline	(	FBR_P_ int	fd,
		void *	buffer,
		size_t	n
	)

Utility function to read a line.

Parameters

[in]	fd	file descriptor to read from
[in]	buffer	pointer to some user-allocated buffer
[in]	n	maximum number of bytes to read

Returns: number of bytes read on success, -1 in case of error and errno set

Attempts to read at most count bytes from file descriptor fd into the buffer starting at buf, but stops if newline is encountered. Calling fiber will be blocked until the required amount of data, EOF or newline arrive at fd.

Possible errno values are described in read man page. As with fbr_read_all this function will never return -1 with EINTR.

See Also: fbr_read; fbr_read_all

Definition at line 679 of file fiber.c.

int fbr_reclaim ( FBR_P_ fbr_id_t fiber )

Reclaims a fiber.

Parameters

[in] fiber fiber pointer

Returns: -1 on error with f_errno set, 0 upon success

Fibers are never destroyed, but reclaimed. Reclamation frees some resources like call lists and memory pools immediately while keeping fiber structure itself and its stack as is. Reclaimed fiber is prepended to the reclaimed fiber list and will be served as a new one whenever next fbr_create is called. Fiber is prepended because it is warm in terms of cpu cache and its use might be faster than any other fiber in the list.

When you have some reclaimed fibers in the list, reclaiming and creating are generally cheap operations.

Definition at line 413 of file fiber.c.

ssize_t fbr_recvfrom	(	FBR_P_ int	sockfd,
		void *	buf,
		size_t	len,
		int	flags,
		struct sockaddr *	src_addr,
		socklen_t *	addrlen
	)

Fiber friendly libc recvfrom wrapper.

Parameters

[in]	sockfd	file descriptor to read from
[in]	buf	pointer to some user-allocated buffer
[in]	len	maximum number of bytes to read
[in]	flags	just flags, see man recvfrom for details
[in]	src_addr	source address
[in]	addrlen	size of src_addr

Returns: number of bytes read on success, -1 in case of error and errno set

This function is used to receive messages from a socket.

Possible errno values are described in recvfrom man page. The only special case is EINTR which is handled internally and is returned to the caller only in case when non-root fiber called the fiber sitting in fbr_recvfrom.

Definition at line 783 of file fiber.c.

fbr_id_t fbr_self ( FBR_P )

Returns id of current fiber.

Returns: fbr_id_t of current fiber being executed.

Definition at line 435 of file fiber.c.

ssize_t fbr_sendto	(	FBR_P_ int	sockfd,
		const void *	buf,
		size_t	len,
		int	flags,
		const struct sockaddr *	dest_addr,
		socklen_t	addrlen
	)

Fiber friendly libc sendto wrapper.

Parameters

[in]	sockfd	file descriptor to write to
[in]	buf	pointer to some user-allocated buffer
[in]	len	maximum number of bytes to write
[in]	flags	just flags, see man sendto for details
[in]	dest_addr	destination address
[in]	addrlen	size of dest_addr

Returns: number of bytes written on success, -1 in case of error and errno set

This function is used to send messages to a socket.

Possible errno values are described in sendto man page. The only special case is EINTR which is handled internally and is returned to the caller only in case when non-root fiber called the fiber sitting in fbr_sendto.

Definition at line 800 of file fiber.c.

int fbr_set_user_data	(	FBR_P_ fbr_id_t	id,
		void *	data
	)

Sets fiber user data pointer.

Parameters

[in]	id	fiber id
[in]	data	pointer to user data

Returns: 0 on success, -1 upon failure with f_errno set

This function allows you to extend fiber with some user structure.

See Also: fbr_get_user_data

Definition at line 1258 of file fiber.c.

ev_tstamp fbr_sleep ( FBR_P_ ev_tstamp seconds )

Puts current fiber to sleep.

Parameters

[in] seconds maximum number of seconds to sleep

Returns: number of seconds actually being asleep

This function is used to put current fiber into sleep. It will wake up after the desired time has passed or earlier if some other fiber has called it.

Definition at line 838 of file fiber.c.

const char* fbr_strerror ( FBR_P_ enum fbr_error_code code )

Analog of strerror but for the library errno.

Parameters

[in] code Error code to describe

See Also: fbr_context; fbr_error_code

int fbr_transfer ( FBR_P_ fbr_id_t to )

Transfer of fiber context to another fiber.

Parameters

[in] to callee id

Returns: 0 on success, -1 on failure with f_errno set.

This function transfers the execution context to other fiber. It returns as soon as the called fiber yields. In case of error it returns immediately.

See Also: fbr_yield

Definition at line 563 of file fiber.c.

ssize_t fbr_write	(	FBR_P_ int	fd,
		const void *	buf,
		size_t	count
	)

Fiber friendly libc write wrapper.

Parameters

[in]	fd	file descriptor to write to
[in]	buf	pointer to some user-allocated buffer
[in]	count	maximum number of bytes to write

Returns: number of bytes written on success, -1 in case of error and errno set

Attempts to write up to count bytes to file descriptor fd from the buffer starting at buf. Calling fiber will be blocked until the data is written.

Possible errno values are described in write man page. The only special case is EINTR which is handled internally and is returned to the caller only in case when non-root fiber called the fiber sitting in fbr_write.

See Also: fbr_write_all

Definition at line 724 of file fiber.c.

ssize_t fbr_write_all	(	FBR_P_ int	fd,
		const void *	buf,
		size_t	count
	)

Even more fiber friendly libc write wrapper.

Parameters

[in]	fd	file descriptor to write to
[in]	buf	pointer to some user-allocated buffer
[in]	count	desired number of bytes to write

Returns: number of bytes read on success, -1 in case of error and errno set

Attempts to write exactly count bytes to file descriptor fd from the buffer starting at buf. Calling fiber will be blocked until the required amount of data is written to fd.

Possible errno values are described in write man page. Unlike fbr_write this function will never return -1 with EINTR and will silently ignore any attempts to call this fiber from other non-root fibers (call infos are still queued if the called desired to do so).

See Also: fbr_write

Definition at line 744 of file fiber.c.

void fbr_yield ( FBR_P )

Yields execution to other fiber.

When a fiber is waiting for some incoming event — it should yield. This will pop current fiber from the fiber stack and transfer the execution context to the next fiber from the stack making that fiber a new current one.

It loops through all fibers subscribed to specified multicast group id.

See Also: fbr_transfer

Definition at line 580 of file fiber.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation