qbloop.h File Reference

Main loop manages timers, jobs and polling sockets. More...

#include <signal.h>
#include <stdint.h>
#include <poll.h>

Include dependency graph for qbloop.h:

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

Typedefs
typedef struct qb_loop	qb_loop_t
	An opaque data type representing the main loop. More...
typedef uint64_t	qb_loop_timer_handle
typedef void *	qb_loop_signal_handle
typedef int32_t(*	qb_loop_poll_dispatch_fn )(int32_t fd, int32_t revents, void *data)
typedef void(*	qb_loop_job_dispatch_fn )(void *data)
typedef void(*	qb_loop_timer_dispatch_fn )(void *data)
typedef int32_t(*	qb_loop_signal_dispatch_fn )(int32_t rsignal, void *data)
typedef void(*	qb_loop_poll_low_fds_event_fn )(int32_t not_enough, int32_t fds_available)

Enumerations
enum	qb_loop_priority { QB_LOOP_LOW = 0, QB_LOOP_MED = 1, QB_LOOP_HIGH = 2 }
	Priorites for jobs, timers & poll. More...

Functions
qb_loop_t *	qb_loop_create (void)
	Create a new main loop. More...
void	qb_loop_destroy (struct qb_loop *l)
void	qb_loop_stop (qb_loop_t *l)
	Stop the main loop. More...
void	qb_loop_run (qb_loop_t *l)
	Run the main loop. More...
int32_t	qb_loop_job_add (qb_loop_t *l, enum qb_loop_priority p, void *data, qb_loop_job_dispatch_fn dispatch_fn)
	Add a job to the mainloop. More...
int32_t	qb_loop_job_del (struct qb_loop *l, enum qb_loop_priority p, void *data, qb_loop_job_dispatch_fn dispatch_fn)
	Delete a job from the mainloop. More...
int32_t	qb_loop_timer_add (qb_loop_t *l, enum qb_loop_priority p, uint64_t nsec_duration, void *data, qb_loop_timer_dispatch_fn dispatch_fn, qb_loop_timer_handle *timer_handle_out)
	Add a timer to the mainloop. More...
int32_t	qb_loop_timer_del (qb_loop_t *l, qb_loop_timer_handle th)
	Delete a timer that is still outstanding. More...
int32_t	qb_loop_timer_is_running (qb_loop_t *l, qb_loop_timer_handle th)
	Check to see if a timer that is still outstanding. More...
uint64_t	qb_loop_timer_expire_time_get (struct qb_loop *l, qb_loop_timer_handle th)
	Get the expiration time of the timer, as set when the timer was created. More...
uint64_t	qb_loop_timer_expire_time_remaining (struct qb_loop *l, qb_loop_timer_handle th)
	Get the time remaining before the timer expires. More...
int32_t	qb_loop_poll_low_fds_event_set (qb_loop_t *l, qb_loop_poll_low_fds_event_fn fn)
	Set a callback to receive events on file descriptors getting low. More...
int32_t	qb_loop_poll_add (qb_loop_t *l, enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_loop_poll_dispatch_fn dispatch_fn)
	Add a poll job to the mainloop. More...
int32_t	qb_loop_poll_mod (qb_loop_t *l, enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_loop_poll_dispatch_fn dispatch_fn)
	Modify a poll job. More...
int32_t	qb_loop_poll_del (qb_loop_t *l, int32_t fd)
	Delete a poll job. More...
int32_t	qb_loop_signal_add (qb_loop_t *l, enum qb_loop_priority p, int32_t sig, void *data, qb_loop_signal_dispatch_fn dispatch_fn, qb_loop_signal_handle *handle)
	Add a signal job. More...
int32_t	qb_loop_signal_mod (qb_loop_t *l, enum qb_loop_priority p, int32_t sig, void *data, qb_loop_signal_dispatch_fn dispatch_fn, qb_loop_signal_handle handle)
	Modify the signal job. More...
int32_t	qb_loop_signal_del (qb_loop_t *l, qb_loop_signal_handle handle)
	Delete the signal job. More...

Detailed Description

Main loop manages timers, jobs and polling sockets.

