libuev 2.4.1
uev.h File Reference
#include "private.h"

Go to the source code of this file.

Classes

struct  uev
 

Macros

#define UEV_MAX_EVENTS   10
 
#define UEV_NONE   0
 
#define UEV_ERROR   EPOLLERR
 
#define UEV_READ   EPOLLIN
 
#define UEV_WRITE   EPOLLOUT
 
#define UEV_PRI   EPOLLPRI
 
#define UEV_HUP   EPOLLHUP
 
#define UEV_RDHUP   EPOLLRDHUP
 
#define UEV_EDGE   EPOLLET
 
#define UEV_ONESHOT   EPOLLONESHOT
 
#define UEV_ONCE   1
 
#define UEV_NONBLOCK   2
 
#define uev_io_active(w)
 
#define uev_signal_active(w)
 
#define uev_timer_active(w)
 
#define uev_cron_active(w)
 
#define uev_event_active(w)
 

Typedefs

typedef struct uev_ctx uev_ctx_t
 
typedef struct uev uev_t
 
typedef void uev_cb_t(uev_t *w, void *arg, int events)
 

Functions

int uev_init (uev_ctx_t *ctx)
 
int uev_init1 (uev_ctx_t *ctx, int maxevents)
 
int uev_exit (uev_ctx_t *ctx)
 
int uev_run (uev_ctx_t *ctx, int flags)
 
int uev_io_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int fd, int events)
 
int uev_io_set (uev_t *w, int fd, int events)
 
int uev_io_start (uev_t *w)
 
int uev_io_stop (uev_t *w)
 
int uev_timer_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int timeout, int period)
 
int uev_timer_set (uev_t *w, int timeout, int period)
 
int uev_timer_start (uev_t *w)
 
int uev_timer_stop (uev_t *w)
 
int uev_cron_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, time_t when, time_t interval)
 
int uev_cron_set (uev_t *w, time_t when, time_t interval)
 
int uev_cron_start (uev_t *w)
 
int uev_cron_stop (uev_t *w)
 
int uev_signal_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int signo)
 
int uev_signal_set (uev_t *w, int signo)
 
int uev_signal_start (uev_t *w)
 
int uev_signal_stop (uev_t *w)
 
int uev_event_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg)
 
int uev_event_post (uev_t *w)
 
int uev_event_stop (uev_t *w)
 

Detailed Description

Micro event loop library

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

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

Definition in file uev.h.

Macro Definition Documentation

◆ uev_cron_active

#define uev_cron_active ( w)
Value:
_uev_watcher_active(w)

Check if cron timer watcher is active or stopped

Definition at line 65 of file uev.h.

◆ UEV_EDGE

#define UEV_EDGE   EPOLLET

edge triggered

Definition at line 51 of file uev.h.

◆ UEV_ERROR

#define UEV_ERROR   EPOLLERR

error flag

Definition at line 45 of file uev.h.

◆ uev_event_active

#define uev_event_active ( w)
Value:
_uev_watcher_active(w)

Check if event watcher is active or stopped

Definition at line 67 of file uev.h.

◆ UEV_HUP

#define UEV_HUP   EPOLLHUP

hangup event

Definition at line 49 of file uev.h.

◆ uev_io_active

#define uev_io_active ( w)
Value:
_uev_watcher_active(w)

Check if I/O watcher is active or stopped

Definition at line 59 of file uev.h.

◆ UEV_MAX_EVENTS

#define UEV_MAX_EVENTS   10

Max. number of simulateneous events

Definition at line 41 of file uev.h.

◆ UEV_NONBLOCK

#define UEV_NONBLOCK   2

exit if no event

Definition at line 56 of file uev.h.

◆ UEV_NONE

#define UEV_NONE   0

normal loop

Definition at line 44 of file uev.h.

◆ UEV_ONCE

#define UEV_ONCE   1

run loop once

Definition at line 55 of file uev.h.

◆ UEV_ONESHOT

#define UEV_ONESHOT   EPOLLONESHOT

one-shot event

Definition at line 52 of file uev.h.

◆ UEV_PRI

#define UEV_PRI   EPOLLPRI

priority message

Definition at line 48 of file uev.h.

◆ UEV_RDHUP

#define UEV_RDHUP   EPOLLRDHUP

peer shutdown

Definition at line 50 of file uev.h.

◆ UEV_READ

#define UEV_READ   EPOLLIN

poll for reading

Definition at line 46 of file uev.h.

◆ uev_signal_active

#define uev_signal_active ( w)
Value:
_uev_watcher_active(w)

Check if signal watcher is active or stopped

Definition at line 61 of file uev.h.

◆ uev_timer_active

#define uev_timer_active ( w)
Value:
_uev_watcher_active(w)

Check if timer is active or stopped

Definition at line 63 of file uev.h.

◆ UEV_WRITE

#define UEV_WRITE   EPOLLOUT

poll for writing

Definition at line 47 of file uev.h.

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.

Definition at line 97 of file uev.h.

