X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_event_add_time.xml;h=d5e2e91375df8152b0cbb36fdced815fc2a3e029;hp=a3304f7985b995408a749beb15fcafc332974e52;hb=734744fddd783fec7b19215b24c12e95c00c1e67;hpb=5aded369782f28255bc6b494ca905d7acaea7a56 diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index a3304f798..d5e2e9137 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -1,27 +1,27 @@ - + - + sd_event_add_time @@ -49,13 +49,23 @@ along with systemd; If not, see . 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 @@ -71,25 +81,25 @@ along with systemd; If not, see . 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 @@ -104,70 +114,120 @@ along with systemd; If not, see . 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 - 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 - 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 - 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 - prctl2) - and additional scheduling latencies. 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. + sd_event_add_time() adds a new timer 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 specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including 0), this timer source "fires" immediately and is ready to be + dispatched. If the parameter is specified as UINT64_MAX the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + sd_event_source_set_enabled3. The + accuracy parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use 0 to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving 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 trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + prctl2), 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 the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continuously 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 if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_time() is + 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 + 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 it, and use 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 + the configured time value of an 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 in, relative to the selected clock's epoch, in µs. 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. + time of an 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 µs. sd_event_source_get_time_accuracy() - retrieves the configured accuracy value of a timer event source + retrieves the configured accuracy value of an 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. The accuracy is specified in µs. 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 accuracy, in µs. sd_event_source_get_time_clock() - retrieves the configured clock of a timer event source created + retrieves the configured clock of an 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. - @@ -181,55 +241,53 @@ along with systemd; If not, see . Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: - -ENOMEM + -ENOMEM - Not enough memory to allocate object. + Not enough memory to allocate an object. - -EINVAL + -EINVAL An invalid argument has been passed. - -ESTALE + -ESTALE The event loop is already terminated. - -ECHILD + -ECHILD The event loop has been created in a different process. - -ENOTSUP + -EOPNOTSUPP 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 @@ -237,8 +295,18 @@ along with systemd; If not, see . systemd1, sd-event3, sd_event_new3, - clock_gettime2, - sd_event_source_set_enabled3 + sd_event_now3, + sd_event_add_io3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + 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