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 ¶
This section is empty.
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 returns always the close error, regardless of how often
// it gets called. Close blocks, until all close functions are done,
// no matter which goroutine called this method.
// Returns a hashicorp multierror.
Close() 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 AddWaitGroup() results in a panic.
CloseAndDone() error
// ClosedChan returns a channel, which is closed as
// soon as the closer is completely closed.
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.
CloserAddWait(delta int)
// CloserDone decrements the closer's wait group by one.
// Attention: Calling this without first adding to the WaitGroup by
// calling AddWaitGroup() 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.
CloserOneWay(f ...CloseFunc) 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.
CloserTwoWay(f ...CloseFunc) 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.
ClosingChan() <-chan struct{}
// 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
// Calls the close function on close.
// Errors are appended to the Close() multi error.
// Close functions are called in LIFO order.
OnClose(f ...CloseFunc)
}
A Closer is a thread-safe helper for common close actions.
Source Files
Directories