libqb  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Typedefs | Enumerations | Functions
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_tqb_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)):

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

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
lpointer to the loop instance
pthe priority
datauser data passed into the dispatch function
dispatch_fncallback 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
lpointer to the loop instance
pthe priority
datauser data passed into the dispatch function
dispatch_fncallback 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
lpointer to the loop instance
pthe priority
fdfile descriptor.
events(POLLIN|POLLOUT) etc ....
datauser data passed into the dispatch function
dispatch_fncallback 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
lpointer to the loop instance
fdfile 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
lpointer to the loop instance
fncallback 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
lpointer to the loop instance
pthe priority
fdfile descriptor.
events(POLLIN|POLLOUT) etc ....
datauser data passed into the dispatch function
dispatch_fncallback function
Returns
status (0 == ok, -errno == failure)
Examples:
ipcserver.c.
void qb_loop_run ( qb_loop_t l)

Run the main loop.

Parameters
lpointer 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
lpointer to the loop instance
pthe priority
sig(SIGHUP or SIGINT) etc ....
datauser data passed into the dispatch function
dispatch_fncallback 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
lpointer 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
lpointer to the loop instance
pthe priority
sig(SIGHUP or SIGINT) etc ....
datauser data passed into the dispatch function
dispatch_fncallback 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
lpointer 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
lpointer to the loop instance
pthe priority
nsec_durationnano-secs in the future to run the dispatch.
datauser data passed into the dispatch function
dispatch_fncallback function
timer_handle_outhandle 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
lpointer to the loop instance
thhandle 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
lpointer to the loop instance
thtimer 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
lpointer to the loop instance
thtimer 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
lpointer to the loop instance
thhandle to delete the timer if needed.
Return values
QB_TRUEyes this timer is outstanding
QB_FALSEthis timer does not exist or has expired