Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrAborted = errors.New("guard operation aborted")
ErrAborted is used to confirm clean termination of a blocking operation.
var ErrShutdown = errors.New("guard worker shutting down")
ErrShutdown is used to report that the guard worker is shutting down.
var ErrSkip = errors.Errorf("skip task execution")
ErrSkip will tell the occupy to skip task execution.
Functions ¶
This section is empty.
Types ¶
type Guard ¶
type Guard struct {
// contains filtered or unexported fields
}
Guard coordinates between clients that access it as a Guard and as a Guest.
func New ¶
func New() *Guard
New returns a new, locked, guard. The caller is responsible for ensuring it somehow gets Kill()ed, and for handling any error returned by Wait().
func (*Guard) Lock ¶
Lock blocks new visit calls, and waits for existing calls to complete; it will return ErrAborted if the supplied abort is closed before lock is complete. In this situation, the guard will remain closed to new visits, but may still be executing pre-existing ones; you need to wait for a lock to complete successfully before you can infer exclusive access.
type Guest ¶
type Guest interface {
// Visit waits until the guard is unlocked, then runs the supplied
// Visit func. It will return ErrAborted if the supplied Abort is closed
// before the Visit is started.
Visit(fn func(context.Context) error, abort <-chan struct{}) error
}
Guest allows clients to Visit a guard when it's unlocked; that is, to get non-exclusive access to whatever resource is being protected for the duration of the supplied Visit func.
type Task ¶
type Task interface {
// Wait waits for the Task to complete and returns any
// error encountered when it was running or stopping.
Wait() error
}
Task describes any type whose validity and/or activity is bounded in time. Most frequently, they will represent the duration of some task or tasks running on internal goroutines, but it's possible and rational to use them to represent any resource that might become invalid.
Task implementations must be goroutine-safe.
func Occupy ¶
Occupy launches a Visit to guard that creates a task and holds the visit open until the task completes. Like most funcs that return any task, the caller takes responsibility for its lifetime; be aware that the responsibility is especially heavy here, because failure to clean up the task will block cleanup of the guard.
This may sound scary, but the alternative is to have multiple components "responsible for" a single task's lifetime -- and guard itself would have to grow new concerns, of understanding and managing Tasks -- and that scenario ends up much worse.
Source Files