Micro event loop library. More...

#include "private.h"

Include dependency graph for uev.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	uev
	Event watcher. More...

Macros
#define	UEV_MAX_EVENTS 10
	Max. More...

#define	UEV_NONE 0
	normal loop

#define	UEV_ERROR EPOLLERR
	error flag

#define	UEV_READ EPOLLIN
	poll for reading

#define	UEV_WRITE EPOLLOUT
	poll for writing

#define	UEV_PRI EPOLLPRI
	priority message

#define	UEV_HUP EPOLLHUP
	hangup event

#define	UEV_RDHUP EPOLLRDHUP
	peer shutdown

#define	UEV_EDGE EPOLLET
	edge triggered

#define	UEV_ONESHOT EPOLLONESHOT
	one-shot event

#define	UEV_ONCE 1
	run loop once

#define	UEV_NONBLOCK 2
	exit if no event

#define	uev_io_active(w) _uev_watcher_active(w)
	Check if I/O watcher is active or stopped.

#define	uev_signal_active(w) _uev_watcher_active(w)
	Check if signal watcher is active or stopped.

#define	uev_timer_active(w) _uev_watcher_active(w)
	Check if timer is active or stopped.

#define	uev_cron_active(w) _uev_watcher_active(w)
	Check if cron timer watcher is active or stopped.

#define	uev_event_active(w) _uev_watcher_active(w)
	Check if event watcher is active or stopped.

Typedefs
typedef struct uev_ctx	uev_ctx_t
	Event loop context, need one per process and thread.

typedef struct uev	uev_t
	Event watcher.

typedef void()	uev_cb_t(uev_t w, void arg, int events)
	Generic callback for watchers, `events` holds UEV_READ and/or UEV_WRITE with optional UEV_PRI (priority data available to read) and any of the UEV_HUP and/or UEV_RDHUP, which may be used to signal hang-up and peer shutdown events. More...

Functions
int	uev_init (uev_ctx_t *ctx)
	Create an event loop context. More...

int	uev_init1 (uev_ctx_t *ctx, int maxevents)
	Create an event loop context. More...

int	uev_exit (uev_ctx_t *ctx)
	Terminate the event loop. More...

int	uev_run (uev_ctx_t *ctx, int flags)
	Start the event loop. More...

int	uev_io_init (uev_ctx_t ctx, uev_t w, uev_cb_t cb, void arg, int fd, int events)
	Create an I/O watcher. More...

int	uev_io_set (uev_t *w, int fd, int events)
	Reset an I/O watcher. More...

int	uev_io_start (uev_t *w)
	Start an I/O watcher. More...

int	uev_io_stop (uev_t *w)
	Stop an I/O watcher. More...

int	uev_timer_init (uev_ctx_t ctx, uev_t w, uev_cb_t cb, void arg, int timeout, int period)
	Create and start a timer watcher. More...

int	uev_timer_set (uev_t *w, int timeout, int period)
	Reset a timer. More...

int	uev_timer_start (uev_t *w)
	Start a stopped timer watcher. More...

int	uev_timer_stop (uev_t *w)
	Stop and unregister a timer watcher. More...

int	uev_cron_init (uev_ctx_t ctx, uev_t w, uev_cb_t cb, void arg, time_t when, time_t interval)
	Create and start an at/cron job watcher. More...

int	uev_cron_set (uev_t *w, time_t when, time_t interval)
	Reset an at/cron job watcher. More...

int	uev_cron_start (uev_t *w)
	Start a stopped at/cron job watcher. More...

int	uev_cron_stop (uev_t *w)
	Stop and unregister an at/cron job watcher. More...

int	uev_signal_init (uev_ctx_t ctx, uev_t w, uev_cb_t cb, void arg, int signo)
	Create a signal watcher. More...

int	uev_signal_set (uev_t *w, int signo)
	Reset a signal watcher. More...

int	uev_signal_start (uev_t *w)
	Start a stopped signal watcher. More...

int	uev_signal_stop (uev_t *w)
	Stop a signal watcher. More...

int	uev_event_init (uev_ctx_t ctx, uev_t w, uev_cb_t cb, void arg)
	Create a generic event watcher. More...

int	uev_event_post (uev_t *w)
	Post a generic event. More...

int	uev_event_stop (uev_t *w)
	Stop a generic event watcher. More...

Detailed Description

Micro event loop library.

Author: Flemming Madsen (2012); Joachim Wiberg (2013-2021)

Copyright: MIT License

The latest version of this manual and the libuEv software are available at https://github.com/troglobit/libuEv/

Macro Definition Documentation

