# sd_event_wait

## 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
    


## 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** ,
           };
    
           **int sd_event_prepare(sd_event ***_event_**);**
    
           **int sd_event_wait(sd_event ***_event_**, uint64_t** _usec_**);**
    
           **int sd_event_dispatch(sd_event ***_event_**);**
    
           **int sd_event_get_state(sd_event ***_event_**);**
    
           **int sd_event_get_iteration(sd_event ***_event_**, uint64_t ***_ret_**);**
    


## DESCRIPTION



           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.
    
           **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()**.
    
           **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.
    
           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.
    
           **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.
    
           **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.
    
           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.
    


## STATE MACHINE



           The event loop knows the following states, that may be queried
           with **sd_event_get_state()**.
    
           **SD_EVENT_INITIAL**
               The initial state the event loop is in, before each event loop
               iteration. Use **sd_event_prepare()** to transition the event loop
               into the **SD_EVENT_ARMED** or **SD_EVENT_PENDING** states.
    
               Added in version 229.
    
           **SD_EVENT_PREPARING**
               An event source is currently being prepared, i.e. the
               preparation handler is currently being executed, as set with
               sd_event_source_set_prepare(3). This state is only seen in the
               event source preparation handler that is invoked from the
               **sd_event_prepare()** call and is immediately followed by
               **SD_EVENT_ARMED** or **SD_EVENT_PENDING**.
    
               Added in version 229.
    
           **SD_EVENT_ARMED**
               **sd_event_prepare()** has been called and no event sources were
               ready to be dispatched. Use **sd_event_wait()** to wait for new
               events, and transition into **SD_EVENT_PENDING** or back into
               **SD_EVENT_INITIAL**.
    
               Added in version 229.
    
           **SD_EVENT_PENDING**
               **sd_event_prepare()** or **sd_event_wait()** have been called and
               there were event sources with events pending. Use
               **sd_event_dispatch()** to dispatch the highest priority event
               source and transition back to **SD_EVENT_INITIAL** , or
               **SD_EVENT_FINISHED**.
    
               Added in version 229.
    
           **SD_EVENT_RUNNING**
               A regular event source is currently being dispatched. This
               state is only seen in the event source handler that is invoked
               from the **sd_event_dispatch()** call, and is immediately followed
               by **SD_EVENT_INITIAL** or **SD_EVENT_FINISHED** as soon the event
               source handler returns. Note that during dispatching of exit
               event sources the **SD_EVENT_EXITING** state is seen instead.
    
               Added in version 229.
    
           **SD_EVENT_EXITING**
               Similar to **SD_EVENT_RUNNING** but is the state in effect while
               dispatching exit event sources. It is followed by
               **SD_EVENT_INITIAL** or **SD_EVENT_FINISHED** as soon as the event
               handler returns.
    
               Added in version 229.
    
           **SD_EVENT_FINISHED**
               The event loop has exited. All exit event sources have run. If
               the event loop is in this state it serves no purpose anymore,
               and should be freed.
    
               Added in version 229.
    
           A simplified flow chart of the states and the calls to transition
           between them is shown below. Note that **SD_EVENT_PREPARING** ,
           **SD_EVENT_RUNNING** and **SD_EVENT_EXITING** are not shown here.
    
                         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
    


## RETURN VALUE



           On success, these functions return 0 or a positive integer. On
           failure, they return a negative errno-style error code. In case of
           **sd_event_prepare()** and **sd_event_wait()** , a positive, non-zero
           return code indicates that events are ready to be processed and
           zero indicates that no events are ready. In case of
           **sd_event_dispatch()** , a positive, non-zero return code indicates
           that the event loop returned to its initial state and zero
           indicates the event loop has exited.  **sd_event_get_state()** returns
           a positive or zero state on success.
    
       **Errors**
           Returned errors may indicate the following problems:
    
           **-EINVAL**
               The _event_ parameter is invalid or **NULL**.
    
           **-EBUSY**
               The event loop object is not in the right state.
    
           **-ESTALE**
               The event loop is already terminated.
    
           **-ECHILD**
               The event loop has been created in a different process,
               library or module instance.
    
           Other errors are possible, too.
    


## NOTES



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           The code described here uses getenv(3), which is declared to be
           not multi-thread-safe. This means that the code calling the
           functions described here must not call setenv(3) from a parallel
           thread. It is recommended to only do calls to **setenv()** from an
           early phase of the program when no other threads have been
           started.
    


* * *