qbloop.h(3)

NAME
qbloop.h - Main loop manages timers, jobs and polling sockets.

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.

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.