qbloop.h File Reference

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

#include <signal.h>
#include <stdint.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.
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.
void	qb_loop_destroy (struct qb_loop *l)
void	qb_loop_stop (qb_loop_t *l)
	Stop the main loop.
void	qb_loop_run (qb_loop_t *l)
	Run the main loop.
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.
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.
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.
int32_t	qb_loop_timer_del (qb_loop_t *l, qb_loop_timer_handle th)
	Delete a timer that is still outstanding.
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.
uint64_t	qb_loop_timer_expire_time_get (struct qb_loop *l, qb_loop_timer_handle th)
	Get the time remaining before it expires.
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.
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.
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.
int32_t	qb_loop_poll_del (qb_loop_t *l, int32_t fd)
	Delete a poll job.
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.
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.
int32_t	qb_loop_signal_del (qb_loop_t *l, qb_loop_signal_handle handle)
	Delete the signal job.

---

Detailed Description

Main loop manages timers, jobs and polling sockets.

---

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.

Examples:

ipcserver.c, and tcpserver.c.

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 paramaters (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-occuring 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 time remaining before it 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 left

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