◆ uev_ctx_t

typedef struct uev_ctx uev_ctx_t

Event loop context, need one per process and thread

Definition at line 70 of file uev.h.

◆ uev_t

typedef struct uev uev_t

Event watcher

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
ctxA valid libuEv context
wPointer to an uev_t watcher
cbCallback function for cron job
argOptional callback argument
whenFirst point in time to call cb
intervalFor 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.

Definition at line 66 of file cron.c.

◆ uev_cron_set()

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

Reset an at/cron job watcher

Parameters
wWatcher to reset
whenFirst point in time to call cb
intervalFor an at job this is zero, for cron the offset interval
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 100 of file cron.c.

◆ uev_cron_start()

int uev_cron_start ( uev_t * w)

Start a stopped at/cron job watcher

Parameters
wWatcher to start (again)
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 145 of file cron.c.

◆ uev_cron_stop()

int uev_cron_stop ( uev_t * w)

Stop and unregister an at/cron job watcher

Parameters
wWatcher to stop
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 156 of file cron.c.

◆ 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
ctxA valid libuEv context
wPointer to an uev_t watcher
cbCallback when an event is posted
argOptional callback argument
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 46 of file event.c.

◆ uev_event_post()

int uev_event_post ( uev_t * w)

Post a generic event

Parameters
wWatcher to post to
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 70 of file event.c.

◆ uev_event_stop()

int uev_event_stop ( uev_t * w)

Stop a generic event watcher

Parameters
wWatcher to stop
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 92 of file event.c.

◆ uev_exit()

int uev_exit ( uev_ctx_t * ctx)

Terminate the event loop

Parameters
ctxA valid libuEv context
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 240 of file uev.c.

◆ uev_init()

int uev_init ( uev_ctx_t * ctx)

Create an event loop context

Create an event loop context

Parameters
ctxPointer 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.

Definition at line 191 of file uev.c.

◆ uev_init1()

int uev_init1 ( uev_ctx_t * ctx,
int maxevents )

Create an event loop context

Parameters
ctxPointer to an uev_ctx_t context to be initialized
maxeventsMaximum 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):

  1. use this function to initialize your event loop and set maxevents to 1
  2. 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.

Definition at line 218 of file uev.c.

◆ 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
ctxA valid libuEv context
wPointer to an uev_t watcher
cbI/O callback
argOptional callback argument
fdFile descriptor to watch, or -1 to register an empty watcher
eventsEvents to watch for: UEV_READ, UEV_WRITE, UEV_EDGE, UEV_ONESHOT
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 44 of file io.c.

◆ uev_io_set()

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

Reset an I/O watcher

Parameters
wPointer to an uev_t watcher
fdNew file descriptor to monitor
eventsRequested events to watch for, a mask of UEV_READ and UEV_WRITE
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 65 of file io.c.

◆ uev_io_start()

int uev_io_start ( uev_t * w)

Start an I/O watcher

Parameters
wWatcher to start (again)
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 82 of file io.c.

◆ uev_io_stop()

int uev_io_stop ( uev_t * w)

Stop an I/O watcher

Parameters
wWatcher to stop
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 93 of file io.c.

◆ uev_run()

int uev_run ( uev_ctx_t * ctx,
int flags )

Start the event loop

Parameters
ctxA valid libuEv context
flagsA 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.

Definition at line 299 of file uev.c.

◆ 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
ctxA valid libuEv context
wPointer to an uev_t watcher
cbSignal callback
argOptional callback argument
signoSignal to watch for
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 52 of file signal.c.

◆ uev_signal_set()

int uev_signal_set ( uev_t * w,
int signo )

Reset a signal watcher

Parameters
wWatcher to reset
signoNew signal to watch for
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 88 of file signal.c.

◆ uev_signal_start()

int uev_signal_start ( uev_t * w)

Start a stopped signal watcher

Parameters
wWatcher to start (again)
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 128 of file signal.c.

◆ uev_signal_stop()

int uev_signal_stop ( uev_t * w)

Stop a signal watcher

Parameters
wWatcher to stop
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 147 of file signal.c.

◆ 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
ctxA valid libuEv context
wPointer to an uev_t watcher
cbCallback function
argOptional callback argument
timeoutTimeout in milliseconds before cb is called
periodFor 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.

Definition at line 77 of file timer.c.

◆ uev_timer_set()

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

Reset a timer

Parameters
wWatcher to reset
timeoutTimeout in milliseconds before cb is called, zero disarms timer
periodFor 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.

Definition at line 116 of file timer.c.

◆ uev_timer_start()

int uev_timer_start ( uev_t * w)

Start a stopped timer watcher

Parameters
wWatcher to start (again)
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 160 of file timer.c.

◆ uev_timer_stop()

int uev_timer_stop ( uev_t * w)

Stop and unregister a timer watcher

Parameters
wWatcher to stop
Returns
POSIX OK(0) or non-zero with errno set on error.

Definition at line 179 of file timer.c.