From a04b84778871d77e539a675acbff05f7220e2f5e Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 19 Dec 2016 13:45:53 -0500 Subject: Improve documentation. --- sd_daemon/booted.go | 4 ++-- sd_daemon/doc.go | 2 +- sd_daemon/log.go | 39 +++++++++++++++++++++++---------------- sd_daemon/log_test.go | 12 ++++++------ sd_daemon/log_util.go.gen | 8 ++++---- sd_daemon/lsb/exit-status.go | 2 +- sd_daemon/notify.go | 9 +++++---- sd_daemon/watchdog.go | 11 +++++------ 8 files changed, 47 insertions(+), 40 deletions(-) diff --git a/sd_daemon/booted.go b/sd_daemon/booted.go index bfbc685..b833b45 100644 --- a/sd_daemon/booted.go +++ b/sd_daemon/booted.go @@ -17,11 +17,11 @@ package sd_daemon import "os" -// Returns whether the operating system booted using the Systemd init +// Returns whether the operating system booted using the systemd init // system. // // Please do not use this function. All of the other functionality in -// this package uses interfaces that are not Systemd-specific. +// this package uses interfaces that are not systemd-specific. func SdBooted() bool { fi, err := os.Lstat("/run/systemd/system") return err != nil && fi.IsDir() diff --git a/sd_daemon/doc.go b/sd_daemon/doc.go index 8f1fb00..90616f6 100644 --- a/sd_daemon/doc.go +++ b/sd_daemon/doc.go @@ -21,7 +21,7 @@ // be much simpler; modern versions of the daemon(7) page on GNU/Linux // systems also describe "new-style" daemons. Though many of the // mechanisms described there and implemented here originated with -// Systemd, they are all very simple mechanisms which can easily be +// systemd, they are all very simple mechanisms which can easily be // implemented with a variety of service managers. // // [daemon(7)]: https://www.freedesktop.org/software/systemd/man/daemon.html diff --git a/sd_daemon/log.go b/sd_daemon/log.go index 9fa62d4..9b23f31 100644 --- a/sd_daemon/log.go +++ b/sd_daemon/log.go @@ -25,14 +25,21 @@ import ( "sync" ) -// Logger writes ""-prefixed lines to an io.Writer, where N is a +// A Logger writes ""-prefixed lines to an io.Writer, where N is a // syslog priority number. It implements mostly the same interface as -// "log/syslog".Writer. +// syslog.Writer. // // You probably don't need any instance of this other than the // constant "Log", which uses os.Stderr as the writer. It is // implemented as a struct rather than a set of functions so that it // can be passed around as an implementation of an interface. +// +// Each logging operation makes a single call to the underlying +// Writer's Write method. A single logging operation may be multiple +// lines; each line will have the prefix, and they will all be written +// in the same Write. A Logger can be used simultaneously from +// multiple goroutines; it guarantees to serialize access to the +// Writer. type Logger struct { mu sync.Mutex out io.Writer @@ -44,9 +51,9 @@ func NewLogger(w io.Writer) *Logger { return &Logger{out: w} } -// Log is a Logger that use used very similarly to -// "log/syslog".Writer, but writes to os.Stderr under the assumption -// that stderr is forwarded to syslog/journald. +// Log is a Logger whose interface is very similar to syslog.Writer, +// but writes to os.Stderr under the assumption that stderr is +// forwarded to syslog (or journald). // // You are encouraged to use stderr unless you have a good reason to // talk to syslog or journald directly. @@ -56,7 +63,7 @@ var Log = NewLogger(os.Stderr) // // *buf = append(*buf, fmt.Sprintf("<%d>", n)...) func appendPrefix(buf []byte, n syslog.Priority) []byte { - var b [22]byte // 21 = ceil(log_10(2^64))+len("<>") + var b [22]byte // 22 = ceil(log_10(2^64))+len("<>") b[len(b)-1] = '>' i := len(b) - 2 for n >= 10 { @@ -72,7 +79,7 @@ func appendPrefix(buf []byte, n syslog.Priority) []byte { // WriteString writes a message with the specified priority to the // log. -func (l *Logger) WriteString(level syslog.Priority, msg string) (n int, err error) { +func (l *Logger) WriteString(pri syslog.Priority, msg string) (n int, err error) { l.mu.Lock() defer l.mu.Unlock() @@ -80,12 +87,12 @@ func (l *Logger) WriteString(level syslog.Priority, msg string) (n int, err erro // The following is a cheap version of: // - // prefix := fmt.Sprintf("<%d>", level) + // prefix := fmt.Sprintf("<%d>", pri) // buf := prefix + strings.Replace(msg, "\n", "\n"+prefix, -1) // return io.WriteString(l.out, buf) l.buf = l.buf[:0] - l.buf = appendPrefix(l.buf, level) // possible allocation + l.buf = appendPrefix(l.buf, pri) // possible allocation prefix := l.buf nlines := strings.Count(msg, "\n") + 1 n = len(msg) + len(prefix)*nlines + 1 @@ -109,7 +116,7 @@ func (l *Logger) WriteString(level syslog.Priority, msg string) (n int, err erro // WriteString writes a message with the specified priority to the // log. -func (l *Logger) WriteBytes(level syslog.Priority, msg []byte) (n int, err error) { +func (l *Logger) WriteBytes(pri syslog.Priority, msg []byte) (n int, err error) { // Copy/pasted from WriteString and // * `strings.` -> `bytes.` // * `"\n"` -> `[]byte{'\n'}` @@ -119,7 +126,7 @@ func (l *Logger) WriteBytes(level syslog.Priority, msg []byte) (n int, err error msg = bytes.TrimSuffix(msg, []byte{'\n'}) l.buf = l.buf[:0] - l.buf = appendPrefix(l.buf, level) // possible allocation + l.buf = appendPrefix(l.buf, pri) // possible allocation prefix := l.buf nlines := bytes.Count(msg, []byte{'\n'}) + 1 n = len(msg) + len(prefix)*nlines + 1 @@ -142,16 +149,16 @@ func (l *Logger) WriteBytes(level syslog.Priority, msg []byte) (n int, err error } type loggerWriter struct { - log *Logger - level syslog.Priority + log *Logger + pri syslog.Priority } func (lw loggerWriter) Write(p []byte) (n int, err error) { - return lw.log.WriteBytes(lw.level, p) + return lw.log.WriteBytes(lw.pri, p) } // Writer returns an io.Writer that writes messages with the specified // priority to the log. -func (l *Logger) Writer(level syslog.Priority) io.Writer { - return loggerWriter{log: l, level: level} +func (l *Logger) Writer(pri syslog.Priority) io.Writer { + return loggerWriter{log: l, pri: pri} } diff --git a/sd_daemon/log_test.go b/sd_daemon/log_test.go index e2fdef9..257ccb9 100644 --- a/sd_daemon/log_test.go +++ b/sd_daemon/log_test.go @@ -33,8 +33,8 @@ func TestLog(t *testing.T) { })) type testcase struct { - level syslog.Priority - msg string + pri syslog.Priority + msg string } testcases := map[testcase]string{ @@ -52,18 +52,18 @@ func TestLog(t *testing.T) { for in, out := range testcases { written = nil - n, err := log.WriteString(in.level, in.msg) + n, err := log.WriteString(in.pri, in.msg) if n != len(out) || string(written) != out || err != nil { t.Errorf("WriteString(%#v, %#v)\n -> expected:{%#v, %#v, %#v}\n -> got:{%#v, %#v, %#v}\n", - in.level, in.msg, + in.pri, in.msg, len(out), nil, out, n, err, string(written)) } written = nil - n, err = log.WriteBytes(in.level, []byte(in.msg)) + n, err = log.WriteBytes(in.pri, []byte(in.msg)) if n != len(out) || string(written) != out || err != nil { t.Errorf("WriteBytes(%#v, %#v)\n -> expected:{%#v, %#v, %#v}\n -> got:{%#v, %#v, %#v}\n", - in.level, in.msg, + in.pri, in.msg, len(out), nil, out, n, err, string(written)) } diff --git a/sd_daemon/log_util.go.gen b/sd_daemon/log_util.go.gen index 95d56b0..3ca63dc 100755 --- a/sd_daemon/log_util.go.gen +++ b/sd_daemon/log_util.go.gen @@ -24,11 +24,11 @@ import "log/syslog" EOF - for level in Emerg Alert Crit Err Warning Notice Info Debug; do + for pri in Emerg Alert Crit Err Warning Notice Info Debug; do cat <