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_add_time.xml | 167 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 116 insertions(+), 51 deletions(-) (limited to 'man/sd_event_add_time.xml') diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index c5f7aee19d..df38f52fc9 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_add_time @@ -49,13 +49,23 @@ sd_event_source_get_time_accuracy sd_event_source_set_time_accuracy sd_event_source_get_time_clock + sd_event_time_handler_t Add a timer event source to an event loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_time_handler_t) + sd_event_source *s + uint64_t usec + void *userdata + int sd_event_add_time @@ -68,35 +78,28 @@ void *userdata - - typedef int (*sd_event_time_handler_t) - sd_event_source *s - uint64_t usec - void *userdata - - int sd_event_source_get_time sd_event_source *source - usec_t *usec + uint64_t *usec int sd_event_source_set_time sd_event_source *source - usec_t usec + uint64_t usec int sd_event_source_get_time_accuracy sd_event_source *source - usec_t *usec + uint64_t *usec int sd_event_source_set_time_accuracy sd_event_source *source - usec_t usec + uint64_t usec @@ -112,73 +115,130 @@ Description sd_event_add_time() adds a new timer - event source to an event loop object. The event loop is specified - in event, the event source is returned in - the source parameter. The - clock parameter takes a clock identifier, - one of CLOCK_REALTIME, - CLOCK_MONOTONIC and + event source to an event loop. The event loop object is specified + in the event parameter, the event source + object is returned in the source + parameter. The clock parameter takes a + clock identifier, one of CLOCK_REALTIME, + CLOCK_MONOTONIC, + CLOCK_BOOTTIME, + CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM. See timerfd_create2 for details regarding the various types of clocks. The usec parameter takes a time value in - microseconds, relative to the clock's epoch specifying when the - timer shall elapse the earliest. The + microseconds (µs), relative to the clock's epoch, specifying when + the timer shall elapse the earliest. If a time that already lies + in the past is specified (including 0), the timer source is + dispatched immediately in the next event loop iterations. The accuracy parameter takes an additional - accuracy value in microseconds specifying a time the timer event - may be delayed. Specify 0 for selecting the default accuracy - (250ms). Specify 1 for most accurate timers. Consider specifying - 60000000 or larger (1h) for long-running events that may be + accuracy value in µs specifying a time the timer event may be + delayed. Specify 0 for selecting the default accuracy + (250ms). Specify 1µs for most accurate timers. Consider specifying + 60000000µs or larger (1min) for long-running events that may be delayed substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, thus improving - power efficiency. The handler shall - reference a function to call when the timer elapses. The handler - function will be passed the userdata - pointer, which may be chosen freely by the caller. The handler is - also passed the configured time it was triggered, however it might - actually have been called at a slightly later time, subject to the - specified accuracy value, the kernel timer slack (see + power efficiency. The handler parameter + shall reference a function to call when the timer elapses. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler is also passed the configured + time it was triggered, however it might actually have been called + at a slightly later time, subject to the specified accuracy value, + the kernel timer slack (see prctl2) - and additional scheduling latencies. + and additional scheduling latencies. To query the actual time the + handler was called use + sd_event_now3. By default, the timer will elapse once (SD_EVENT_ONESHOT), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continously unless its configured time is updated using + sd_event_source_set_time(). + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the the second parameter of + sd_event_add_time() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + If the handler to + sd_event_add_time() is passed as NULL, and + the event source fires, this will be considered a request to exit + the event loop. In this case, the userdata + parameter, cast to an integer is used for the exit code passed to + sd_event_exit3. + + Use CLOCK_BOOTTIME_ALARM and + CLOCK_REALTIME_ALARM to define event sources + that may wake up the system from suspend. + + In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + sd_event_now3, + add the desired timespan to sleep to it, and pass the result as + the usec parameter to + sd_event_add_time(). + + In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + sd_event_source_set_time3 for the next timer + iteration, and reenable the timer using + sd_event_source_set_enabled(). To calculate + the next point in time to pass to + sd_event_source_set_time(), either use as + base the usec parameter passed to the timer + callback, or the timestamp returned by + sd_event_now(). In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer. + sd_event_source_get_time() retrieves the configured time value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store the - time in microseconds in. + time, relative to the selected clock's epoch, in µs in. sd_event_source_set_time() changes the configured time value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a time relative to the selected clock's - epoch, in microseconds. + epoch, in µs. sd_event_source_get_time_accuracy() retrieves the configured accuracy value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store - the accuracy in microseconds in. + the accuracy in µs in. sd_event_source_set_time_accuracy() changes the configured accuracy of a timer event source created previously with sd_event_add_time(). It takes - the event source object and an accuracy, in microseconds. + the event source object and an accuracy, in µs. sd_event_source_get_time_clock() retrieves the configured clock of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store the clock identifier in. - @@ -228,19 +288,17 @@ The selected clock is not supported by the event loop implementation. - - - - Notes + + -EDOM - sd_event_add_time() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. + The passed event source is not a timer event source. + + + + See Also @@ -248,11 +306,18 @@ systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_signal3, sd_event_add_child3, sd_event_add_defer3, - clock_gettime2, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + clock_gettime2, + timerfd_create2, + prctl2 -- cgit v1.2.3-54-g00ecf