Only a weaker sense of priorities is implemented, alluding to distinct set of pros and cons compared to the stronger, strict approach to them as widely applied in this problem space (since the latter gives the application more control as the effect of the former can still be achieved with some reductions, whereas it is not straightforward the other way around; cf. static priority task scheduling vs. relative fine-tuning within a single priority domain with nice(2)):

• implicit mitigation for deadlock-prone priority arrangements
• less predictable (proportional probability based, we can talk about an advisory effect of the priorities) responses to the arrival of the high-ranked events (i.e. in the process of the picking the next event to handle from the priority queue when at least two different priorities are eligible at the moment)

One practical application for this module of libqb is in combination with IPC servers based on qbipcs.h published one (the qb_ipcs_poll_handlers structure maps fittingly to the control functions published here).

Typedef Documentation

typedef void(* qb_loop_job_dispatch_fn)(void *data)

Examples:

ipcserver.c.

typedef int32_t(* qb_loop_poll_dispatch_fn)(int32_t fd, int32_t revents, void *data)

typedef void(* qb_loop_poll_low_fds_event_fn)(int32_t not_enough, int32_t fds_available)

typedef int32_t(* qb_loop_signal_dispatch_fn)(int32_t rsignal, void *data)

typedef void* qb_loop_signal_handle

typedef struct qb_loop qb_loop_t

An opaque data type representing the main loop.

typedef void(* qb_loop_timer_dispatch_fn)(void *data)

typedef uint64_t qb_loop_timer_handle

Enumeration Type Documentation

enum qb_loop_priority

Priorites for jobs, timers & poll.

Enumerator
QB_LOOP_LOW
QB_LOOP_MED
QB_LOOP_HIGH

Function Documentation

qb_loop_t* qb_loop_create

(

void

)

Create a new main loop.

Returns

loop instance.

Examples:

ipcserver.c, and tcpserver.c.

void qb_loop_destroy

(

struct qb_loop *

l

)

int32_t qb_loop_job_add	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		void *	data,
		qb_loop_job_dispatch_fn	dispatch_fn
	)

Add a job to the mainloop.

This is run in the next cycle of the loop.

Note

it is a one-shot job.

Parameters

l	pointer to the loop instance
p	the priority
data	user data passed into the dispatch function
dispatch_fn	callback function

Returns

status (0 == ok, -errno == failure)

Examples:

ipcserver.c.

int32_t qb_loop_job_del	(	struct qb_loop *	l,
		enum qb_loop_priority	p,
		void *	data,
		qb_loop_job_dispatch_fn	dispatch_fn
	)

Delete a job from the mainloop.

This will try to delete the job if it hasn't run yet.

Note

this will remove the first job that matches the parameters (priority, data, dispatch_fn).

Parameters

l	pointer to the loop instance
p	the priority
data	user data passed into the dispatch function
dispatch_fn	callback function

Returns

status (0 == ok, -errno == failure)

int32_t qb_loop_poll_add	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		int32_t	fd,
		int32_t	events,
		void *	data,
		qb_loop_poll_dispatch_fn	dispatch_fn
	)

Add a poll job to the mainloop.

Note

it is a re-occurring job.

Parameters

l	pointer to the loop instance
p	the priority
fd	file descriptor.
events	(POLLIN|POLLOUT) etc ....
data	user data passed into the dispatch function
dispatch_fn	callback function

Returns

status (0 == ok, -errno == failure)

Examples:

ipcserver.c, and tcpserver.c.

int32_t qb_loop_poll_del	(	qb_loop_t *	l,
		int32_t	fd
	)

Delete a poll job.

Parameters

l	pointer to the loop instance
fd	file descriptor.

Returns

status (0 == ok, -errno == failure)

Examples:

ipcserver.c.

int32_t qb_loop_poll_low_fds_event_set	(	qb_loop_t *	l,
		qb_loop_poll_low_fds_event_fn	fn
	)

Set a callback to receive events on file descriptors getting low.

Parameters

l	pointer to the loop instance
fn	callback function.

Returns

status (0 == ok, -errno == failure)

