closer

type CloseFunc func() error

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 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 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_()

	// 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 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

	// 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)

	// CloseOnContextDone closes the closer if the context is done.
	CloseOnContextDone(context.Context)

	// 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{}

	// 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{}

	// IsClosing returns a boolean indicating
	// whether this instance is about to close.
	// Also returns true, if IsClosed() returns true.
	IsClosing() bool

	// IsClosed returns a boolean indicating
	// whether this instance has been closed completely.
	IsClosed() 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

	// CloserWait waits for the closer to close and returns the CloserError if present.
	// Use the context to cancel the blocking wait.
	CloserWait(ctx context.Context) error

	// CloserWaitChan extends CloserWait by returning an error channel.
	// If the context is canceled, the context error will be send over the channel.
	CloserWaitChan(ctx context.Context) <-chan error

	// BlockCloser ensures that during the function execution, the closer will not reach the
	// closed state. This is handled by calling CloserAddWait.
	// This call will return ErrClosed, if the closer is already closed.
	// This method can be used to free C memory during OnClose and ensures,
	// that pointers are not used after beeing freed.
	BlockCloser(f func() error) error

	// RunCloserRoutine starts a closer goroutine:
	// - call CloserAddWait
	// - start a new goroutine
	// - wait for the routine function to return
	// - handle the error and close the closer by calling CloseWithErrAndDone
	RunCloserRoutine(f func() error)
}