ctxgroup

README

ContextGroup

• Godoc: https://godoc.org/github.com/jbenet/go-ctxgroup

ContextGroup is an interface for services able to be opened and closed. It has a parent Context, and Children. But ContextGroup is not a proper "tree" like the Context tree. It is more like a Context-WaitGroup hybrid. It models a main object with a few children objects -- and, unlike the context -- concerns itself with the parent-child closing semantics:

• Can define an optional TeardownFunc (func() error) to be run at Closetime.
• Children call Children().Add(1) to be waited upon
• Children can select on <-Closing() to know when they should shut down.
• Close() will wait until all children call Children().Done()
• <-Closed() signals when the service is completely closed.

ContextGroup can be embedded into the main object itself. In that case, the teardownFunc (if a member function) has to be set after the struct is intialized:

type service struct {
  ContextGroup
  net.Conn
}
func (s *service) close() error {
  return s.Conn.Close()
}
func newService(ctx context.Context, c net.Conn) *service {
  s := &service{c}
  s.ContextGroup = NewContextGroup(ctx, s.close)
  return s
}

Documentation

Overview

package ctxgroup provides the ContextGroup, a hybrid between the context.Context and sync.WaitGroup, which models process trees.

Index

• type ChildFunc
• type ContextGroup
  • func WithBackground() ContextGroup
  • func WithContext(ctx context.Context) ContextGroup
  • func WithContextAndTeardown(ctx context.Context, cf TeardownFunc) ContextGroup
  • func WithParent(p ContextGroup) ContextGroup
  • func WithTeardown(cf TeardownFunc) ContextGroup
• type TeardownFunc

Types

type ChildFunc

type ChildFunc func(parent ContextGroup)

ChildFunc is a function to register as a child. It will be automatically tracked.

type ContextGroup

type ContextGroup interface {

	// Context is the context of this ContextGroup. It is "sort of" a parent.
	Context() context.Context

	// SetTeardown assigns the teardown function.
	// It is called exactly _once_ when the ContextGroup is Closed.
	SetTeardown(tf TeardownFunc)

	// Children is a sync.Waitgroup for all children goroutines that should
	// shut down completely before this service is said to be "closed".
	// Follows the semantics of WaitGroup:
	//
	//  Children().Add(1) // add one more dependent child
	//  Children().Done() // child signals it is done
	//
	// WARNING: this is deprecated and will go away soon.
	Children() *sync.WaitGroup

	// AddChild gives ownership of a child io.Closer. The child will be closed
	// when the context group is closed.
	AddChild(io.Closer)

	// AddChildFunc registers a dependent ChildFund. The child will receive
	// its parent ContextGroup, and can wait on its signals. Child references
	// tracked automatically. It equivalent to the following:
	//
	//  go func(parent, child ContextGroup) {
	//
	//  	<-parent.Closing()       // wait until parent is closing
	//  	child.Close()            // signal child to close
	//  	parent.Children().Done() // child signals it is done
	//	}(a, b)
	//
	AddChildFunc(c ChildFunc)

	// Close is a method to call when you wish to stop this ContextGroup
	Close() error

	// Closing is a signal to wait upon, like Context.Done().
	// It fires when the object should be closing (but hasn't yet fully closed).
	// The primary use case is for child goroutines who need to know when
	// they should shut down. (equivalent to Context().Done())
	Closing() <-chan struct{}

	// Closed is a method to wait upon, like Context.Done().
	// It fires when the entire object is fully closed.
	// The primary use case is for external listeners who need to know when
	// this object is completly done, and all its children closed.
	Closed() <-chan struct{}
}

ContextGroup is an interface for services able to be opened and closed. It has a parent Context, and Children. But ContextGroup is not a proper "tree" like the Context tree. It is more like a Context-WaitGroup hybrid. It models a main object with a few children objects -- and, unlike the context -- concerns itself with the parent-child closing semantics:

- Can define an optional TeardownFunc (func() error) to be run at Close time. - Children call Children().Add(1) to be waited upon - Children can select on <-Closing() to know when they should shut down. - Close() will wait until all children call Children().Done() - <-Closed() signals when the service is completely closed.

ContextGroup can be embedded into the main object itself. In that case, the teardownFunc (if a member function) has to be set after the struct is intialized:

type service struct {
	ContextGroup
	net.Conn
}

func (s *service) close() error {
	return s.Conn.Close()
}

func newService(ctx context.Context, c net.Conn) *service {
	s := &service{c}
	s.ContextGroup = NewContextGroup(ctx, s.close)
	return s
}

func WithBackground

func WithBackground() ContextGroup

WithBackground returns a ContextGroup with context.Background()

func WithContext

func WithContext(ctx context.Context) ContextGroup

WithContext constructs and returns a ContextGroup with given context

func WithContextAndTeardown

func WithContextAndTeardown(ctx context.Context, cf TeardownFunc) ContextGroup

WithContextAndTeardown constructs and returns a ContextGroup with cf TeardownFunc (and context.Background)

func WithParent

func WithParent(p ContextGroup) ContextGroup

WithParent constructs and returns a ContextGroup with given parent

func WithTeardown

func WithTeardown(cf TeardownFunc) ContextGroup

WithTeardown constructs and returns a ContextGroup with cf TeardownFunc (and context.Background)

type TeardownFunc

type TeardownFunc func() error

TeardownFunc is a function used to cleanup state at the end of the lifecycle of a process.