picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
Systemd/src/systemd/sd-event.h

153 lines
6.5 KiB
C
Raw Normal View History

Add SPDX license identifiers to source files under the LGPL This follows what the kernel is doing, c.f. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=5fd54ace4721fc5ce2bb5aef6318fcf17f421460.
2017-11-18 17:09:20 +01:00
/* SPDX-License-Identifier: LGPL-2.1+ */
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
#ifndef foosdeventhfoo
#define foosdeventhfoo
/***
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
***/
#include <inttypes.h>
#include <signal.h>
tree-wide: sort includes in *.h This is a continuation of the previous include sort patch, which only sorted for .c files.
2015-11-18 22:46:33 +01:00
#include <sys/epoll.h>
sd-event: add new API for subscribing to inotify events This adds a new call sd_event_add_inotify() which allows watching for inotify events on specified paths. sd-event will try to minimize the number of inotify fds allocated, and will try to add file watches to the same inotify fd objects as far as that's possible. Doing this kind of inotify object should optimize behaviour in programs that watch a limited set of mostly independent files as in most cases a single inotify object will suffice for watching all files. Traditionally, this kind of coalescing logic (i.e. that multiple event sources are implemented on top of a single inotify object) was very hard to do, as the inotify API had serious limitations: it only allowed adding watches by path, and would implicitly merge watches installed on the same node via different path, without letting the caller know about whether such merging took place or not. With the advent of O_PATH this issue can be dealt with to some point: instead of adding a path to watch to an inotify object with inotify_add_watch() right away, we can open the path with O_PATH first, call fstat() on the fd, and check the .st_dev/.st_ino fields of that against a list of watches we already have in place. If we find one we know that the inotify_add_watch() will update the watch mask of the existing watch, otherwise it will create a new watch. To make this race-free we use inotify_add_watch() on the /proc/self/fd/ path of the O_PATH fd, instead of the original path, so that we do the checking and watch updating with guaranteed the same inode. This approach let's us deal safely with inodes that may appear under various different paths (due to symlinks, hardlinks, bind mounts, fs namespaces). However it's not a perfect solution: currently the kernel has no API for changing the watch mask of an existing watch -- unless you have a path or fd to the original inode. This means we can "merge" the watches of the same inode of multiple event sources correctly, but we cannot "unmerge" it again correctly in many cases, as access to the original inode might have been lost, due to renames, mount/unmount, or deletions. We could in theory always keep open an O_PATH fd of the inode to watch so that we can change the mask anytime we want, but this is highly problematics, as it would consume too many fds (and in fact the scarcity of fds is the reason why watch descriptors are a separate concepts from fds) and would keep the backing mounts busy (wds do not keep mounts busy, fds do). The current implemented approach to all this: filter in userspace and accept that the watch mask on some inode might be higher than necessary due to earlier installed event sources that might have ceased to exist. This approach while ugly shouldn't be too bad for most cases as the same inodes are probably wacthed for the same masks in most implementations. In order to implement priorities correctly a seperate inotify object is allocated for each priority that is used. This way we get separate per-priority event queues, of which we never dequeue more than a few events at a time. Fixes: #3982
2018-05-28 16:26:50 +02:00
#include <sys/inotify.h>
tree-wide: sort includes in *.h This is a continuation of the previous include sort patch, which only sorted for .c files.
2015-11-18 22:46:33 +01:00
#include <sys/signalfd.h>
#include <sys/types.h>
Include time.h in sd-event.h The time-related functions in sd-event.h take as inputs constants (CLOCK_*) defined in time.h. By including time.h in sd-event.h, we free the developer from having to do this manually.
2018-01-24 15:53:49 +01:00
#include <time.h>
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
api: replace manual C++ guards by macros
2013-11-07 16:44:48 +01:00
#include "_sd-common.h"
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
/*
Why is this better than pure epoll?
src/systemd: fix grammar and spelling errors in comments
2014-03-25 04:14:28 +01:00
- Supports event source prioritization
- Scales better with a large number of time events because it does not require one timerfd each
event: refuse operation if the caller tries to reuse an event loop after a fork()
2013-10-10 21:37:50 +02:00
- Automatically tries to coalesce timer events system-wide
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
- Handles signals and child PIDs
*/
api: replace manual C++ guards by macros
2013-11-07 16:44:48 +01:00
_SD_BEGIN_DECLARATIONS;
api: add C++ guards
2013-11-07 03:47:42 +01:00
Add support for SD_EVENT_DEFAULT Currently, sd-event supports the ability to have a thread-local default event loop. However, this is less useful than it can be since all functions which require an sd_event* as input require the caller to pass it. This patch adds a new macro which allows the developer to pass a constant SD_EVENT_DEFAULT instead. This reduces work for the caller. For example: r = sd_event_default(&e); r = sd_event_add_io(e, ...); sd_event_unref(e); Becomes: r = sd_event_add_io(SD_EVENT_DEFAULT, ...); If no thread-local default event loop exists, the function calls will return -ENOPKG. No event loop will ever be implicitly created.
2018-01-22 21:38:07 +01:00
#define SD_EVENT_DEFAULT ((sd_event *) 1)
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
typedef struct sd_event sd_event;
typedef struct sd_event_source sd_event_source;
event: implement quit handlers Quit handlers are executed when an event loop is terminated via sd_event_request_quit(). They are in a way atexit() handlers that are executed in a well-defined environment, time and thread: from the event loop thread when the event loop finishes.
2013-10-11 00:49:11 +02:00
enum {
event: rename the "mute" field of event sources to "enabled" In addition, the states "UNMUTED" and "MUTED" become "ON" and "OFF". This has the benefit that a possible value of this field is not identical to its name, thus minimizing confusion.
2013-10-11 01:08:15 +02:00
SD_EVENT_OFF = 0,
SD_EVENT_ON = 1,
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
SD_EVENT_ONESHOT = -1
event: implement quit handlers Quit handlers are executed when an event loop is terminated via sd_event_request_quit(). They are in a way atexit() handlers that are executed in a well-defined environment, time and thread: from the event loop thread when the event loop finishes.
2013-10-11 00:49:11 +02:00
};
enum {
sd-event: rename PASSIVE/PREPARED to INITIAL/ARMED
2015-03-14 11:47:35 +01:00
SD_EVENT_INITIAL,
SD_EVENT_ARMED,
sd-event: split run into prepare/wait/dispatch This will allow sd-event to be integrated into an external event loop, which in turn will allow (say) glib-based applications to use our various libraries, without manually integrating each of them (bus, rtnl, dhcp, ...). The external event-loop should integrate sd-event int he following way: Every iteration must start with a call to sd_event_prepare(), which will return 0 if no event sources are ready to be processed, a positive value if they are and a negative value on error. sd_event_prepare() may only be called following sd_event_dispatch(); a call to sd_event_wait() indicating that no sources are ready to be dispatched; or a failed call to sd_event_dispatch() or sd_event_wait(). A successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched must be followed by a call to sd_event_wait(), which will return 0 if it timed out without event sources being ready to be processed, a negative value on error and a positive value otherwise. sd_event_wait() may only be called following a successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched. If sd_event_wait() indicates that some events sources are ready to be dispatched, it must be followed by a call to sd_event_dispatch(). This is the only time sd_event_dispatch() may be called.
2014-08-15 18:49:29 +02:00
SD_EVENT_PENDING,
event: implement quit handlers Quit handlers are executed when an event loop is terminated via sd_event_request_quit(). They are in a way atexit() handlers that are executed in a well-defined environment, time and thread: from the event loop thread when the event loop finishes.
2013-10-11 00:49:11 +02:00
SD_EVENT_RUNNING,
event: rework sd-event exit logic With this change a failing event source handler will not cause the entire event loop to fail. Instead, we just disable the specific event source, log a message at debug level and go on. This also introduces a new concept of "exit code" which can be stored in the event loop and is returned by sd_event_loop(). We also rename "quit" to "exit" everywhere else. Altogether this should make things more robus and keep errors local while still providing a way to return event loop errors in a clear way.
2013-12-12 22:21:25 +01:00
SD_EVENT_EXITING,
sd-event: define a new PREPARING state We already have a state RUNNING and EXITING when we dispatch regular and exit callbacks. Let's introduce a new state called PREPARING that is active while we invoke preparation callbacks. This way we have a state each for all three kinds of event handlers. The states are currently not documented, hence let's add a new state to the end, before we start documenting this.
2015-11-19 23:33:55 +01:00
SD_EVENT_FINISHED,
headers: remove commas at end of enum lists src/systemd/sd-journal.h:75:51: warning: commas at the end of enumerator lists are a C99-specific feature [-Wc99-extensions]
2016-03-11 19:50:56 +01:00
SD_EVENT_PREPARING
event: implement quit handlers Quit handlers are executed when an event loop is terminated via sd_event_request_quit(). They are in a way atexit() handlers that are executed in a well-defined environment, time and thread: from the event loop thread when the event loop finishes.
2013-10-11 00:49:11 +02:00
};
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
event: add some well-defined priority values of event sources
2013-11-05 00:51:14 +01:00
enum {
src/systemd: fix grammar and spelling errors in comments
2014-03-25 04:14:28 +01:00
/* And everything in-between and outside is good too */
core: convert PID 1 to libsystemd-bus This patch converts PID 1 to libsystemd-bus and thus drops the dependency on libdbus. The only remaining code using libdbus is a test case that validates our bus marshalling against libdbus' marshalling, and this dependency can be turned off. This patch also adds a couple of things to libsystem-bus, that are necessary to make the port work: - Synthesizing of "Disconnected" messages when bus connections are severed. - Support for attaching multiple vtables for the same interface on the same path. This patch also fixes the SetDefaultTarget() and GetDefaultTarget() bus calls which used an inappropriate signature. As a side effect we will now generate PropertiesChanged messages which carry property contents, rather than just invalidation information.
2013-11-19 21:12:59 +01:00
SD_EVENT_PRIORITY_IMPORTANT = -100,
SD_EVENT_PRIORITY_NORMAL = 0,
SD_EVENT_PRIORITY_IDLE = 100
event: add some well-defined priority values of event sources
2013-11-05 00:51:14 +01:00
};
core: convert PID 1 to libsystemd-bus This patch converts PID 1 to libsystemd-bus and thus drops the dependency on libdbus. The only remaining code using libdbus is a test case that validates our bus marshalling against libdbus' marshalling, and this dependency can be turned off. This patch also adds a couple of things to libsystem-bus, that are necessary to make the port work: - Synthesizing of "Disconnected" messages when bus connections are severed. - Support for attaching multiple vtables for the same interface on the same path. This patch also fixes the SetDefaultTarget() and GetDefaultTarget() bus calls which used an inappropriate signature. As a side effect we will now generate PropertiesChanged messages which carry property contents, rather than just invalidation information.
2013-11-19 21:12:59 +01:00
typedef int (*sd_event_handler_t)(sd_event_source *s, void *userdata);
typedef int (*sd_event_io_handler_t)(sd_event_source *s, int fd, uint32_t revents, void *userdata);
typedef int (*sd_event_time_handler_t)(sd_event_source *s, uint64_t usec, void *userdata);
typedef int (*sd_event_signal_handler_t)(sd_event_source *s, const struct signalfd_siginfo *si, void *userdata);
check for _POSIX_C_SOURCE instead of __USE_POSIX* check for _GNU_SOURCE as well as sd_event_child_handler_t needs to be defined correctly while compiling systemd
2017-03-15 14:16:40 +01:00
#if defined _GNU_SOURCE || _POSIX_C_SOURCE >= 199309L
core: convert PID 1 to libsystemd-bus This patch converts PID 1 to libsystemd-bus and thus drops the dependency on libdbus. The only remaining code using libdbus is a test case that validates our bus marshalling against libdbus' marshalling, and this dependency can be turned off. This patch also adds a couple of things to libsystem-bus, that are necessary to make the port work: - Synthesizing of "Disconnected" messages when bus connections are severed. - Support for attaching multiple vtables for the same interface on the same path. This patch also fixes the SetDefaultTarget() and GetDefaultTarget() bus calls which used an inappropriate signature. As a side effect we will now generate PropertiesChanged messages which carry property contents, rather than just invalidation information.
2013-11-19 21:12:59 +01:00
typedef int (*sd_event_child_handler_t)(sd_event_source *s, const siginfo_t *si, void *userdata);
headers: do not use siginfo_t if not defined Simply avoid the trouble and use a void* if the define is missing. We lose type safety, but who cares. sigaction(2) says that siginfo_t requires _POSIX_C_SOURCE >= 199309L, but we can be a bit more generous and use the same define as /usr/include/signal.h.
2016-03-11 19:46:12 +01:00
#else
typedef void* sd_event_child_handler_t;
#endif
sd-event: add new API for subscribing to inotify events This adds a new call sd_event_add_inotify() which allows watching for inotify events on specified paths. sd-event will try to minimize the number of inotify fds allocated, and will try to add file watches to the same inotify fd objects as far as that's possible. Doing this kind of inotify object should optimize behaviour in programs that watch a limited set of mostly independent files as in most cases a single inotify object will suffice for watching all files. Traditionally, this kind of coalescing logic (i.e. that multiple event sources are implemented on top of a single inotify object) was very hard to do, as the inotify API had serious limitations: it only allowed adding watches by path, and would implicitly merge watches installed on the same node via different path, without letting the caller know about whether such merging took place or not. With the advent of O_PATH this issue can be dealt with to some point: instead of adding a path to watch to an inotify object with inotify_add_watch() right away, we can open the path with O_PATH first, call fstat() on the fd, and check the .st_dev/.st_ino fields of that against a list of watches we already have in place. If we find one we know that the inotify_add_watch() will update the watch mask of the existing watch, otherwise it will create a new watch. To make this race-free we use inotify_add_watch() on the /proc/self/fd/ path of the O_PATH fd, instead of the original path, so that we do the checking and watch updating with guaranteed the same inode. This approach let's us deal safely with inodes that may appear under various different paths (due to symlinks, hardlinks, bind mounts, fs namespaces). However it's not a perfect solution: currently the kernel has no API for changing the watch mask of an existing watch -- unless you have a path or fd to the original inode. This means we can "merge" the watches of the same inode of multiple event sources correctly, but we cannot "unmerge" it again correctly in many cases, as access to the original inode might have been lost, due to renames, mount/unmount, or deletions. We could in theory always keep open an O_PATH fd of the inode to watch so that we can change the mask anytime we want, but this is highly problematics, as it would consume too many fds (and in fact the scarcity of fds is the reason why watch descriptors are a separate concepts from fds) and would keep the backing mounts busy (wds do not keep mounts busy, fds do). The current implemented approach to all this: filter in userspace and accept that the watch mask on some inode might be higher than necessary due to earlier installed event sources that might have ceased to exist. This approach while ugly shouldn't be too bad for most cases as the same inodes are probably wacthed for the same masks in most implementations. In order to implement priorities correctly a seperate inotify object is allocated for each priority that is used. This way we get separate per-priority event queues, of which we never dequeue more than a few events at a time. Fixes: #3982
2018-05-28 16:26:50 +02:00
typedef int (*sd_event_inotify_handler_t)(sd_event_source *s, const struct inotify_event *event, void *userdata);
sd-event: add destroy callback logic to sd-event too This adds what has been added to sd_bus_slot and sd_bus_track to sd_event too.
2018-06-07 12:40:35 +02:00
typedef void (*sd_event_destroy_t)(void *userdata);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
bus: introduce concept of a "default" event loop per-thread and make use of it everywhere Try to emphasize a bit that there should be a mapping between event loops and threads, hence introduce a logic that there's one "default" event loop for each thread, that can be queried via "sd_event_default()".
2013-11-11 19:34:13 +01:00
int sd_event_default(sd_event **e);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
int sd_event_new(sd_event **e);
sd_event* sd_event_ref(sd_event *e);
sd_event* sd_event_unref(sd_event *e);
api: in constructor function calls, always put the returned object pointer first (or second) Previously the returned object of constructor functions where sometimes returned as last, sometimes as first and sometimes as second parameter. Let's clean this up a bit. Here are the new rules: 1. The object the new object is derived from is put first, if there is any 2. The object we are creating will be returned in the next arguments 3. This is followed by any additional arguments Rationale: For functions that operate on an object we always put that object first. Constructors should probably not be too different in this regard. Also, if the additional parameters might want to use varargs which suggests to put them last. Note that this new scheme only applies to constructor functions, not to all other functions. We do give a lot of freedom for those. Note that this commit only changes the order of the new functions we added, for old ones we accept the wrong order and leave it like that.
2014-02-19 23:54:58 +01:00
int sd_event_add_io(sd_event *e, sd_event_source **s, int fd, uint32_t events, sd_event_io_handler_t callback, void *userdata);
sd-event: rework API to support CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM, too
2014-03-24 02:49:09 +01:00
int sd_event_add_time(sd_event *e, sd_event_source **s, clockid_t clock, uint64_t usec, uint64_t accuracy, sd_event_time_handler_t callback, void *userdata);
api: in constructor function calls, always put the returned object pointer first (or second) Previously the returned object of constructor functions where sometimes returned as last, sometimes as first and sometimes as second parameter. Let's clean this up a bit. Here are the new rules: 1. The object the new object is derived from is put first, if there is any 2. The object we are creating will be returned in the next arguments 3. This is followed by any additional arguments Rationale: For functions that operate on an object we always put that object first. Constructors should probably not be too different in this regard. Also, if the additional parameters might want to use varargs which suggests to put them last. Note that this new scheme only applies to constructor functions, not to all other functions. We do give a lot of freedom for those. Note that this commit only changes the order of the new functions we added, for old ones we accept the wrong order and leave it like that.
2014-02-19 23:54:58 +01:00
int sd_event_add_signal(sd_event *e, sd_event_source **s, int sig, sd_event_signal_handler_t callback, void *userdata);
int sd_event_add_child(sd_event *e, sd_event_source **s, pid_t pid, int options, sd_event_child_handler_t callback, void *userdata);
sd-event: add new API for subscribing to inotify events This adds a new call sd_event_add_inotify() which allows watching for inotify events on specified paths. sd-event will try to minimize the number of inotify fds allocated, and will try to add file watches to the same inotify fd objects as far as that's possible. Doing this kind of inotify object should optimize behaviour in programs that watch a limited set of mostly independent files as in most cases a single inotify object will suffice for watching all files. Traditionally, this kind of coalescing logic (i.e. that multiple event sources are implemented on top of a single inotify object) was very hard to do, as the inotify API had serious limitations: it only allowed adding watches by path, and would implicitly merge watches installed on the same node via different path, without letting the caller know about whether such merging took place or not. With the advent of O_PATH this issue can be dealt with to some point: instead of adding a path to watch to an inotify object with inotify_add_watch() right away, we can open the path with O_PATH first, call fstat() on the fd, and check the .st_dev/.st_ino fields of that against a list of watches we already have in place. If we find one we know that the inotify_add_watch() will update the watch mask of the existing watch, otherwise it will create a new watch. To make this race-free we use inotify_add_watch() on the /proc/self/fd/ path of the O_PATH fd, instead of the original path, so that we do the checking and watch updating with guaranteed the same inode. This approach let's us deal safely with inodes that may appear under various different paths (due to symlinks, hardlinks, bind mounts, fs namespaces). However it's not a perfect solution: currently the kernel has no API for changing the watch mask of an existing watch -- unless you have a path or fd to the original inode. This means we can "merge" the watches of the same inode of multiple event sources correctly, but we cannot "unmerge" it again correctly in many cases, as access to the original inode might have been lost, due to renames, mount/unmount, or deletions. We could in theory always keep open an O_PATH fd of the inode to watch so that we can change the mask anytime we want, but this is highly problematics, as it would consume too many fds (and in fact the scarcity of fds is the reason why watch descriptors are a separate concepts from fds) and would keep the backing mounts busy (wds do not keep mounts busy, fds do). The current implemented approach to all this: filter in userspace and accept that the watch mask on some inode might be higher than necessary due to earlier installed event sources that might have ceased to exist. This approach while ugly shouldn't be too bad for most cases as the same inodes are probably wacthed for the same masks in most implementations. In order to implement priorities correctly a seperate inotify object is allocated for each priority that is used. This way we get separate per-priority event queues, of which we never dequeue more than a few events at a time. Fixes: #3982
2018-05-28 16:26:50 +02:00
int sd_event_add_inotify(sd_event *e, sd_event_source **s, const char *path, uint32_t mask, sd_event_inotify_handler_t callback, void *userdata);
api: in constructor function calls, always put the returned object pointer first (or second) Previously the returned object of constructor functions where sometimes returned as last, sometimes as first and sometimes as second parameter. Let's clean this up a bit. Here are the new rules: 1. The object the new object is derived from is put first, if there is any 2. The object we are creating will be returned in the next arguments 3. This is followed by any additional arguments Rationale: For functions that operate on an object we always put that object first. Constructors should probably not be too different in this regard. Also, if the additional parameters might want to use varargs which suggests to put them last. Note that this new scheme only applies to constructor functions, not to all other functions. We do give a lot of freedom for those. Note that this commit only changes the order of the new functions we added, for old ones we accept the wrong order and leave it like that.
2014-02-19 23:54:58 +01:00
int sd_event_add_defer(sd_event *e, sd_event_source **s, sd_event_handler_t callback, void *userdata);
event: add new kind of event source called "post" This new event source is triggered by the dispatching of any non-post event source. It can thus be used to do clean-up or recheck work, triggered by any other event source having been executed. This is different from "defer" event source which are unconditionally triggered as long as they are enabled. A "defer" event source that does nothing will result in the event loop busy looping unless it is turned off eventually. This is different for "post" event sources that will be only triggered when some other non-post ran, and will thus not keep the event loop busy on its own.
2014-02-21 21:06:09 +01:00
int sd_event_add_post(sd_event *e, sd_event_source **s, sd_event_handler_t callback, void *userdata);
api: in constructor function calls, always put the returned object pointer first (or second) Previously the returned object of constructor functions where sometimes returned as last, sometimes as first and sometimes as second parameter. Let's clean this up a bit. Here are the new rules: 1. The object the new object is derived from is put first, if there is any 2. The object we are creating will be returned in the next arguments 3. This is followed by any additional arguments Rationale: For functions that operate on an object we always put that object first. Constructors should probably not be too different in this regard. Also, if the additional parameters might want to use varargs which suggests to put them last. Note that this new scheme only applies to constructor functions, not to all other functions. We do give a lot of freedom for those. Note that this commit only changes the order of the new functions we added, for old ones we accept the wrong order and leave it like that.
2014-02-19 23:54:58 +01:00
int sd_event_add_exit(sd_event *e, sd_event_source **s, sd_event_handler_t callback, void *userdata);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
sd-event: split run into prepare/wait/dispatch This will allow sd-event to be integrated into an external event loop, which in turn will allow (say) glib-based applications to use our various libraries, without manually integrating each of them (bus, rtnl, dhcp, ...). The external event-loop should integrate sd-event int he following way: Every iteration must start with a call to sd_event_prepare(), which will return 0 if no event sources are ready to be processed, a positive value if they are and a negative value on error. sd_event_prepare() may only be called following sd_event_dispatch(); a call to sd_event_wait() indicating that no sources are ready to be dispatched; or a failed call to sd_event_dispatch() or sd_event_wait(). A successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched must be followed by a call to sd_event_wait(), which will return 0 if it timed out without event sources being ready to be processed, a negative value on error and a positive value otherwise. sd_event_wait() may only be called following a successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched. If sd_event_wait() indicates that some events sources are ready to be dispatched, it must be followed by a call to sd_event_dispatch(). This is the only time sd_event_dispatch() may be called.
2014-08-15 18:49:29 +02:00
int sd_event_prepare(sd_event *e);
sd-event: define a new PREPARING state We already have a state RUNNING and EXITING when we dispatch regular and exit callbacks. Let's introduce a new state called PREPARING that is active while we invoke preparation callbacks. This way we have a state each for all three kinds of event handlers. The states are currently not documented, hence let's add a new state to the end, before we start documenting this.
2015-11-19 23:33:55 +01:00
int sd_event_wait(sd_event *e, uint64_t usec);
sd-event: split run into prepare/wait/dispatch This will allow sd-event to be integrated into an external event loop, which in turn will allow (say) glib-based applications to use our various libraries, without manually integrating each of them (bus, rtnl, dhcp, ...). The external event-loop should integrate sd-event int he following way: Every iteration must start with a call to sd_event_prepare(), which will return 0 if no event sources are ready to be processed, a positive value if they are and a negative value on error. sd_event_prepare() may only be called following sd_event_dispatch(); a call to sd_event_wait() indicating that no sources are ready to be dispatched; or a failed call to sd_event_dispatch() or sd_event_wait(). A successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched must be followed by a call to sd_event_wait(), which will return 0 if it timed out without event sources being ready to be processed, a negative value on error and a positive value otherwise. sd_event_wait() may only be called following a successful call to sd_event_prepare() indicating that no event sources are ready to be dispatched. If sd_event_wait() indicates that some events sources are ready to be dispatched, it must be followed by a call to sd_event_dispatch(). This is the only time sd_event_dispatch() may be called.
2014-08-15 18:49:29 +02:00
int sd_event_dispatch(sd_event *e);
sd-event: define a new PREPARING state We already have a state RUNNING and EXITING when we dispatch regular and exit callbacks. Let's introduce a new state called PREPARING that is active while we invoke preparation callbacks. This way we have a state each for all three kinds of event handlers. The states are currently not documented, hence let's add a new state to the end, before we start documenting this.
2015-11-19 23:33:55 +01:00
int sd_event_run(sd_event *e, uint64_t usec);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
int sd_event_loop(sd_event *e);
event: rework sd-event exit logic With this change a failing event source handler will not cause the entire event loop to fail. Instead, we just disable the specific event source, log a message at debug level and go on. This also introduces a new concept of "exit code" which can be stored in the event loop and is returned by sd_event_loop(). We also rename "quit" to "exit" everywhere else. Altogether this should make things more robus and keep errors local while still providing a way to return event loop errors in a clear way.
2013-12-12 22:21:25 +01:00
int sd_event_exit(sd_event *e, int code);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
sd-event: rework API to support CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM, too
2014-03-24 02:49:09 +01:00
int sd_event_now(sd_event *e, clockid_t clock, uint64_t *usec);
sd-event: add API to access epoll_fd This is a prerequisite for integrating sd-event into an external event loop.
2014-08-15 21:04:07 +02:00
int sd_event_get_fd(sd_event *e);
event: implement quit handlers Quit handlers are executed when an event loop is terminated via sd_event_request_quit(). They are in a way atexit() handlers that are executed in a well-defined environment, time and thread: from the event loop thread when the event loop finishes.
2013-10-11 00:49:11 +02:00
int sd_event_get_state(sd_event *e);
bus: introduce concept of a "default" event loop per-thread and make use of it everywhere Try to emphasize a bit that there should be a mapping between event loops and threads, hence introduce a logic that there's one "default" event loop for each thread, that can be queried via "sd_event_default()".
2013-11-11 19:34:13 +01:00
int sd_event_get_tid(sd_event *e, pid_t *tid);
event: rework sd-event exit logic With this change a failing event source handler will not cause the entire event loop to fail. Instead, we just disable the specific event source, log a message at debug level and go on. This also introduces a new concept of "exit code" which can be stored in the event loop and is returned by sd_event_loop(). We also rename "quit" to "exit" everywhere else. Altogether this should make things more robus and keep errors local while still providing a way to return event loop errors in a clear way.
2013-12-12 22:21:25 +01:00
int sd_event_get_exit_code(sd_event *e, int *code);
event: hook up sd-event with the service watchdog logic Adds a new call sd_event_set_watchdog() that can be used to hook up the event loop with the watchdog supervision logic of systemd. If enabled and $WATCHDOG_USEC is set the event loop will ping the invoking systemd daemon right after coming back from epoll_wait() but not more often than $WATCHDOG_USEC/4. The epoll_wait() will sleep no longer than $WATCHDOG_USEC/4*3, to make sure the service manager is called in time. This means that setting WatchdogSec= in a .service file and calling sd_event_set_watchdog() in your daemon is enough to hook it up with the watchdog logic.
2013-12-11 18:14:52 +01:00
int sd_event_set_watchdog(sd_event *e, int b);
event: allow to query userdata and watchdog state
2013-12-13 04:14:25 +01:00
int sd_event_get_watchdog(sd_event *e);
sd-event: expose the event loop iteration counter via sd_event_get_iteration() (#3631) This extends the existing event loop iteration counter to 64bit, and exposes it via a new function sd_event_get_iteration(). This is helpful for cases like issue #3612. After all, since we maintain the counter anyway, we might as well expose it. (This also fixes an unrelated issue in the man page for sd_event_wait() where micro and milliseconds got mixed up)
2016-06-30 21:25:07 +02:00
int sd_event_get_iteration(sd_event *e, uint64_t *ret);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
sd_event_source* sd_event_source_ref(sd_event_source *s);
sd_event_source* sd_event_source_unref(sd_event_source *s);
sd-event: reorder header slightly
2014-05-15 00:44:29 +02:00
sd_event *sd_event_source_get_event(sd_event_source *s);
void* sd_event_source_get_userdata(sd_event_source *s);
void* sd_event_source_set_userdata(sd_event_source *s, void *userdata);
sd-event: rename sd_event_source_set_name() to sd_event_source_get_name() To mirror the recent name change of the concept for sd_bus objects, follow the same logic for sd_event_source objects, too.
2014-11-04 16:27:05 +01:00
int sd_event_source_set_description(sd_event_source *s, const char *description);
int sd_event_source_get_description(sd_event_source *s, const char **description);
core: convert PID 1 to libsystemd-bus This patch converts PID 1 to libsystemd-bus and thus drops the dependency on libdbus. The only remaining code using libdbus is a test case that validates our bus marshalling against libdbus' marshalling, and this dependency can be turned off. This patch also adds a couple of things to libsystem-bus, that are necessary to make the port work: - Synthesizing of "Disconnected" messages when bus connections are severed. - Support for attaching multiple vtables for the same interface on the same path. This patch also fixes the SetDefaultTarget() and GetDefaultTarget() bus calls which used an inappropriate signature. As a side effect we will now generate PropertiesChanged messages which carry property contents, rather than just invalidation information.
2013-11-19 21:12:59 +01:00
int sd_event_source_set_prepare(sd_event_source *s, sd_event_handler_t callback);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
int sd_event_source_get_pending(sd_event_source *s);
event: extend priority raneg to 64bit The kdbus prioq logic will use 64bit prios too, so let's keep this similar in style. Using 64bit here has the advantage, that pointers and pretty much anything else can be mapped naturally to priorities if so desired.
2014-01-15 09:08:20 +01:00
int sd_event_source_get_priority(sd_event_source *s, int64_t *priority);
int sd_event_source_set_priority(sd_event_source *s, int64_t priority);
event: rename the "mute" field of event sources to "enabled" In addition, the states "UNMUTED" and "MUTED" become "ON" and "OFF". This has the benefit that a possible value of this field is not identical to its name, thus minimizing confusion.
2013-10-11 01:08:15 +02:00
int sd_event_source_get_enabled(sd_event_source *s, int *enabled);
int sd_event_source_set_enabled(sd_event_source *s, int enabled);
event: move all library calls over to new assert_return() macro
2013-10-11 02:11:30 +02:00
int sd_event_source_get_io_fd(sd_event_source *s);
event: add ability to change fd of an active event source
2013-12-13 05:13:59 +01:00
int sd_event_source_set_io_fd(sd_event_source *s, int fd);
Add fd close support to sd_event_source It is often the case that a file descriptor and its corresponding IO sd_event_source share a life span. When this is the case, developers will have to unref the event source and close the file descriptor. Instead, we can just have the event source take ownership of the file descriptor and close it when the event source is freed. This is especially useful when combined with cleanup attributes and sd_event_source_unrefp(). This patch adds two new public functions: sd_event_source_get_io_fd_own() sd_event_source_set_io_fd_own()
2018-01-24 15:45:48 +01:00
int sd_event_source_get_io_fd_own(sd_event_source *s);
int sd_event_source_set_io_fd_own(sd_event_source *s, int own);
event: move all library calls over to new assert_return() macro
2013-10-11 02:11:30 +02:00
int sd_event_source_get_io_events(sd_event_source *s, uint32_t* events);
int sd_event_source_set_io_events(sd_event_source *s, uint32_t events);
int sd_event_source_get_io_revents(sd_event_source *s, uint32_t* revents);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
int sd_event_source_get_time(sd_event_source *s, uint64_t *usec);
int sd_event_source_set_time(sd_event_source *s, uint64_t usec);
event: add timer accuracy/coalescing logic In order to improve energy consumption we should minimize our wake-ups when handling timers. Hence, for each timer take an accuracy value and schedule the actual wake-up time somewhere between the specified time and the specified timer plus the accuracy. The specified time of timer event sources hence becomes the time the handler is called the *earliest*, and the specified time plus the accuracy the time by which it is called the *latest*, leaving the library the freedom to schedule the wake-up somewhere inbetween. If the accuracy is specified as 0 the default of 250ms will be used. When scheduling timeouts we will now try to elapse them at the same point within each second, across the entire system. We do this by using a fixed perturbation value keyed off the boot id. If this point within a second is not in the acceptable range, we try again with a fixed time within each 250ms time step. If that doesn't work either, we wake up at the last possible time.
2013-10-10 21:16:21 +02:00
int sd_event_source_get_time_accuracy(sd_event_source *s, uint64_t *usec);
man: document sd_event_add_time(3)
2014-05-06 18:51:08 +02:00
int sd_event_source_set_time_accuracy(sd_event_source *s, uint64_t usec);
sd-event: rework API to support CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM, too
2014-03-24 02:49:09 +01:00
int sd_event_source_get_time_clock(sd_event_source *s, clockid_t *clock);
event: move all library calls over to new assert_return() macro
2013-10-11 02:11:30 +02:00
int sd_event_source_get_signal(sd_event_source *s);
event: add sd_event_source_get_child_pid() call to query the PID of a child event source
2013-10-11 01:33:25 +02:00
int sd_event_source_get_child_pid(sd_event_source *s, pid_t *pid);
sd-event: add new API for subscribing to inotify events This adds a new call sd_event_add_inotify() which allows watching for inotify events on specified paths. sd-event will try to minimize the number of inotify fds allocated, and will try to add file watches to the same inotify fd objects as far as that's possible. Doing this kind of inotify object should optimize behaviour in programs that watch a limited set of mostly independent files as in most cases a single inotify object will suffice for watching all files. Traditionally, this kind of coalescing logic (i.e. that multiple event sources are implemented on top of a single inotify object) was very hard to do, as the inotify API had serious limitations: it only allowed adding watches by path, and would implicitly merge watches installed on the same node via different path, without letting the caller know about whether such merging took place or not. With the advent of O_PATH this issue can be dealt with to some point: instead of adding a path to watch to an inotify object with inotify_add_watch() right away, we can open the path with O_PATH first, call fstat() on the fd, and check the .st_dev/.st_ino fields of that against a list of watches we already have in place. If we find one we know that the inotify_add_watch() will update the watch mask of the existing watch, otherwise it will create a new watch. To make this race-free we use inotify_add_watch() on the /proc/self/fd/ path of the O_PATH fd, instead of the original path, so that we do the checking and watch updating with guaranteed the same inode. This approach let's us deal safely with inodes that may appear under various different paths (due to symlinks, hardlinks, bind mounts, fs namespaces). However it's not a perfect solution: currently the kernel has no API for changing the watch mask of an existing watch -- unless you have a path or fd to the original inode. This means we can "merge" the watches of the same inode of multiple event sources correctly, but we cannot "unmerge" it again correctly in many cases, as access to the original inode might have been lost, due to renames, mount/unmount, or deletions. We could in theory always keep open an O_PATH fd of the inode to watch so that we can change the mask anytime we want, but this is highly problematics, as it would consume too many fds (and in fact the scarcity of fds is the reason why watch descriptors are a separate concepts from fds) and would keep the backing mounts busy (wds do not keep mounts busy, fds do). The current implemented approach to all this: filter in userspace and accept that the watch mask on some inode might be higher than necessary due to earlier installed event sources that might have ceased to exist. This approach while ugly shouldn't be too bad for most cases as the same inodes are probably wacthed for the same masks in most implementations. In order to implement priorities correctly a seperate inotify object is allocated for each priority that is used. This way we get separate per-priority event queues, of which we never dequeue more than a few events at a time. Fixes: #3982
2018-05-28 16:26:50 +02:00
int sd_event_source_get_inotify_mask(sd_event_source *s, uint32_t *ret);
sd-event: add destroy callback logic to sd-event too This adds what has been added to sd_bus_slot and sd_bus_track to sd_event too.
2018-06-07 12:40:35 +02:00
int sd_event_source_set_destroy_callback(sd_event_source *s, sd_event_destroy_t callback);
int sd_event_source_get_destroy_callback(sd_event_source *s, sd_event_destroy_t *ret);
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
tree-wide: expose "p"-suffix unref calls in public APIs to make gcc cleanup easy GLIB has recently started to officially support the gcc cleanup attribute in its public API, hence let's do the same for our APIs. With this patch we'll define an xyz_unrefp() call for each public xyz_unref() call, to make it easy to use inside a __attribute__((cleanup())) expression. Then, all code is ported over to make use of this. The new calls are also documented in the man pages, with examples how to use them (well, I only added docs where the _unref() call itself already had docs, and the examples, only cover sd_bus_unrefp() and sd_event_unrefp()). This also renames sd_lldp_free() to sd_lldp_unref(), since that's how we tend to call our destructors these days. Note that this defines no public macro that wraps gcc's attribute and makes it easier to use. While I think it's our duty in the library to make our stuff easy to use, I figure it's not our duty to make gcc's own features easy to use on its own. Most likely, client code which wants to make use of this should define its own: #define _cleanup_(function) __attribute__((cleanup(function))) Or similar, to make the gcc feature easier to use. Making this logic public has the benefit that we can remove three header files whose only purpose was to define these functions internally. See #2008.
2015-11-27 19:13:45 +01:00
/* Define helpers so that __attribute__((cleanup(sd_event_unrefp))) and similar may be used. */
_SD_DEFINE_POINTER_CLEANUP_FUNC(sd_event, sd_event_unref);
_SD_DEFINE_POINTER_CLEANUP_FUNC(sd_event_source, sd_event_source_unref);
api: replace manual C++ guards by macros
2013-11-07 16:44:48 +01:00
_SD_END_DECLARATIONS;
api: add C++ guards
2013-11-07 03:47:42 +01:00
bus: add minimal event loop API So far we tried to use epoll directly wherever we needed an event loop. However, that has various shortcomings, such as the inability to handle larger amounts of timers (since each timerfd costs one fd, which is a very limited resource, usually bounded to 1024), and inability to do priorisation between multiple queued events. Let's add a minimal event loop API around epoll that is suitable for implementation of our own daemons and maybe one day can become public API for those who desire it. This loop is part of libsystemd-bus, but may be used independently of it.
2013-10-10 04:40:28 +02:00
#endif
Reference in a new issue Copy permalink