int32_t qb_loop_poll_mod	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		int32_t	fd,
		int32_t	events,
		void *	data,
		qb_loop_poll_dispatch_fn	dispatch_fn
	)

Modify a poll job.

Parameters

l	pointer to the loop instance
p	the priority
fd	file descriptor.
events	(POLLIN|POLLOUT) etc ....
data	user data passed into the dispatch function
dispatch_fn	callback function

Returns

status (0 == ok, -errno == failure)

Examples:

ipcserver.c.

void qb_loop_run

(

qb_loop_t *

l

)

Run the main loop.

Parameters

l	pointer to the loop instance

Examples:

ipcserver.c, and tcpserver.c.

int32_t qb_loop_signal_add	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		int32_t	sig,
		void *	data,
		qb_loop_signal_dispatch_fn	dispatch_fn,
		qb_loop_signal_handle *	handle
	)

Add a signal job.

Get a callback on this signal (not in the context of the signal).

Parameters

l	pointer to the loop instance
p	the priority
sig	(SIGHUP or SIGINT) etc ....
data	user data passed into the dispatch function
dispatch_fn	callback function
handle	(out) a reference to the signal job

Returns

status (0 == ok, -errno == failure)

Examples:

tcpserver.c.

int32_t qb_loop_signal_del	(	qb_loop_t *	l,
		qb_loop_signal_handle	handle
	)

Delete the signal job.

Parameters

l	pointer to the loop instance
handle	(in) a reference to the signal job

Returns

status (0 == ok, -errno == failure)

int32_t qb_loop_signal_mod	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		int32_t	sig,
		void *	data,
		qb_loop_signal_dispatch_fn	dispatch_fn,
		qb_loop_signal_handle	handle
	)

Modify the signal job.

Parameters

l	pointer to the loop instance
p	the priority
sig	(SIGHUP or SIGINT) etc ....
data	user data passed into the dispatch function
dispatch_fn	callback function
handle	(in) a reference to the signal job

Returns

status (0 == ok, -errno == failure)

void qb_loop_stop

(

qb_loop_t *

l

)

Stop the main loop.

Parameters

l	pointer to the loop instance

Examples:

tcpserver.c.

int32_t qb_loop_timer_add	(	qb_loop_t *	l,
		enum qb_loop_priority	p,
		uint64_t	nsec_duration,
		void *	data,
		qb_loop_timer_dispatch_fn	dispatch_fn,
		qb_loop_timer_handle *	timer_handle_out
	)

Add a timer to the mainloop.

Note

it is a one-shot job.

Parameters

l	pointer to the loop instance
p	the priority
nsec_duration	nano-secs in the future to run the dispatch.
data	user data passed into the dispatch function
dispatch_fn	callback function
timer_handle_out	handle to delete the timer if needed.

Returns

status (0 == ok, -errno == failure)

int32_t qb_loop_timer_del	(	qb_loop_t *	l,
		qb_loop_timer_handle	th
	)

Delete a timer that is still outstanding.

Parameters

l	pointer to the loop instance
th	handle to delete the timer if needed.

Returns

status (0 == ok, -errno == failure)

uint64_t qb_loop_timer_expire_time_get	(	struct qb_loop *	l,
		qb_loop_timer_handle	th
	)

Get the expiration time of the timer, as set when the timer was created.

Note

if the timer has already expired it will return 0

Parameters

l	pointer to the loop instance
th	timer handle.

Returns

nano seconds at which the timer will expire

uint64_t qb_loop_timer_expire_time_remaining	(	struct qb_loop *	l,
		qb_loop_timer_handle	th
	)

Get the time remaining before the timer expires.

Note

if the timer has already expired it will return 0

Parameters

l	pointer to the loop instance
th	timer handle.

Returns

nano seconds remaining until the timer expires

int32_t qb_loop_timer_is_running	(	qb_loop_t *	l,
		qb_loop_timer_handle	th
	)

Check to see if a timer that is still outstanding.

Parameters

l	pointer to the loop instance
th	handle to delete the timer if needed.

Return values

QB_TRUE	yes this timer is outstanding
QB_FALSE	this timer does not exist or has expired