◆ UEV_MAX_EVENTS

#define UEV_MAX_EVENTS 10

Max.

number of simulateneous events

Typedef Documentation

◆ uev_cb_t

typedef void() uev_cb_t(uev_t *w, void *arg, int events)

Generic callback for watchers, events holds UEV_READ and/or UEV_WRITE with optional UEV_PRI (priority data available to read) and any of the UEV_HUP and/or UEV_RDHUP, which may be used to signal hang-up and peer shutdown events.

Note: UEV_ERROR conditions must be handled by all callbacks! I/O watchers may also need to check UEV_HUP. Appropriate action, e.g. restart the watcher, is up to the application and is thus delegated to the callback.

Function Documentation

◆ uev_cron_init()

int uev_cron_init	(	uev_ctx_t *	ctx,
		uev_t *	w,
		uev_cb_t *	cb,
		void *	arg,
		time_t	when,
		time_t	interval
	)

Create and start an at/cron job watcher.

Parameters

ctx	A valid libuEv context
w	Pointer to an uev_t watcher
cb	Callback function for cron job
arg	Optional callback argument
when	First point in time to call `cb`
interval	For an at job this is zero, for cron the offset interval

For at jobs set interval to zero and only use when. For cron jobs, set interval to the offset. E.g., if the job should run every five minutes set the tm_min of struct tm to five.

Use mktime() to create the time_t arguments. The special value zero may be used for when to denote 'now', where 'now' is when the event loop is started. You can also treat time_t simply as a signed integer. E.g., set interval to 3600 to create a cron job that runs every hour.

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_cron_set()

int uev_cron_set	(	uev_t *	w,
		time_t	when,
		time_t	interval
	)

Reset an at/cron job watcher.

Parameters

w	Watcher to reset
when	First point in time to call `cb`
interval	For an at job this is zero, for cron the offset interval

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_cron_start()

int uev_cron_start ( uev_t * w )

Start a stopped at/cron job watcher.

Parameters

w	Watcher to start (again)

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_cron_stop()

int uev_cron_stop ( uev_t * w )

Stop and unregister an at/cron job watcher.

Parameters

w	Watcher to stop

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_event_init()

int uev_event_init	(	uev_ctx_t *	ctx,
		uev_t *	w,
		uev_cb_t *	cb,
		void *	arg
	)

Create a generic event watcher.

Parameters

ctx	A valid libuEv context
w	Pointer to an uev_t watcher
cb	Callback when an event is posted
arg	Optional callback argument

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_event_post()

int uev_event_post ( uev_t * w )

Post a generic event.

Parameters

w	Watcher to post to

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_event_stop()

int uev_event_stop ( uev_t * w )

Stop a generic event watcher.

Parameters

w	Watcher to stop

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_exit()

int uev_exit ( uev_ctx_t * ctx )

Terminate the event loop.

Parameters

ctx	A valid libuEv context

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_init()

int uev_init ( uev_ctx_t * ctx )

Create an event loop context.

Parameters

ctx	Pointer to an uev_ctx_t context to be initialized

This function calls uev_init1() with maxevents set to UEV_MAX_EVENTS

Returns: POSIX OK(0) on success, or non-zero on error.

◆ uev_init1()

int uev_init1	(	uev_ctx_t *	ctx,
		int	maxevents
	)

Create an event loop context.

Parameters

ctx	Pointer to an uev_ctx_t context to be initialized
maxevents	Maximum number of events in event cache [1, 10]

This function is the same as uev_init() except for the maxevents argument, max UEV_MAX_EVENTS, which controls the number of events in the event cache returned to the main loop.

In cases where you have multiple events pending in the cache and some event may cause later ones, already sent by the kernel to userspace, to be deleted the pointer returned to the event loop for this later event may be deleted.

There are two ways around this (accessing deleted memory):

use this function to initialize your event loop and set maxevents to 1
use a free list in you application that you garbage collect at intervals relevant to your application

Returns: POSIX OK(0) on success, or non-zero on error.

◆ uev_io_init()

int uev_io_init	(	uev_ctx_t *	ctx,
		uev_t *	w,
		uev_cb_t *	cb,
		void *	arg,
		int	fd,
		int	events
	)

Create an I/O watcher.

Parameters

ctx	A valid libuEv context
w	Pointer to an uev_t watcher
cb	I/O callback
arg	Optional callback argument
fd	File descriptor to watch, or -1 to register an empty watcher
events	Events to watch for: UEV_READ, UEV_WRITE, UEV_EDGE, UEV_ONESHOT

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_io_set()

