From f23e83b156da8966e43e303dced5439503450d21 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Mon, 4 Jan 2016 23:17:21 -0500 Subject: man/sd_event_{add_io,add_time,add_signal,now}: various small fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - remove things which are clear from the context - 0 is a valid descriptor number, hence "positive" → "non-negative" - "positive" means greater than zero, hence "positive non-zero" → "positive" - use oxford comma - reword some things for clarity --- man/sd_event_add_time.xml | 80 ++++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 39 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 b58d740bd8..142fa80f8f 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -122,31 +122,31 @@ clock identifier, one of CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, - CLOCK_REALTIME_ALARM or + 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 (µ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 µ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 + 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. 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, thus improving + 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 - time it was triggered, however it might actually have been called - at a slightly later time, subject to the specified accuracy value, + trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see - prctl2) + prctl2), and additional scheduling latencies. To query the actual time the handler was called use sd_event_now3. @@ -167,22 +167,24 @@ 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. + 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 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. + 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 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_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 @@ -192,7 +194,7 @@ 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 + add the desired timespan to it, and use the result as the usec parameter to sd_event_add_time(). @@ -212,30 +214,30 @@ 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, relative to the selected clock's epoch, in µs 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 µs. + 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 a 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 µs 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 µs. + 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 a 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. @@ -252,7 +254,7 @@ Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: -- cgit v1.2.3-54-g00ecf