status-go/vendor/github.com/jbenet/goprocess

goprocess - lifecycles in go

(Based on https://github.com/jbenet/go-ctxgroup)

• Godoc: https://godoc.org/github.com/jbenet/goprocess

goprocess introduces a way to manage process lifecycles in go. It is much like go.net/context (it actually uses a Context), but it is more like a Context-WaitGroup hybrid. goprocess is about being able to start and stop units of work, which may receive Close signals from many clients. Think of it like a UNIX process tree, but inside go.

goprocess seeks to minimally affect your objects, so you can use it with both embedding or composition. At the heart of goprocess is the Process interface:

// Process is the basic unit of work in goprocess. It defines a computation
// with a lifecycle:
// - running (before calling Close),
// - closing (after calling Close at least once),
// - closed (after Close returns, and all teardown has _completed_).
//
// More specifically, it fits this:
//
//   p := WithTeardown(tf) // new process is created, it is now running.
//   p.AddChild(q)         // can register children **before** Closing.
//   go p.Close()          // blocks until done running teardown func.
//   <-p.Closing()         // would now return true.
//   <-p.childrenDone()    // wait on all children to be done
//   p.teardown()          // runs the user's teardown function tf.
//   p.Close()             // now returns, with error teardown returned.
//   <-p.Closed()          // would now return true.
//
// Processes can be arranged in a process "tree", where children are
// automatically Closed if their parents are closed. (Note, it is actually
// a Process DAG, children may have multiple parents). A process may also
// optionally wait for another to fully Close before beginning to Close.
// This makes it easy to ensure order of operations and proper sequential
// teardown of resurces. For example:
//
//   p1 := goprocess.WithTeardown(func() error {
//     fmt.Println("closing 1")
//   })
//   p2 := goprocess.WithTeardown(func() error {
//     fmt.Println("closing 2")
//   })
//   p3 := goprocess.WithTeardown(func() error {
//     fmt.Println("closing 3")
//   })
//
//   p1.AddChild(p2)
//   p2.AddChild(p3)
//
//
//   go p1.Close()
//   go p2.Close()
//   go p3.Close()
//
//   // Output:
//   // closing 3
//   // closing 2
//   // closing 1
//
// Process is modelled after the UNIX processes group idea, and heavily
// informed by sync.WaitGroup and go.net/context.Context.
//
// In the function documentation of this interface, `p` always refers to
// the self Process.
type Process interface {

  // WaitFor makes p wait for q before exiting. Thus, p will _always_ close
  // _after_ q. Note well: a waiting cycle is deadlock.
  //
  // If q is already Closed, WaitFor calls p.Close()
  // If p is already Closing or Closed, WaitFor panics. This is the same thing
  // as calling Add(1) _after_ calling Done() on a wait group. Calling WaitFor
  // on an already-closed process is a programming error likely due to bad
  // synchronization
  WaitFor(q Process)

  // AddChildNoWait registers child as a "child" of Process. As in UNIX,
  // when parent is Closed, child is Closed -- child may Close beforehand.
  // This is the equivalent of calling:
  //
  //  go func(parent, child Process) {
  //    <-parent.Closing()
  //    child.Close()
  //  }(p, q)
  //
  // Note: the naming of functions is `AddChildNoWait` and `AddChild` (instead
  // of `AddChild` and `AddChildWaitFor`) because:
  // - it is the more common operation,
  // - explicitness is helpful in the less common case (no waiting), and
  // - usual "child" semantics imply parent Processes should wait for children.
  AddChildNoWait(q Process)

  // AddChild is the equivalent of calling:
  //  parent.AddChildNoWait(q)
  //  parent.WaitFor(q)
  AddChild(q Process)

  // Go creates a new process, adds it as a child, and spawns the ProcessFunc f
  // in its own goroutine. It is equivalent to:
  //
  //   GoChild(p, f)
  //
  // It is useful to construct simple asynchronous workers, children of p.
  Go(f ProcessFunc) Process

  // Close ends the process. Close blocks until the process has completely
  // shut down, and any teardown has run _exactly once_. The returned error
  // is available indefinitely: calling Close twice returns the same error.
  // If the process has already been closed, Close returns immediately.
  Close() error

  // Closing is a signal to wait upon. The returned channel is closed
  // _after_ Close has been called at least once, but teardown may or may
  // not be done yet. The primary use case of Closing is for children who
  // need to know when a parent is shutting down, and therefore also shut
  // down.
  Closing() <-chan struct{}

  // Closed is a signal to wait upon. The returned channel is closed
  // _after_ Close has completed; teardown has finished. The primary use case
  // of Closed is waiting for a Process to Close without _causing_ the Close.
  Closed() <-chan struct{}
}