From c11dd1c49b997de4d222f302070387f82d8068ca Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 19 Nov 2015 23:38:54 +0100 Subject: [PATCH] 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.xml | 187 +++++++++++++++ man/sd_event_add_io.xml | 300 ++++++++++++++++++++++++ man/sd_event_exit.xml | 163 +++++++++++++ man/sd_event_now.xml | 141 +++++++++++ man/sd_event_set_watchdog.xml | 177 ++++++++++++++ man/sd_event_source_get_event.xml | 100 ++++++++ man/sd_event_source_get_pending.xml | 167 +++++++++++++ man/sd_event_source_set_description.xml | 170 ++++++++++++++ man/sd_event_source_set_enabled.xml | 179 ++++++++++++++ man/sd_event_source_set_prepare.xml | 171 ++++++++++++++ man/sd_event_source_set_priority.xml | 189 +++++++++++++++ man/sd_event_source_set_userdata.xml | 119 ++++++++++ man/sd_event_source_unref.xml | 125 ++++++++++ 13 files changed, 2188 insertions(+) create mode 100644 man/sd-event.xml create mode 100644 man/sd_event_add_io.xml create mode 100644 man/sd_event_exit.xml create mode 100644 man/sd_event_now.xml create mode 100644 man/sd_event_set_watchdog.xml create mode 100644 man/sd_event_source_get_event.xml create mode 100644 man/sd_event_source_get_pending.xml create mode 100644 man/sd_event_source_set_description.xml create mode 100644 man/sd_event_source_set_enabled.xml create mode 100644 man/sd_event_source_set_prepare.xml create mode 100644 man/sd_event_source_set_priority.xml create mode 100644 man/sd_event_source_set_userdata.xml create mode 100644 man/sd_event_source_unref.xml diff --git a/man/sd-event.xml b/man/sd-event.xml new file mode 100644 index 000000000..c7d937705 --- /dev/null +++ b/man/sd-event.xml @@ -0,0 +1,187 @@ + + + + + + + + + sd-event + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-event + 3 + + + + sd-event + A generic event loop implementation + + + + + #include <elogind/sd-event.h> + + + + pkg-config --cflags --libs libelogind + + + + + + Description + + sd-event.h provides a generic event + loop implementation, based on Linux epoll7. + + + See + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3 + for more information about the functions available. + + The event loop design is targeted on running a separate + instance of the event loop in each thread; it has no concept of + distributing events from a single event loop instance onto + multiple worker threads. Dispatching events is strictly ordered + and subject to configurable priorities. In each event loop + iteration a single event source is dispatched. Each time an event + source is dispatched the kernel is polled for new events, before + the next event source is dispatched. The event loop is designed to + honour priorities and provide fairness within each priority. It is + not designed to provide optimal throughput, as this contradicts + these goals due the limitations of the underlying epoll7 + primitives. + + The event loop implementation provides the following features: + + + I/O event sources, based on epoll7's + file descriptor watching, including edge triggered events (EPOLLET). See sd_event_add_io3. + + Timer event sources, based on timerfd_create2, + supporting the CLOCK_MONOTONIC, + CLOCK_REALTIME, + CLOCK_BOOTIME clocks, as well as the + CLOCK_REALTIME_ALARM and + CLOCK_BOOTTIME_ALARM clocks that can resume + the system from suspend. When creating timer events a required + accuracy parameter may be specified which allows coalescing of + timer events to minimize power consumption. See sd_event_add_time3. + + UNIX process signal events, based on + signalfd2, + including full support for real-time signals, and queued parameters. See sd_event_add_signal3. + + Child process state change events, based on + waitid2. See sd_event_add_child3. + + Static event sources, of three types: defer, + post and exit, for invoking calls in each event loop, after + other event sources or at event loop termination. See + sd_event_add_defer3. + + Event sources may be assigned a 64bit priority + value, that controls the order in which event sources are + dispatched if multiple are pending simultanously. See + sd_event_source_set_priority3. + + The event loop may automatically send watchdog + notification messages to the service manager. See + sd_event_set_watchdog3. + + The event loop may be integrated into foreign + event loops, such as the GLib one. See + sd_event_get_fd3 + for an example. + + + + + + + + See Also + + elogind1, + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3, + epoll7, + timerfd_create2, + signalfd2, + waitid2 + + + + diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml new file mode 100644 index 000000000..4e01d2754 --- /dev/null +++ b/man/sd_event_add_io.xml @@ -0,0 +1,300 @@ + + + + + + + + + sd_event_add_io + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_io + 3 + + + + sd_event_add_io + sd_event_source_get_io_events + sd_event_source_set_io_events + sd_event_source_get_io_revents + sd_event_source_get_io_fd + sd_event_source_set_io_fd + sd_event_source + sd_event_io_handler_t + + Add an I/O event source to an event loop + + + + + #include <elogind/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_io_handler_t) + sd_event_source *s + int fd + uint32_t revents + void *userdata + + + + int sd_event_add_io + sd_event *event + sd_event_source **source + int fd + uint32_t events + sd_event_io_handler_t handler + void *userdata + + + + int sd_event_source_get_io_events + sd_event_source *source + uint32_t *events + + + + int sd_event_source_set_io_events + sd_event_source *source + uint32_t events + + + + int sd_event_source_get_io_revents + sd_event_source *source + uint32_t *revents + + + + int sd_event_source_get_io_fd + sd_event_source *source + + + + int sd_event_source_set_io_fd + sd_event_source *source + int fd + + + + + + + Description + + sd_event_add_io() adds a new I/O 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 + fd parameter takes the UNIX file descriptor + to watch, which may refer to a socket, a FIFO, a message queue, a + serial connection, a character device or any other file descriptor + compatible with Linux epoll7. The + events parameter takes a bit mask of I/O + events to watch the file descriptor for, a combination of the + following event flags: EPOLLIN, + EPOLLOUT, EPOLLRDHUP, + EPOLLPRI and EPOLLET, + see epoll_ctl2 + for details. The handler shall reference a + function to call when the I/O event source is triggered. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler will also be passed the file + descriptor the event was seen on as well as the actual event flags + seen. It's generally a subset of the events watched, however may + additionally have EPOLLERR and + EPOLLHUP set. + + By default, the I/O event source will stay enabled + continously (SD_EVENT_ON), 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 an I/O event source set to SD_EVENT_ON will + fire continously unless data is read or written to the file + descriptor in order to reset the mask of events seen. + + + Setting the I/O event mask to watch for to 0 does not mean + that the event source won't be triggered anymore, as + EPOLLHUP and EPOLLERR + may be triggered even with a zero event mask. To temporarily + disable an I/O event source use + sd_event_source_set_enabled3 + with SD_EVENT_OFF instead. + + 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_io() 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. + + It is recommended to use + sd_event_add_io() only in conjunction with + file descriptors that have O_NONBLOCK set, to + ensure that all I/O operations from invoked handlers are properly + asynchronous and non-blocking. Using file descriptors without + O_NONBLOCK might result in unexpected + starving of other event sources. See fcntl2 + for details on enabling O_NONBLOCK mode. + + sd_event_source_get_io_events() retrieves + the configured I/O event mask to watch of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and a pointer to a variable to store the + event mask in. + + sd_event_source_set_io_events() changes the + configured I/O event mask to watch of an I/O event source created previously + with sd_event_add_io(). It takes the event + source object and the new event mask to set. + + sd_event_source_get_io_events() + retrieves the I/O event mask of currently seen but undispatched + events from an I/O event source created previously with + sd_event_add_io(). It takes the event source + object and a pointer to a variable to store the event mask + in. When called from a handler function on the handler's event + source object this will return the same mask as passed to the + handler's revents parameter. This call is + primarily useful to check for undispatched events of an event + source from the handler of an unrelated (possibly higher priority) + event source. Note the relation between + sd_event_source_get_pending() and + sd_event_source_get_io_revents(): both + functions will report non-zero results when there's an event + pending for the event source, but the former applies to all event + source types, the latter only to I/O event sources. + + sd_event_source_get_io_fd() retrieves + the UNIX file descriptor of an I/O event source created previously + with sd_event_add_io(). It takes the event + source object and returns the positive file descriptor in the return + value, or a negative error number on error (see below). + + sd_event_source_set_io_fd() + changes the UNIX file descriptor of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and the new file descriptor to set. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not an I/O event source. + + + + + + + + See Also + + + elogind1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_time3, + 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, + sd_event_source_get_pending3, + epoll_ctl3, + epoll7 + + + + diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml new file mode 100644 index 000000000..20ef7b10f --- /dev/null +++ b/man/sd_event_exit.xml @@ -0,0 +1,163 @@ + + + + + + + + + sd_event_exit + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_exit + 3 + + + + sd_event_exit + sd_event_get_exit_code + + Ask the event loop to exit + + + + + #include <elogind/sd-event.h> + + + int sd_event_exit + sd_event *event + int code + + + + int sd_event_get_exit_code + sd_event *event + int *code + + + + + + + Description + + sd_event_exit() requests the event loop + specified in the event event loop object to + exit. The code parameter may be any integer + value and is returned as-is by + sd_event_loop3 + after the last event loop iteration. It may also be be queried + using sd_event_get_exit_code(), see + below. + + When exiting is requested the event loop will stop listening + for and dispatching regular event sources. Instead it will proceed + with executing only event sources registered with + sd_event_add_exit3 + in the order defined by their priority. After all exit event + sources have been dispatched the event loop is terminated. + + If sd_event_exit() is invoked a second + time while the event loop is still processing exit event sources, + the exit code stored in the event loop object is updated, but + otherwise no further operation is executed. + + sd_event_get_exit_code() may be used to + query the exit code passed into + sd_event_exit() earlier. + + While the full positive and negative integer ranges may be used + for the exit code, care should be taken not pick exit codes that + conflict with regular exit codes returned by + sd_event_loop(), if these exit codes shall be + distinguishable. + + + + Return Value + + On success, sd_event_exit() and + sd_event_get_exit_code() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The event loop object or error code pointer are invalid. + + + + + -ECHILD + + The event loop was created in a different process. + + + + -ESTALE + + The event loop has exited already and all exit handlers are already processed. + + + + -ENODATA + + The event loop has not been requested to exit yet. + + + + + + + + + See Also + + + elogind1, + sd-event3, + sd_event_new3, + sd_event_add_exit3 + + + + diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml new file mode 100644 index 000000000..b4105236d --- /dev/null +++ b/man/sd_event_now.xml @@ -0,0 +1,141 @@ + + + + + + + + + sd_event_now + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_now + 3 + + + + sd_event_now + + Retrieve current event loop iteration timestamp + + + + + #include <elogind/sd-event.h> + + + int sd_event_now + sd_event *event + clockid_t clock + uint64_t *usec + + + + + + + Description + + sd_event_now() returns the timestamp + the most recent event loop iteration began. This timestamp is + taken right after after returning from the event sleep, and before + dispatching any event sources. The event + parameter takes the even loop object to retrieve the timestamp + from. The clock parameter specifies the clock to + retrieve the timestamp for, and is one of + CLOCK_REALTIME (or its equivalent + CLOCK_REALTIME_ALARM), + CLOCK_MONOTONIC or + CLOCK_BOOTTIME (or its equivalent + CLOCK_BOOTTIME_ALARM), see clock_gettime2 + for more information on the various clocks. The retrieved + timestamp is stored in the usec parameter, + in µs since the clock's epoch. If this function is invoked before + the first event loop iteration the current time is returned, as + reported by clock_gettime(). To distinguish + this case from a regular invocation the return value will be + positive non-zero in this case, while it is zero when the returned + timestamp refers to the actual event loop iteration. + + + + Return Value + + If the first event loop iteration has not run yet + sd_event_now() returns the requested + timestamp in usec and returns a positive, + non-zero return value. Otherwise, on success it will return the + iteration's timestamp in usec and 0 as + return value. On failure, the call returns a negative errno-style + error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An invalid parameter was + passed. + + + + + -ECHILD + + The event loop object was created in a + different process. + + + + + + + + + See Also + + + elogind1, + sd-event3, + sd_event_new3, + sd_event_add_time3, + clock_gettime2 + + + + diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml new file mode 100644 index 000000000..58a052d59 --- /dev/null +++ b/man/sd_event_set_watchdog.xml @@ -0,0 +1,177 @@ + + + + + + + + + sd_event_set_watchdog + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_set_watchdog + 3 + + + + sd_event_set_watchdog + sd_event_get_watchdog + + Enable event loop watchdog support + + + + + #include <elogind/sd-event.h> + + + int sd_event_set_watchdog + sd_event *event + int b + + + + int sd_event_get_watchdog + sd_event *event + + + + + + + Description + + sd_event_set_watchdog() may be used to + enable or disable automatic watchdog notification support in the + event loop object specified in the event + parameter. Specifically, depending on the b + boolean argument this will make sure the event loop wakes up in + regular intervals and sends watchdog notification messages to the + service manager, if this was requested by the service + manager. Watchdog support is determined with + sd_watchdog_enabled3, + and watchdog messages are sent with + sd_notify3. See + the WatchdogSec= setting in + elogind.service5 + for details on how to enable watchdog support for a service and + the protocol used. The wake-up interval is chosen as half the + watchdog timeout declared by the service manager via the + $WATCHDOG_USEC environment variable. If the + service manager did not request watchdog notifications, or if the + process was not invoked by the service manager this call with a + true b parameter executes no + operation. Passing a false b parameter will + disable the automatic sending of watchdog notification messages if + it was enabled before. Newly allocated event loop objects have + this feature disabled. + + The first watchdog notification message is sent immediately + when set_event_set_watchdog() is invoked with + a true b parameter. + + The watchdog logic is designed to allow the service manager + to automatically detect services that ceased processing of + incoming events, and thus appear "hung". Watchdog notifications + are sent out only at the beginning of each event loop + iteration. If an event source dispatch function blocks for an + excessively long time and does not return execution to the event + loop quickly, this might hence cause the notification message to + be delayed, and possibly result in abnormal program termination, + as configured in the service unit file. + + sd_event_get_watchdog() may be used to + determine whether watchdog support was previously requested by a + call to sd_event_set_watchdog() with a true + b parameter and successfully + enabled. + + + + Return Value + + On success, sd_event_set_watchdog() and + sd_event_get_watchdog() return a non-zero + positive integer if the service manager requested watchdog support + and watchdog support was successfully enabled. They return zero if + the service manager did not request watchdog support, or if + watchdog support was explicitly disabled with a false + b parameter. On failure, they return a + negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EINVAL + + The passed event loop object was invalid. + + + + + + + + + See Also + + + elogind1, + sd-event3, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3, + sd_event_add_exit3, + sd_watchdog_enabled3, + sd_notify3, + elogind.service5 + + + + diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml new file mode 100644 index 000000000..c9a52af68 --- /dev/null +++ b/man/sd_event_source_get_event.xml @@ -0,0 +1,100 @@ + + + + + + + + + sd_event_source_get_event + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_event + 3 + + + + sd_event_source_get_event + + Retrieve the event loop of an event source + + + + + #include <elogind/sd-event.h> + + + sd_event* sd_event_source_get_event + sd_event_source *source + + + + + + + Description + + sd_event_source_get_event() may be used + to retrieve the event loop object the event source object specified + as source is associated with. The event + loop object is specified when creating an event source object with + calls such as + sd_event_add_io3 + or + sd_event_add_time3. + + + + Return Value + + On success, sd_event_source_get_event() + returns the associated event loop object. On failure, it returns + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml new file mode 100644 index 000000000..1339d5046 --- /dev/null +++ b/man/sd_event_source_get_pending.xml @@ -0,0 +1,167 @@ + + + + + + + + + sd_event_source_get_pending + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_pending + 3 + + + + sd_event_source_get_pending + + Determine pending state of event sources + + + + + #include <elogind/sd-event.h> + + + int sd_event_source_get_pending + sd_event_source *source + + + + + + + Description + + sd_event_source_get_pending() may be + used to determine whether the event source object specified as + source has seen events but has not been + dispatched yet (and thus is marked "pending"). + + Event source objects initially are not marked pending, when + they are created with calls such as + sd_event_add_io3, + sd_event_add_time3, + with the exception of those created with + sd_event_add_defer3 + which are immediately marked pending, and + sd_event_add_exit3 + for which the "pending" concept is not defined. For details see + the respective manual pages. + + In each event loop iteration one event source of those + marked pending is dispatched, in the order defined by the event + source priority, as set with + sd_event_source_set_priority3. + + For I/O event sources, as created with + sd_event_add_io3, + the call + sd_event_get_io_revents3 + may be used to query the type of event pending in more + detail. + + + + + Return Value + + On success, + sd_event_source_get_pending() returns an + integer greater than zero when the event source is marked pending, + and zero when the event source is not marked pending. On failure, + it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -EDOM + + source refers to an + event source object created with + sd_event_add_exit3. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml new file mode 100644 index 000000000..9e8a1d6d9 --- /dev/null +++ b/man/sd_event_source_set_description.xml @@ -0,0 +1,170 @@ + + + + + + + + + sd_event_source_set_description + elogind + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_source_set_description + 3 + + + + sd_event_source_set_description + sd_event_source_get_description + + Set or retrieve descriptive names of event sources + + + + + #include <elogind/sd-event.h> + + + int sd_event_source_set_description + sd_event_source *source + const char *description + + + + int sd_event_source_get_description + sd_event_source *source + const char **description + + + + + + + Description + + sd_event_source_set_description() may + be used to set an arbitrary descriptive name for the event source + object specified as source. This name will + be used in debugging messages generated by + sd-event3 + for this event source, and may be queried using + sd_event_source_get_description() for + debugging purposes. The description parameter shall + point to a NUL-terminated string or be + NULL. In the latter case, the descriptive + name will be unset. The string is copied internally, hence the + description argument is not referenced + after the function returns. + + sd_event_source_get_description() may + be used to query the current descriptive name assigned to the + event source object source. It returns a + pointer to the current name in description, + stored in memory internal to the event source. The memory is + invalidated when the event source is destroyed or the descriptive + name is changed. + + Event source objects generally have no description set when + they are created, except for UNIX signal event sources created + with + sd_event_add_signal3, + whose descriptive name is initialized to the signal's C constant + name (e.g. SIGINT or + SIGTERM). + + + + Return Value + + On success, sd_event_source_set_description() and + sd_event_source_get_description() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object or the description argument for + sd_event_source_get_description() is + NULL. + + + + -ENOMEM + + Not enough memory to copy the + name. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -ENXIO + + No name was set for the event + source. + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml new file mode 100644 index 000000000..1dad6f01d --- /dev/null +++ b/man/sd_event_source_set_enabled.xml @@ -0,0 +1,179 @@ + + + + + + + + + sd_event_source_set_enabled + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_enabled + 3 + + + + sd_event_source_set_enabled + sd_event_source_get_enabled + SD_EVENT_ON + SD_EVENT_OFF + SD_EVENT_ONESHOT + + Enable or disable event sources + + + + + #include <elogind/sd-event.h> + + enum { + SD_EVENT_OFF = 0, + SD_EVENT_ON = 1, + SD_EVENT_ONESHOT = -1, +}; + + + int sd_event_source_set_enabled + sd_event_source *source + int enabled + + + + int sd_event_source_get_enabled + sd_event_source *source + int *enabled + + + + + + + Description + + sd_event_source_set_enabled() may be + used to enable or disable the event source object specified as + source. The enabled + parameter takes one of SD_EVENT_ON (to + enable), SD_EVENT_OFF (to disable) or + SD_EVENT_ONESHOT. If invoked with + SD_EVENT_ONESHOT the event source will be + enabled but automatically reset to + SD_EVENT_OFF after the event source was + dispatched once. + + Event sources that are disabled will not result in event + loop wakeups and will not be dispatched, until they are enabled + again. + + sd_event_source_get_enabled() may be + used to query whether the event source object + source is currently enabled or not. It + returns the enablement state in + enabled. + + Event source objects are enabled when they are first created + with calls such as + sd_event_add_io3, + sd_event_add_time3. However, + depending on the event source type they are enabled continously + (SD_EVENT_ON) or only for a single invocation + of the event source handler + (SD_EVENT_ONESHOT). For details see the + respective manual pages. + + As event source objects stay active and may be dispatched as + long as there is at least one reference to them, in many cases it + is a good idea to combine a call to + sd_event_source_unref3 + with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF, to ensure the event source is + not dispatched again until all other remaining references are dropped. + + + + Return Value + + On success, sd_event_source_set_enabled() and + sd_event_source_get_enabled() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ENOMEM + + Not enough memory. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml new file mode 100644 index 000000000..e1763e6d3 --- /dev/null +++ b/man/sd_event_source_set_prepare.xml @@ -0,0 +1,171 @@ + + + + + + + + + sd_event_source_set_prepare + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_prepare + 3 + + + + sd_event_source_set_prepare + + Set a preparation callback for event sources + + + + + #include <elogind/sd-event.h> + + + int sd_event_source_set_prepare + sd_event_source *source + sd_event_handler_t callback + + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + + + + + + + Description + + sd_event_source_set_prepare() may be + used to set a prepartion callback for the event source object + specified as source. The callback function + specified as callback will be invoked + immediately before the event loop goes to sleep to wait for + incoming events. It is invoked with the user data pointer passed + when the event source was created. The callback function may be + used to reconfigure the precise events to wait for. If the + callback parameter is passed as NULL the + callback function is reset. + + Event source objects have no preparation callback associated + when they are first created with calls such as + sd_event_add_io3, + sd_event_add_time3. Preparation + callback functions are supported for all event source types with + the exception of those created with + sd_event_add_exit3. Preparation + callback functions are dispatched in the order indicated by the + event source's priority field, as set with + sd_event_source_set_priority3. Preparation + callbacks of disabled event sources (see + sd_event_source_set_enabled3) + are not invoked. + + + + Return Value + + On success, + sd_event_source_set_prepare() returns a + non-negative integer. On failure, it returns a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ESTALE + + The event loop is already terminated. + + + + -ENOMEM + + Not enough memory. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The specified event source has been created + with + sd_event_add_exit3. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml new file mode 100644 index 000000000..0f7fde203 --- /dev/null +++ b/man/sd_event_source_set_priority.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_event_source_set_priority + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_priority + 3 + + + + sd_event_source_set_priority + sd_event_source_get_priority + SD_EVENT_PRIORITY_IMPORTANT + SD_EVENT_PRIORITY_NORMAL + SD_EVENT_PRIORITY_IDLE + + Set or retrieve the priority of event sources + + + + + #include <elogind/sd-event.h> + + enum { + SD_EVENT_SOURCE_IMPORTANT = -100, + SD_EVENT_SOURCE_NORMAL = 0, + SD_EVENT_SOURCE_IDLE = 100, +}; + + + int sd_event_source_set_priority + sd_event_source *source + int64_t priority + + + + int sd_event_source_get_priority + sd_event_source *source + int64_t *priority + + + + + + + Description + + sd_event_source_set_priority() may be + used to set the priority for the event source object specified as + source. The priority is specified as an + arbitrary signed 64bit integer. The priority is initialized to + SD_EVENT_PRIORITY_NORMAL (0) when the event + source is allocated with a call such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the + event sources' priorities. Event sources with smaller priority + values are dispatched first. As well-known points of reference, + the constants SD_EVENT_PRIORITY_IMPORTANT + (-100), SD_EVENT_PRIORITY_NORMAL (0) and + SD_EVENT_PRIORITY_IDLE (100) may be used to + indicate event sources that shall be dispatched early, normally or + late. It is recommended to specify priorities based on these + definitions, and relative to them -- however, the full 64bit + signed integer range is available for ordering event + sources. + + Priorities define the order in which event sources that have + seen events are dispatched. Care should be taken to ensure that + high-priority event sources (those with negative priority values + assigned) do not cause starvation of low-priority event sources + (those with positive priority values assigned). + + The order in which event sources with the same priority are + dispatched is undefined, but the event loop generally tries to + dispatch them in the order it learnt about events on them. As the + backing kernel primitives do not provide accurate information + about the order in which events occured this is not necessarily + reliable. However, it is guaranteed that if events are seen on + multiple same-priority event sources at the same time, each one is + not dispatched again until all others have been dispatched + once. This behaviour guarantees that within each priority + particular event sources do not starve or dominate the event + loop. + + sd_event_source_get_priority() may be + used to query the current priority assigned to the event source + object source. + + + + Return Value + + On success, + sd_event_source_set_priority() and + sd_event_source_get_priority() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3 + + + + diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml new file mode 100644 index 000000000..697539662 --- /dev/null +++ b/man/sd_event_source_set_userdata.xml @@ -0,0 +1,119 @@ + + + + + + + + + sd_event_source_set_userdata + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_userdata + 3 + + + + sd_event_source_set_userdata + sd_event_source_get_userdata + + Set or retrieve user data pointer of event sources + + + + + #include <elogind/sd-event.h> + + + void* sd_event_source_set_userdata + sd_event_source *source + void *userdata + + + + void* sd_event_source_get_userdata + sd_event_source *source + + + + + + + Description + + sd_event_source_set_userdata() may be + used to set an arbitrary user data pointer for the event source + object specified as source. The user data + pointer is usually specified when creating an event source object + with calls such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be updated with this call. The user data pointer is also + passed to all handler callback functions associated with the event + source. The userdata parameter specifies + the new user data pointer to set, the function returns the + previous user data pointer. Note that NULL is + a valid user data pointer. + + sd_event_source_get_userdata() may be + used to query the current user data pointer assigned to the event + source object source. + + + + Return Value + + On success, + sd_event_source_set_userdata() and + sd_event_source_get_userdata() return the + previously set user data pointer. On failure, they return + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_description3 + + + + diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml new file mode 100644 index 000000000..3c1a64dc7 --- /dev/null +++ b/man/sd_event_source_unref.xml @@ -0,0 +1,125 @@ + + + + + + + + + sd_event_source_unref + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_unref + 3 + + + + sd_event_source_unref + sd_event_source_ref + + Increase or decrease event source reference counters + + + + + #include <elogind/sd-event.h> + + + sd_event_source* sd_event_source_unref + sd_event_source *source + + + + sd_event_source* sd_event_source_ref + sd_event_source *source + + + + + + + Description + + sd_event_source_unref() may be used to + decrement by one the reference counter of the event source object + specified as source. The reference counter + is initially set to one, when the event source is created with calls + such as + sd_event_add_io3 + or + sd_event_add_time3. When + the reference counter reaches zero it is removed from its event loop + object and destroyed. + + sd_event_source_ref() may be used + to increase by one the reference counter of the event source object + specified as source. + + Both functions execute no operation if the passed event + source object is NULL. + + Note that event source objects stay alive and may be + dispatched as long as they have a reference counter greater than + zero. In order to drop a reference of an event source and make + sure the associated event source handler function is not called + anymore it is recommended to combine a call of + sd_event_source_unref() with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF. + + + + Return Value + + sd_event_source_unref() always returns + NULL. + sd_event_source_ref() always returns the + event source object passed in. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3 + + + + -- 2.30.2