int uev_io_set	(	uev_t *	w,
		int	fd,
		int	events
	)

Reset an I/O watcher.

Parameters

w	Pointer to an uev_t watcher
fd	New file descriptor to monitor
events	Requested events to watch for, a mask of UEV_READ and UEV_WRITE

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_io_start()

int uev_io_start ( uev_t * w )

Start an I/O watcher.

Parameters

w	Watcher to start (again)

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_io_stop()

int uev_io_stop ( uev_t * w )

Stop an I/O watcher.

Parameters

w	Watcher to stop

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_run()

int uev_run	(	uev_ctx_t *	ctx,
		int	flags
	)

Start the event loop.

Parameters

ctx	A valid libuEv context
flags	A mask of UEV_ONCE and UEV_NONBLOCK, or zero

With flags set to UEV_ONCE the event loop returns after the first event has been served, useful for instance to set a timeout on a file descriptor. If flags also has the UEV_NONBLOCK flag set the event loop will return immediately if no event is pending, useful when run inside another event loop.

Returns: POSIX OK(0) upon successful termination of the event loop, or non-zero on error.

◆ uev_signal_init()

int uev_signal_init	(	uev_ctx_t *	ctx,
		uev_t *	w,
		uev_cb_t *	cb,
		void *	arg,
		int	signo
	)

Create a signal watcher.

Parameters

ctx	A valid libuEv context
w	Pointer to an uev_t watcher
cb	Signal callback
arg	Optional callback argument
signo	Signal to watch for

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_signal_set()

int uev_signal_set	(	uev_t *	w,
		int	signo
	)

Reset a signal watcher.

Parameters

w	Watcher to reset
signo	New signal to watch for

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_signal_start()

int uev_signal_start ( uev_t * w )

Start a stopped signal watcher.

Parameters

w	Watcher to start (again)

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_signal_stop()

int uev_signal_stop ( uev_t * w )

Stop a signal watcher.

Parameters

w	Watcher to stop

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_timer_init()

int uev_timer_init	(	uev_ctx_t *	ctx,
		uev_t *	w,
		uev_cb_t *	cb,
		void *	arg,
		int	timeout,
		int	period
	)

Create and start a timer watcher.

Parameters

ctx	A valid libuEv context
w	Pointer to an uev_t watcher
cb	Callback function
arg	Optional callback argument
timeout	Timeout in milliseconds before `cb` is called
period	For periodic timers this is the period time that `timeout` is reset to

This function creates, and optionally starts, a timer watcher. There are two types of timers: one-shot and periodic.

One-shot timers only use timeout, period is zero.

Periodic timers can either start their life disabled, with timeout set to zero, or with the same value as period.

When the timeout expires, for either of the two types, cb is called, with the optional arg argument. A one-shot timer ends its life there, while a periodic task's timeout is reset to the period and restarted.

A timer is automatically started if the event loop is already running, otherwise it is kept on hold until triggered by calling uev_run().

See also: uev_timer_set

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_timer_set()

int uev_timer_set	(	uev_t *	w,
		int	timeout,
		int	period
	)

Reset a timer.

Parameters

w	Watcher to reset
timeout	Timeout in milliseconds before `cb` is called, zero disarms timer
period	For periodic timers this is the period time that `timeout` is reset to

Note, the timeout value must be non-zero. Setting it to zero disarms the timer. This is the behavior of the underlying Linux function timerfd_settimer(2)

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_timer_start()

int uev_timer_start ( uev_t * w )

Start a stopped timer watcher.

Parameters

w	Watcher to start (again)

Returns: POSIX OK(0) or non-zero with errno set on error.

◆ uev_timer_stop()

int uev_timer_stop ( uev_t * w )

Stop and unregister a timer watcher.

Parameters

w	Watcher to stop

Returns: POSIX OK(0) or non-zero with errno set on error.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ UEV_MAX_EVENTS

Typedef Documentation

◆ uev_cb_t

Function Documentation

◆ uev_cron_init()

◆ uev_cron_set()

◆ uev_cron_start()

◆ uev_cron_stop()

◆ uev_event_init()

◆ uev_event_post()

◆ uev_event_stop()

◆ uev_exit()

◆ uev_init()

◆ uev_init1()

◆ uev_io_init()

◆ uev_io_set()

◆ uev_io_start()

◆ uev_io_stop()

◆ uev_run()

◆ uev_signal_init()

◆ uev_signal_set()

◆ uev_signal_start()

◆ uev_signal_stop()

◆ uev_timer_init()

◆ uev_timer_set()

◆ uev_timer_start()

◆ uev_timer_stop()