X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_event_add_time.xml;h=d5e2e91375df8152b0cbb36fdced815fc2a3e029;hb=91d60274701a12d2bbcd2b8e40f8b8abe00be0e7;hp=c975f07de5e53a0a3770fd44ea9f33e05896731f;hpb=b975b0d514321f169b3c4599a8ea92e13741b4e4;p=elogind.git
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index c975f07de..d5e2e9137 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
@@ -111,74 +114,120 @@
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.
+ 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
- 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 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.
-
@@ -192,7 +241,7 @@
Errors
- Returned errors may indicate the following problems:
+ Returned values may indicate the following problems:
@@ -223,24 +272,22 @@
- -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
@@ -248,11 +295,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