README
¶
bark
a golang watchdog for fast detection and restart of child processes
summary
Watch a child process and get notified immediately upon status change (such as termination). Remedies deficiency in the Go stdlib.
relevant inspiration:
a) detection of child process failure on OSX using the golang stdlib os.Process.Wait can take 30 seconds. Ouch.
b) Ian Lance Taylor suggested a Wait4 approach in this thread, and Igor Bukanov indicates it worked well for his use case; I confirm here that response is rapid.
what bark provides
The bark library provides the ability to monitor a child process, to automatically restart it if it fails, and to shut it down (SIGKILL or kill -9) upon request.
Simple and fast.
use / example
import (
"github.com/betable/bark"
)
...
watcher := NewWatchdog(nil, "/path/to/child/executable")
watcher.Start() // launchs proc, automatically restarts it
// give it a second to get started
time.Sleep(2 * time.Millisecond)
// current Process ID is available here; if 0 then
// it is between restarts and you should poll again.
pid := <-watcher.CurrentPid
// ready to stop both child and watchdog
watcher.TermChildAndStopWatchdog <- true
// wait for shutdown of child and watchdog to complete
<-watcher.Done
fmt.Print("watchdog and child pid shutdown.\n")
...
rarely needed
Also available, the ReqStopWatchdog channel will shutdown only the watchdog, and leave the child process unmonitored:
watcher.ReqStopWatchdog <- true
Copyright (c) 2016 Betable.com and Rubicon Media, LLC.
License: Apache 2.0
Documentation
¶
Index ¶
- Variables
- func DarwinOpenFiles(pid int) []string
- func DarwinPs() *map[int]bool
- func DirExists(name string) bool
- func FileExists(name string) bool
- func FileSize(name string) (int64, error)
- func IsNumberString(s string) bool
- func LinuxOpenFiles(pid int) []string
- func LinuxPs() *map[int]bool
- func OneshotAndWait(pathToProcess string, timeOut time.Duration, args ...string) (int, error)
- func OpenFiles(pid int) []string
- func P(format string, stuff ...interface{})
- func ProcessTable() *map[int]bool
- func Q(quietly_ignored ...interface{})
- func SetDiff(a, b []string) []string
- func ShowStrings(s []string)
- func TSPrintf(format string, a ...interface{})
- func VPrintf(format string, a ...interface{})
- func WPrintf(format string, a ...interface{})
- func WaitForShutdownWithTimeout(pid int, timeout time.Duration) error
- type Watchdog
- func NewOneshotReaper(attr *os.ProcAttr, pathToChildExecutable string, args ...string) *Watchdog
- func NewWatchdog(attr *os.ProcAttr, pathToChildExecutable string, args ...string) *Watchdog
- func Oneshot(pathToProcess string, args ...string) (*Watchdog, error)
- func StartAndWatch(pathToProcess string, args ...string) (*Watchdog, error)
Constants ¶
This section is empty.
Variables ¶
var Sysname string
var TimedOut = errors.New("TimedOut")
var V = VPrintf
var Verbose bool // set to true to debug
var W = WPrintf
var Working bool // currently under investigation
Functions ¶
func DarwinOpenFiles ¶
func FileExists ¶
func IsNumberString ¶
func LinuxOpenFiles ¶
func OneshotAndWait ¶
OneshotAndWait runs the command pathToProcess with the given args, and returns the exit code of the process. You may need to divide the exit code by 256 to get what you expect, at least on OSX.
With timeOut of 0 we wait forever and return the exitcode and an error of nil. Otherwise we return 0 and the TimedOut error if we timed-out waiting for the child process to finish.
func ProcessTable ¶
func ShowStrings ¶
func ShowStrings(s []string)
Types ¶
type Watchdog ¶
type Watchdog struct {
Ready chan bool
RestartChild chan bool
ReqStopWatchdog chan bool
TermChildAndStopWatchdog chan bool
Done chan bool
CurrentPid chan int
StopWatchdogAfterChildExits chan bool
ExitCode int
PathToChildExecutable string
Args []string
Attr os.ProcAttr
// contains filtered or unexported fields
}
func NewOneshotReaper ¶
NewOneshotReaper() is just like NewWatchdog, except that it also does two things:
a) sets a flag so that the watchdog won't restart the child process after it finishes.
and
b) the watchdog goroutine will itself exit once the child exists--after cleaning up. Cleanup means we don't leave zombies and we call go's os.Process.Release() to release associated resources after the child exits.
You still need to call Start(), just like after NewWatchdog().
func NewWatchdog ¶
NewWatchdog creates a Watchdog structure but does not launch it or its child process until Start() is called on it. The attr argument sets function attributes such as environment and open files; see os.ProcAttr for details. Also, attr can be nil here, in which case and empty os.ProcAttr will be supplied to the os.StartProcess() call.
func Oneshot ¶
Oneshot() combines NewOneshotReaper() and Start(). In other words, we start the child once. We don't restart once it finishes. Instead we just reap and cleanup. The returned pointer's Done channel will be closed when the child process and watchdog goroutine have finished.
func StartAndWatch ¶
StartAndWatch() is the convenience/main entry API. pathToProcess should give the path to the executable within the filesystem. If it dies it will be restarted by the Watchdog.
Source Files
Directories