README
¶
Closer - A simple, thread-safe closer
This package aims to provide a simple and performance oriented mechanism to manage the graceful and reliable shutdown of an application, or parts of it.
It can also be a handy alternative to the context package, though it does not solve the problem that common go libraries only accept context as a valid cancellation method. Therefore, you are only able to cancel "in-between" slow operations.
Examples
Check out the sample program for a good overview of this package's functionality.
Let us assume you want a server that should close its connection once it gets closed. We close the connection in the onClose() method of the server's closer and demonstrate that it does not matter how often you call Close(), the connection is closed exactly once.
type Server struct {
closer.Closer // Embedded
conn net.Conn
}
func New() *Server {
// ...
s := &Server {
conn: conn,
}
s.Closer = closer.New(s.onClose)
return s
}
func (s *server) onClose() error {
return s.conn.Close()
}
func main() {
s := New()
// ...
// The s.onClose function will be called only once.
s.Close()
s.Close()
}
Now we want an application that (among other things) connects as a client to a remote server. In case the connection is interrupted, the app should continue to run and not fail. But if the app itself closes, of course we want to take down the client connection as well.
type App struct {
closer.Closer
}
func NewApp() *App {
return &App{
Closer: closer.New()
}
}
type Client struct {
closer.Closer
conn net.Conn
}
func NewClient(cl closer.Closer) *Client {
c := &Client{
Closer: cl,
}
c.OnClose(func() error {
return c.conn.Close()
})
return c
}
func main() {
a := NewApp()
// Close c, when a closes, but do not close a, when c closes.
c := NewClient(a.CloserOneWay())
c.Close()
// a still alive.
}
Of course, there is the opposite to the OneWay closer that closes its parent as well. If we take the example from before, we can simply exchange the closer that is passed to the client.
//...
func main() {
a := NewApp()
// Close c, when a closes, and close a, when c closes.
c := NewClient(a.CloserTwoWay())
c.Close()
// a has been closed.
}
Documentation
Check out godoc for the documentation.
Install
go get github.com/desertbit/closer
Contribution
We love contributions, so feel free to do so! Coding and contribution guide lines will come in the future. Simply file a new issue, if you encounter problems with this package or have feature requests.
Documentation
¶
Overview ¶
Package closer offers a simple, thread-safe closer.
It allows to build up a tree of closing relationships, where you typically start with a root closer that branches into different children and children's children. When a parent closer spawns a child closer, the child either has a one-way or two-way connection to its parent. One-way children are closed when their parent closes. In addition, two-way children also close their parent, if they are closed themselves.
A closer is also useful to ensure that certain dependencies, such as network connections, are reliably taken down, once the closer closes. In addition, a closer can be concurrently closed many times, without closing more than once, but still returning the errors to every caller.
This allows to represent complex closing relationships and helps avoiding leaking goroutines, gracefully shutting down, etc.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("closed")
ErrClosed is a generic error that indicates a resource has been closed.
Functions ¶
This section is empty.
Types ¶
type Closer ¶
type Closer interface {
// Close closes this closer in a thread-safe manner.
//
// Implements the io.Closer interface.
//
// This method always returns the close error,
// regardless of how often it gets called.
//
// The closing order looks like this:
// 1: the closing chan is closed.
// 2: the OnClosing funcs are executed.
// 3: each of the closer's children is closed.
// 4: it waits for the wait group.
// 5: the OnClose funcs are executed.
// 6: the closed chan is closed.
// 7: the parent is closed, if it has one.
//
// Close blocks, until step 6 of the closing order
// has been finished. A potential parent gets
// closed concurrently in a new goroutine.
//
// The returned error contains the joined errors of all closers that were part of
// the blocking closing order of this closer.
// This means that two-way closers do not report their parents' errors.
Close() error
// Close_ is a convenience version of Close(), for use in defer
// where the error is not of interest.
Close_()
// CloseWithErr closes the closer and appends the given error to its joined error.
CloseWithErr(err error)
// CloseWithErrAndDone performs the same operation as CloseWithErr(), but decrements
// the closer's wait group by one beforehand.
// Attention: Calling this without first adding to the WaitGroup by
// calling CloserAddWait results in a panic.
CloseWithErrAndDone(err error)
// CloseAndDone performs the same operation as Close(), but decrements
// the closer's wait group by one beforehand.
// Attention: Calling this without first adding to the WaitGroup by
// calling CloserAddWait() results in a panic.
CloseAndDone() error
// CloseAndDone_ is a convenience version of CloseAndDone(), for use in
// defer where the error is not of interest.
CloseAndDone_()
// ClosedChan returns a channel, which is closed as
// soon as the closer is completely closed.
// See Close() for the position in the closing order.
ClosedChan() <-chan struct{}
// CloserAddWait adds the given delta to the closer's
// wait group. Useful to wait for routines associated
// with this closer to gracefully shutdown.
// See Close() for the position in the closing order.
CloserAddWait(delta int)
// CloserDone decrements the closer's wait group by one.
// Attention: Calling this without first adding to the WaitGroup by
// calling CloserAddWait() results in a panic.
CloserDone()
// CloserOneWay creates a new child closer that has a one-way relationship
// with the current closer. This means that the child is closed whenever
// the parent closes, but not vice versa.
// See Close() for the position in the closing order.
CloserOneWay() Closer
// CloserTwoWay creates a new child closer that has a two-way relationship
// with the current closer. This means that the child is closed whenever
// the parent closes and vice versa.
// See Close() for the position in the closing order.
CloserTwoWay() Closer
// ClosingChan returns a channel, which is closed as
// soon as the closer is about to close.
// Remains closed, once ClosedChan() has also been closed.
// See Close() for the position in the closing order.
ClosingChan() <-chan struct{}
// Context returns a context.Context, which is cancelled
// as soon as the closer is closing.
// The returned cancel func should be called as soon as the
// context is no longer needed, to free resources.
Context() (context.Context, context.CancelFunc)
// IsClosed returns a boolean indicating
// whether this instance has been closed completely.
IsClosed() bool
// IsClosing returns a boolean indicating
// whether this instance is about to close.
// Also returns true, if IsClosed() returns true.
IsClosing() bool
// OnClose adds the given CloseFuncs to the closer.
// Their errors are joined with the closer's other errors.
// Close functions are called in LIFO order.
// See Close() for their position in the closing order.
OnClose(f ...CloseFunc)
// OnClosing adds the given CloseFuncs to the closer.
// Their errors are joined with the closer's other errors.
// Closing functions are called in LIFO order.
// It is guaranteed that all closing funcs are executed before
// any close funcs.
// See Close() for their position in the closing order.
OnClosing(f ...CloseFunc)
// CloserError returns the joined error of this closer once it has fully closed.
// If there was no error or the closer is not yet closed, nil is returned.
CloserError() error
}
A Closer is a thread-safe helper for common close actions.
Source Files
Directories