NAME

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

SYNOPSIS

       #include <signal.h>
       #include <stdint.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
   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 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)

   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.