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.
Source Files