Documentation
¶
Overview ¶
Package systemd provides access to systemd via D-Bus using Unix domain sockets as a transport. The objective of this package is to list services with a low overhead for a caller.
Index ¶
Constants ¶
const ( // DefaultConnectionTimeout is the default // read/write timeout associated with the connection. DefaultConnectionTimeout = time.Second // DefaultConnectionReadSize is the default size (in bytes) // of the buffer which is used for reading from a connection. // Buffering reduces count of read syscalls, // e.g., ListUnits makes 12 read syscalls when decoding 35KB message // using 4KB buffer. // It takes over 4K syscalls without buffering to decode the same message. DefaultConnectionReadSize = 4096 // DefaultStringConverterSize is the default buffer size (in bytes) // of the string converter that is used to convert bytes to strings // with less allocs. // // After trying various buffer sizes on ListUnits, // a 4KB buffer showed 24.96 KB/op and 7 allocs/op // in a benchmark when decoding 35KB message. DefaultStringConverterSize = 4096 )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides access to systemd via dbus. A caller shouldn't use Client concurrently.
func New ¶
New creates a new Client to access systemd via dbus.
By default it connects to the system message bus using address found in DBUS_SYSTEM_BUS_ADDRESS environment variable. If that variable is not set, the Client will try to connect to the well-known address unix:path=/var/run/dbus/system_bus_socket, see https://dbus.freedesktop.org/doc/dbus-specification.html.
func (*Client) ListUnits ¶
ListUnits fetches systemd units, optionally filters them with a given predicate, and calls f. The pointer to Unit struct in f must not be retained, because its fields change on each f call.
Note, don't call any Client's methods within f, because concurrent reading from the same underlying connection is not supported.
func (*Client) MainPID ¶
MainPID fetches the main PID of the service. If a service is inactive (see Unit.ActiveState), the returned PID will be zero.
Note, you can't call this method within ListUnits's f func, because that would imply concurrent reading from the same underlying connection. Simply waiting on a lock won't help, because ListUnits won't be able to finish waiting for MainPID, thus creating a deadlock.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config represents a Client config.
type Option ¶
type Option func(*Config)
Option sets up a Config.
func WithAddress ¶ added in v0.17.0
WithAddress sets a bus address.
func WithConnectionReadSize ¶
WithConnectionReadSize sets a size of a buffer which is used for reading from a D-Bus connection. Bigger the buffer, less read syscalls will be made.
func WithSerialCheck ¶
func WithSerialCheck() Option
WithSerialCheck enables checking of message serials, i.e., the Client will compare the serial number sent within a message to D-Bus with the serial received in the reply.
Note, this requires decoding of header fields which incurs extra allocs. There shouldn't be any request/reply mishmash because the Client guarantees that the underlying D-Bus connection is accessed sequentially.
func WithStringConverterSize ¶
WithStringConverterSize sets a buffer size of the string converter to reduce allocs.
func WithTimeout ¶
WithTimeout sets the read and write timeouts associated with the connection.
type Predicate ¶
Predicate is used to filter out a decoded struct based on its field index and a value. This helps to reduce memory consumption because a decoder can ignore the remaining struct fields. For example, D-Bus ListUnits returns tens of kilobytes in a reply, but a caller is interested only in service units.
The field name would be more convenient to work with compared to a field index, but that causes unintended allocs.
type Unit ¶
type Unit struct {
// Name is the primary unit name.
Name string
// Description is the human readable description.
Description string
// LoadState is the load state, i.e., whether the unit file has been loaded successfully.
LoadState string
// ActiveState is the active state, i.e., whether the unit is currently started or not.
ActiveState string
// SubState is the sub state, i.e.,
// a more fine-grained version of the active state that
// is specific to the unit type, which the active state is not.
SubState string
// Followed is a unit that is being followed in its state by this unit,
// if there is any, otherwise the empty string.
Followed string
// Path is the unit object path.
Path string
// JobID is the numeric job ID
// if there is a job queued for the job unit, 0 otherwise.
JobID uint32
// JobType is the job type.
JobType string
// JobPath is the job object path.
JobPath string
}
Unit represents a currently loaded systemd unit. Note that units may be known by multiple names at the same name, and hence there might be more unit names loaded than actual units behind them.
Source Files