ctxgroup

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 10, 2015 License: MIT Imports: 3 Imported by: 0

README

ContextGroup

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL