Module: SdNotify

Defined in:
lib/sd_notify.rb

Overview

SdNotify is a pure-Ruby implementation of sd_notify(3). It can be used to notify systemd about state changes. Methods of this package are no-op on non-systemd systems (eg. Darwin).

The API maps closely to the original implementation of sd_notify(3), therefore be sure to check the official man pages prior to using SdNotify.

See Also:

Defined Under Namespace

Classes: NotifyError

Constant Summary collapse

READY = 
"READY=1"
RELOADING = 
"RELOADING=1"
STOPPING = 
"STOPPING=1"
STATUS = 
"STATUS="
ERRNO = 
"ERRNO="
MAINPID = 
"MAINPID="
WATCHDOG = 
"WATCHDOG=1"
FDSTORE = 
"FDSTORE=1"

Class Method Summary collapse

Class Method Details

.errno(errno, unset_env = false) ⇒ Object

Parameters:

  • errno (Integer) 


43
44
45
 
# File 'lib/sd_notify.rb', line 43

def self.errno(errno, unset_env=false)
  notify("#{ERRNO}#{errno}", unset_env)
end

.fdstore(unset_env = false) ⇒ Object 



56
57
58
 
# File 'lib/sd_notify.rb', line 56

def self.fdstore(unset_env=false)
  notify(FDSTORE, unset_env)
end

.mainpid(pid, unset_env = false) ⇒ Object

Parameters:

  • pid (Integer) 


48
49
50
 
# File 'lib/sd_notify.rb', line 48

def self.mainpid(pid, unset_env=false)
  notify("#{MAINPID}#{pid}", unset_env)
end

.notify(state, unset_env = false) ⇒ Fixnum?

Notify systemd with the provided state, via the notification socket, if any.

Generally this method will be used indirectly through the other methods of the library.

Parameters:

  • state (String)
  • unset_env (Boolean) (defaults to: false)

Returns:

  • (Fixnum, nil) —

    the number of bytes written to the notification socket or nil if there was no socket to report to (eg. the program wasn’t started by systemd)

Raises:

  • (NotifyError) —

    if there was an error communicating with the systemd socket

See Also:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/sd_notify.rb', line 77

def self.notify(state, unset_env=false)
  sock = ENV["NOTIFY_SOCKET"]

  return nil if !sock

  ENV.delete("NOTIFY_SOCKET") if unset_env

  connected = false

  begin
    sock = Addrinfo.unix(sock, :DGRAM).connect
    connected = true
    sock.close_on_exec = true
    sock.write(state)
  rescue StandardError => e
    raise NotifyError, "#{e.class}: #{e.message}", e.backtrace
  ensure
    sock.close if connected
  end
end

.ready(unset_env = false) ⇒ Object 



24
25
26
 
# File 'lib/sd_notify.rb', line 24

def self.ready(unset_env=false)
  notify(READY, unset_env)
end

.reloading(unset_env = false) ⇒ Object 



28
29
30
 
# File 'lib/sd_notify.rb', line 28

def self.reloading(unset_env=false)
  notify(RELOADING, unset_env)
end

.status(status, unset_env = false) ⇒ Object

Parameters:

  • status (String) —

    a custom status string that describes the current state of the service



38
39
40
 
# File 'lib/sd_notify.rb', line 38

def self.status(status, unset_env=false)
  notify("#{STATUS}#{status}", unset_env)
end

.stopping(unset_env = false) ⇒ Object 



32
33
34
 
# File 'lib/sd_notify.rb', line 32

def self.stopping(unset_env=false)
  notify(STOPPING, unset_env)
end

.watchdog(unset_env = false) ⇒ Object 



52
53
54
 
# File 'lib/sd_notify.rb', line 52

def self.watchdog(unset_env=false)
  notify(WATCHDOG, unset_env)
end