X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_event_new.xml;h=12716d7deb600c647aa5a328d11f3dec4ccf2780;hb=c3e41400d106b6c2482d9d42298fac1a6a882071;hp=35e58ea755e480cb8a9b1dabad4850a3f0c04794;hpb=b8bde11658366290521e3d03316378b482600323;p=elogind.git diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index 35e58ea75..12716d7de 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -1,27 +1,27 @@ - + - + sd_event_new @@ -47,32 +47,48 @@ along with systemd; If not, see . sd_event_default sd_event_ref sd_event_unref + sd_event_unrefp + sd_event_get_tid + sd_event Acquire and release an event loop object - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event sd_event; int sd_event_new - sd_bus **event + sd_event **event int sd_event_default - sd_bus **event + sd_event **event + + + + sd_event *sd_event_ref + sd_event *event - sd_bus *sd_event_ref - sd_bus *event + sd_event *sd_event_unref + sd_event *event - sd_bus *sd_event_unref - sd_bus *event + void sd_event_unrefp + sd_event **event + + + + int sd_event_get_tid + sd_event *event + pid_t *tid @@ -86,7 +102,7 @@ along with systemd; If not, see . event parameter. After use, drop the returned reference with sd_event_unref(). When the last reference is - dropped, the event loop is freed. + dropped, the object is freed. sd_event_default() acquires a reference to the default event loop object of the calling thread, possibly @@ -100,15 +116,26 @@ along with systemd; If not, see . recommended to use this call instead of sd_event_new() in order to share event loop objects between various components that are dispatched in the same - thread. All threads either have exactly zero or one default event loop - associated, but never more. + thread. All threads have exactly either zero or one default event loop + objects associated, but never more. + + After allocating an event loop object, add event sources to + it with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3 + or + sd_event_add_defer3, + and then execute the event loop using + sd_event_run3. sd_event_ref() increases the reference - counter of the specified event loop object by one. + count of the specified event loop object by one. sd_event_unref() decreases the - reference counter of the specified event loop object by one. If - the counter hits zero, the event loop object is freed. Note that it + reference count of the specified event loop object by one. If + the count hits zero, the object is freed. Note that it is freed regardless of whether it is the default event loop object for a thread or not. This means that allocating an event loop with sd_event_default(), then releasing it, and @@ -116,19 +143,54 @@ along with systemd; If not, see . sd_event_default() will result in two distinct objects. Note that, in order to free an event loop object, all remaining event sources of the event loop also need to be - freed as they each keep a reference to it. + freed as each keeps a reference to it. + + sd_event_unrefp() is similar to + sd_event_unref() but takes a pointer to a + pointer to an sd_event object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left: + + { + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +} + + sd_event_ref(), + sd_event_unref() and + sd_event_unrefp() execute no operation if the + passed in event loop object is NULL. + + sd_event_get_tid() retrieves the thread + identifier ("TID") of the thread the specified event loop object + is associated with. This call is only supported for event loops + allocated with sd_event_default(), and + returns the identifier for the thread the event loop is the + default event loop of. See gettid2 + for more information on thread identifiers. Return Value - On success, sd_event_new() and - sd_event_default() return 0 or a positive + On success, sd_event_new(), + sd_event_default() and + sd_event_get_tid() return 0 or a positive integer. On failure, they return a negative errno-style error code. sd_event_ref() always returns a pointer to the event loop object passed in. sd_event_unref() always returns - NULL. + NULL. @@ -138,30 +200,31 @@ along with systemd; If not, see . - -ENOMEM + -ENOMEM - Not enough memory to allocate object + Not enough memory to allocate the object. - -EMFILE + -EMFILE The maximum number of event loops has been allocated. - - - - Notes + + -ENXIO - sd_event_new() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. + sd_event_get_tid() was + invoked on an event loop object that was not allocated with + sd_event_default(). + + + + + See Also @@ -174,7 +237,9 @@ along with systemd; If not, see . sd_event_add_child3, sd_event_add_defer3, sd_event_add_post3, - sd_event_add_exit3 + sd_event_add_exit3, + sd_event_run3, + gettid2