sd_bus_track_new, sd_bus_track_ref, sd_bus_track_unref, sd_bus_track_unrefp, sd_bus_track_set_recursive, sd_bus_track_get_recursive, sd_bus_track_get_bus, sd_bus_track_get_userdata, sd_bus_track_set_userdata — Track bus peers
sd_bus_track_new() creates a new bus peer tracking object. The object is allocated for
the specified bus, and returned in the
*ret parameter. After use, the object should be freed
again by dropping the acquired reference with
sd_bus_track_unref() (see below). A bus peer
tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of
one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as
long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers
have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to
specific bus peers are added via
sd_bus_track_add_sender(). They may be dropped again via
sd_bus_track_remove_sender(). Alternatively, references on peers are removed automatically
when they disconnect from the bus. If non-NULL the
handler may specify a function that is
invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via
sd_bus_track_remove_name() or implicitly because the peer disconnected from the bus. The final
userdata may be used to attach a generic user data pointer to the object. This
pointer is passed to the handler callback when it is invoked.
sd_bus_track_ref() creates a new reference to a bus peer tracking object. This object
will not be destroyed until
sd_bus_track_unref() has been called as many times plus once
more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to
sd_bus_track_unref() on the same object are
sd_bus_track_unref() destroys a reference to a bus peer tracking object.
sd_bus_track_unrefp() is similar to
sd_bus_track_unref() but takes
a pointer to a pointer to an sd_bus_track 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.
sd_bus_track_unrefp() execute no operation if the passed in bus peer tracking object is
Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may
optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked
or not tracked. In this mode invoking
sd_bus_track_add_name() multiple times in a row for the
same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if
necessary, and executes no operation if the peer is already being tracked. A single invocation of
sd_bus_track_remove_name() removes the reference on the peer again, regardless how many times
sd_bus_track_add_name() was called before. If operating in recursive mode, the number of times
sd_bus_track_add_name() is invoked for the same peer name is counted and
sd_bus_track_remove_name() must be called the same number of times before the peer is not
tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is
irrelevant and the tracking of the specific peer is immediately
sd_bus_track_get_recursive() may be used to determine whether the bus peer tracking
object is operating in recursive mode.
sd_bus_track_set_recursive() may be used to enable or
disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and
sd_bus_track_get_recursive() for a newly allocated object hence returns a value equal to
sd_bus_track_set_recursive() to enable recursive mode, right after allocation. It
takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which
sd_bus_track_add_name() was already invoked at least once (and which hence track already one
or more peers) may not be switched from recursive to non-recursive mode anymore.
sd_bus_track_get_bus() returns the bus object the bus peer tracking object belongs
to. It returns the bus object initially passed to
sd_bus_track_new() when the object was
sd_bus_track_get_userdata() returns the generic user data pointer set on the bus peer
tracking object at the time of creation using
sd_bus_track_new() or at a later time, using
return 0 or a positive integer. On failure, they return a negative errno-style error code.
sd_bus_track_ref() always returns the argument.
sd_bus_track_unref() always returns
sd_bus_track_get_recursive() returns 0 if non-recursive mode is selected (default), and
greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.
sd_bus_track_get_bus() returns the bus object associated to the bus peer tracking
sd_bus_track_get_userdata() returns the generic user data pointer associated with the
bus peer tracking object.
sd_bus_track_set_userdata() returns the previous user data pointer
sd_bus_track_new() function creates a new object and the caller owns the sole
reference. When not needed anymore, this reference should be destroyed with
Returned errors may indicate the following problems:
sd_bus_track_new() and the other calls described here are available as a shared library,
which can be compiled and linked to with the
libsystemd pkg-config(1) file.