danawoodman / overseer

Simple process manager written in Go-lang

Overseer

Simple process manager library.

• Note: The master branch is the development branch. To make sure you use the correct version, use the repository tags.

At the heart of this library is the os/exec.Cmd from Go-lang and the first wrapper for that is the Cmd struct.
The Overseer struct can supervise one or more Cmds running at the same time.
You can safely run multiple Overseer instances at the same time.

It's recommended to use Overseer, instead of Cmd directly.
If you use Cmd directly, keep in mind that it is one use only. After starting a instance, it cannot be started again. However, you can Clone your instance and start the clone.
The Supervise method from the Overseer does all of that for you.

There are 3 states in the normal lifecycle of a proc: starting, running, finished.
If the process is killed prematurely, the states are: starting, running, interrupted.
If the process cannot start, the states are: starting, fatal.

The useful methods are:

• NewOverseer() - Returns a new instance of a process manager.
• Add(id string, exec string, args ...interface{}) - Register a proc, without starting it. The id must be unique. The name of the executable is exec. The args of the executable are args.
• Remove(id string) - Unregister a proc, only if it's not running. The id must be unique.
• SuperviseAll() - This is the main function. Supervise all processes and block until they finish. This includes killing all the processes when the main program exits. The status of the running processes can be watched live with the Watch() function.
• Supervise(id string) - Supervise one registered process and block until it finishes. This includes checking if the process was killed from the outside, delaying the start and restarting in case of failure (failure means the program has an exit code != 0 or it ran with errors).
• Watch(outputChan chan *ProcessJSON) - Subscribe to all state changes via the provided output channel. The channel will receive status changes for all the added procs, but you can easily identify the one your are interested in from the ID, Group, etc. Note that for each proc you will receive only 2 or 3 messages that represent all the possible states (eg: starting, running, finished).
• Unwatch(outputChan chan *ProcessJSON) - Un-subscribe from the state changes, by un-registering the channel.
• Stop(id string) - Stops the process by sending its process group a SIGTERM signal.
• Signal(id string, sig syscall.Signal) - Sends an OS signal to the process group.
• StopAll() - Cycles and stops all processes by sending SIGTERM.

Highlights:

• real-time status
• real-time stdout and stderr
• complete and consolidated return
• easy to track process state
• proper process termination on program exit
• portable command line binary for managing procs
• heavily tested, very good test coverage
• no race conditions

For examples of usage, please check the Examples folder, the manager tests, or the command line app.

Similar libraries

• https://github.com/go-cmd/cmd - os/exec.Cmd with concurrent-safe access, real-time streaming output and complete runtime/return status. Overseer is based off this one.
• https://github.com/immortal/immortal - A *nix cross-platform (OS agnostic) supervisor. The real deal.
• https://github.com/ochinchina/supervisord - A Golang supervisor implementation, inspired by Python supervisord.
• https://github.com/DarthSim/hivemind - Process manager for Procfile-based applications.

Icon is made by Freepik from www.flaticon.com and licensed by CC 3.0 BY.

---

License

MIT © Cristi Constantin.