sd_event_wait(3)

.SH "NAME" sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state, sd_event_get_iteration, SD_EVENT_INITIAL, SD_EVENT_PREPARING, SD_EVENT_ARMED, SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING, SD_EVENT_FINISHED - Low-level event loop operations

.SH "SYNOPSIS"

#include <systemd/sd-event.h>

enum {


        SD_EVENT_INITIAL,


        SD_EVENT_PREPARING,


        SD_EVENT_ARMED,


        SD_EVENT_PENDING,


        SD_EVENT_RUNNING,


        SD_EVENT_EXITING,


        SD_EVENT_FINISHED,
};

.HP 504u int sd_event_prepare(sd_event *event);

.HP 432u int sd_event_wait(sd_event *event, uint64_t usec);

.HP 528u int sd_event_dispatch(sd_event *event);

.HP 552u int sd_event_get_state(sd_event *event);

.HP 648u int sd_event_get_iteration(sd_event *event, uint64_t *ret);

.SH "DESCRIPTION"

.PP The low-level sd_event_prepare(), sd_event_wait() and sd_event_dispatch() functions may be used to execute specific phases of an event loop. See sd_event_run(3) and sd_event_loop(3) for higher-level functions that execute individual but complete iterations of an event loop or run it continuously.

.PP sd_event_prepare() checks for pending events and arms necessary timers. If any events are ready to be processed ("pending"), it returns a positive, non-zero value, and the caller should process these events with sd_event_dispatch().

.PP sd_event_dispatch() dispatches the highest priority event source that has a pending event. On success, sd_event_dispatch() returns either zero, which indicates that no further event sources may be dispatched and exiting of the event loop was requested via sd_event_exit(3); or a positive non-zero value, which means that an event source was dispatched and the loop returned to its initial state, and the caller should initiate the next event loop iteration by invoking sd_event_prepare() again.

.PP In case sd_event_prepare() returned zero, sd_event_wait() should be called to wait for further events or a timeout. If any events are ready to be processed, it returns a positive, non-zero value, and the events should be dispatched with sd_event_dispatch(). Otherwise, the event loop returned to its initial state and the next event loop iteration should be initiated by invoking sd_event_prepare() again.

.PP sd_event_get_state() may be used to determine the state the event loop is currently in. It returns one of the states described below.

.PP sd_event_get_iteration() may be used to determine the current iteration of the event loop. It returns an unsigned 64-bit integer containing a counter that increases monotonically with each iteration of the event loop, starting with 0. The counter is increased at the time of the sd_event_prepare() invocation.

.PP All five functions take, as the first argument, the event loop object event that has been created with sd_event_new(). The timeout for sd_event_wait() is specified in usec in microseconds. (uint64_t) -1 may be used to specify an infinite timeout.

.SH "STATE MACHINE"

.PP The event loop knows the following states, that may be queried with sd_event_get_state().

.PP SD_EVENT_INITIAL

          INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\


             |                                                     |


             |                                                     ^


             |                                                     |


             v                 ret == 0                            |


      sd_event_prepare() >--->--->--->--->- ARMED                  |


             |                                |                    ^


             | ret > 0                        |                    |


             |                                |                    |


             v                                v          ret == 0  |


          PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+


             |           ret > 0                                   ^


             |                                                     |


             |                                                     |


             v                                                     |


      sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/


             |                             ret > 0


             | ret == 0


             |


             v


          FINISHED