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

	// CloseErr 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.
	CloseErr() error

	// AsyncClose closes the this closer without blocking.
	// Use this within Block() calls or Routines().
	AsyncClose()

	// AsyncCloseWithErr appends the given error to its joined error and calls AsyncClose.
	// If the closer is already closed, the error will be ignored. During the closing state errors can be appended.
	AsyncCloseWithErr(error)

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

type H interface {
	// OnClose same as OnCloseWithErr but without error.
	OnClose(f ...func())

	// OnClosing same as OnClosingWithErr but without error.
	OnClosing(f ...func())

	// OnCloseWithErr adds the given functions 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.
	OnCloseWithErr(f ...func() error)

	// OnClosingWithErr adds the given functions 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 within this hook scope are executed before
	// any close funcs.
	// See Close() for their position in the closing order.
	OnClosingWithErr(f ...func() error)
}