Scroll to navigation

qbloop.h(3) libqb qbloop.h(3)

NAME

qbloop.h

SYNOPSIS

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

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.

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.

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)

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.

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)

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)

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)

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)

void qb_loop_run (qb_loop_t * l)

Run the main loop.

Parameters

l pointer to the loop instance

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)

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

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

Author

Generated automatically by Doxygen for libqb from the source code.
Thu Jul 30 2020 Version 1.0.6