From dc83f27a7cf03757dec11a69ec18504ad4ea8f89 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 19 Nov 2015 23:38:54 +0100 Subject: man: fully document sd-event interfaces This completes the set of man pages for sd-event and contains some minor other fixes for other man pages too. The sd_event_set_name(3) man page is renamed to sd_event_source_set_description(3), which is the correct name of the concept today. --- man/sd_event_wait.xml | 275 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 204 insertions(+), 71 deletions(-) (limited to 'man/sd_event_wait.xml') diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 7ca50aedf9..1eefa80700 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_wait @@ -46,14 +46,32 @@ sd_event_wait sd_event_prepare sd_event_dispatch - - Run parts of the libsystemd event loop + sd_event_get_state + 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 #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 @@ -62,7 +80,7 @@ int sd_event_wait sd_event *event - uint64_t timeout + uint64_t usec @@ -70,66 +88,184 @@ sd_event *event + + int sd_event_get_state + sd_event *event + + Description - Functions described here form parts of an event loop. - - sd_event_prepare checks for pending + 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_run3 + and + sd_event_loop3 + for higher-level functions that execute individual but complete + iterations of an event loop or run it continously. + + sd_event_prepare() checks for pending events and arms necessary timers. If any events are ready to be - processed, it returns a positive value, and the events should be - processed with sd_event_dispatch. - sd_event_dispatch runs a handler for one of - the events from the sources with the highest priority. On success, - sd_event_dispatch returns either 0, which - means that the loop is finished, or a positive value, which means - that the loop is again in the initial state and - sd_event_prepare should be called again. - + 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_exit3; + 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. + + All four 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 milliseconds. (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(). - In case sd_event_prepare returned 0, - sd_event_wait should be called to wait for - events or a timeout. If any events are ready to be processed, it - returns a positive value, and the events should be processed with - sd_event_dispatch. Otherwise, the loop is - back in the initial state and sd_event_prepare - should be called again. + + + 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. + + + + SD_EVENT_PREPARING + + An event source is currently being prepared, + i.e. the preparation handler is currently being excuted, as + set with + sd_event_set_prepare3. 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + + 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 ├──←←←←←←←←←←←←←←←←←←←─┐ - └───┬──────┘ ↑ - │ ↑ - sd_event_prepare ┌─────────┐ ↑ - ├ 0 →→→→→→→──┤ armed │ ↑ - 1 └───┬─────┘ ↑ - ↓ │ ↑ - ↓ sd_event_wait ↑ - ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘ - ┌───┴──────┐ ↑ - │ pending │ ↑ - └───┬──────┘ ↑ - │ ↑ - sd_event_dispatch ↑ - ↓ ↑ - ├ 1 ──────────→→→→→→→─────────┘ - 0 - ↓ - ┌───┴──────┐ - │ finished │ - └──────────┘ + 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 - - All three functions take, as the first argument, the event - loop object event that is created with - sd_event_new. The timeout for - sd_event_wait is specified with - timeout in milliseconds. - (uint64_t) -1 may be used to specify an - infinite timeout. @@ -137,13 +273,15 @@ 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 value means that - events are ready to be processed and 0 means that no events are - ready. In case of sd_event_dispatch, a - positive value means that the loop is again in the initial state - and 0 means the loop is finished. For any of these functions, a - negative return value means the loop must be aborted. + 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. @@ -156,7 +294,7 @@ -EINVAL The event parameter is - NULL. + invalid or NULL. @@ -185,14 +323,7 @@ Other errors are possible, too. - - Notes - - Functions described here are available - as a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -200,13 +331,15 @@ systemd1, sd_event_new3, - sd_event_run3, sd_event_add_io3, sd_event_add_time3, sd_event_add_signal3, sd_event_add_defer3, sd_event_add_exit3, - sd_event_add_post3. + sd_event_add_post3, + sd_event_run3, + sd_event_get_fd3, + sd_event_source_set_prepare3 -- cgit v1.2.1