Documentation
¶
Overview ¶
Package task contains types that can be used to create cancelable tasks.
Index ¶
- func Async(ctx context.Context, t Task) (stop func() error)
- func IgnoreCancellation(ctx context.Context) context.Context
- func NewSignal() (Signal, Task)
- func Poll(ctx context.Context, i time.Duration, f func(context.Context) error) error
- func Pool(queue int, parallel int) (Executor, Task)
- func Prepare(ctx context.Context, task Task) (Handle, Runner)
- func Retry(ctx context.Context, maxAttempts int, retryDelay time.Duration, ...) error
- func ShouldStop(ctx context.Context) <-chan struct{}
- func StopReason(ctx context.Context) error
- func Stopped(ctx context.Context) bool
- type Baton
- type CancelFunc
- type Event
- type Events
- type Executor
- type ExecutorFactory
- type Handle
- type Runner
- type Signal
- type Task
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Async ¶
Async runs the task t on a new go-routine, retuning a function that cancels the task's context, and blocks until the task completes.
func IgnoreCancellation ¶
IgnoreCancellation returns a context that will pretend to never be canceled.
func NewSignal ¶
NewSignal builds a new signal, and then returns the signal and a Task that is used to fire the signal. The returned fire Task must only be called once.
func Poll ¶
Poll blocks, calling f at regular intervals of i until the context is cancelled or f returns an error.
func Pool ¶
Pool returns a new Executor that uses a pool of goroutines to run the tasks, and a Task that shuts down the pool. The number of goroutines in the pool is controlled by parallel, and it must be greater than 0. The length of the submission queue is controlled by queue. It may be 0, in which case the executor will block until a goroutine is ready to accept the task. It will also block if the queue fills up. The shutdown task may only be called once, and it is an error to call the executor again after the shutdown task has run.
func Prepare ¶
Prepare is used to build a new Signal,Runner pair for a Task. The Signal will be closed when the task completes. The same task can be passed to Run multiple times, and will build a new Signal, Runner pair each time, but the returned runner should be executed exactly once, which will run the Task. In general this method is only used by Executor implementations when scheduling new tasks.
func Retry ¶
func Retry(ctx context.Context, maxAttempts int, retryDelay time.Duration, f func(context.Context) (done bool, err error)) error
Retry repeatedly calls f until f returns a true, the number of attempts reaches maxAttempts or the context is cancelled. Retry will sleep for retryDelay between retry attempts. if maxAttempts <= 0, then there is no maximum limit to the number of times f will be called.
func ShouldStop ¶
ShouldStop returns a chan that's closed when work done on behalf of this context should be stopped. See context.Context.Done for more details.
func StopReason ¶
StopReason returns a non-nil error value after Done is closed. See context.Context.Err for more details.
Types ¶
type Baton ¶
type Baton chan interface{}
Baton implements a task interlock. A baton must be owned by exactly 1 task at any given time, so a release blocks until a corresponding acquire occurs. You can pass a value through the baton from the release to the acquire.
func NewBaton ¶
func NewBaton() Baton
NewBaton returns a new Baton, with the expectation that the calling goroutine owns the baton.
func (Baton) Acquire ¶
func (b Baton) Acquire() interface{}
Acquire is a request to pick up the baton, it will block until another goroutine releases it. It returns the value passed to the release that triggers it.
func (Baton) Relay ¶
func (b Baton) Relay()
Relay is a helper that does an Acquire followed by a Release with the value that came from the Acquire. This waits for the baton to be available, and then immediately passes back, used as a signalling gate.
func (Baton) Release ¶
func (b Baton) Release(value interface{})
Release is a request to relinquish the baton, it will block until another goroutine acquires it. The supplied value is returned from the Acquire this release triggers.
func (Baton) TryAcquire ¶
TryAcquire is a request to pick up the baton, it will block until another goroutine releases it or timeout passes. It will return the released value and true if the baton was successfully acquired.
func (Baton) TryRelease ¶
TryRelease is a request to relinquish the baton, it will block until another goroutine acquires it or timeout passes. It will return true if the baton was successfully released.
type CancelFunc ¶
type CancelFunc context.CancelFunc
CancelFunc is a function type that can be used to stop a context.
func WithCancel ¶
func WithCancel(ctx context.Context) (context.Context, CancelFunc)
WithCancel returns a copy of ctx with a new Done channel. See context.WithCancel for more details.
func WithDeadline ¶
WithDeadline returns a copy of ctx with the deadline adjusted to be no later than deadline. See context.WithDeadline for more details.
func WithTimeout ¶
WithTimeout is shorthand for ctx.WithDeadline(time.Now().Add(duration)). See context.Context.WithTimeout for more details.
type Event ¶
type Event interface {
// Fired returns true if Wait would not block.
Fired() bool
// Wait blocks until the signal has been fired or the context has been
// cancelled.
// Returns true if the signal was fired, false if the context was cancelled.
Wait(ctx context.Context) bool
// TryWait waits for the signal to fire, the context to be cancelled or the
// timeout, whichever comes first.
TryWait(ctx context.Context, timeout time.Duration) bool
}
Event is the interface to things that can be used to wait for conditions to occur.
type Events ¶
type Events struct {
// contains filtered or unexported fields
}
Events is a thread safe list of Event entries. It can be used to collect a list of events so you can Wait for them all to complete. The list of events may be purged of already completed entries at any time, this is an invisible optimization to the semantics of the API.
func (*Events) Join ¶
Join the current list of events into a signal you can wait on. Subsequent calls to Add will not affect the returned signal.
type Executor ¶
Executor is the signature for a function that executes a Task. When the task is invoked depends on the specific Executor. The returned handle can be used to wait for the task to complete and collect it's error return value.
type ExecutorFactory ¶
ExecutorFactory returns an executor for the specified channel id, and a Task to shut the executor down again. The Task may be nil for executors that don't need to be shutdown.
func CachedExecutorFactory ¶
func CachedExecutorFactory(ctx context.Context, factory ExecutorFactory) ExecutorFactory
CachedExecutorFactory builds an ExecutorFactory that makes new executors on demand using the underlying factory. It guarantees that all concurrent tasks delivered to the same id go to the same Executor, but it will drop executors that have no active tasks any more.
func PoolExecutorFactory ¶
func PoolExecutorFactory(ctx context.Context, queue int, parallel int) ExecutorFactory
PoolExecutorFactory builds an ExecutorFactory that makes a new Pool executor each time it is invoked. The returned ExecutorFactory ignores the channel id.
type Handle ¶
type Handle struct {
Signal
// contains filtered or unexported fields
}
Handle is a reference to a running task submitted to an executor. It can be used to check if the task has completed and get it's error result if it has one.
func Direct ¶
Direct is a synchronous implementation of an Executor that runs the task before returning. In general it is easier to just invoke the task directly, so this is only used in cases where you want to hand the Exectuor to something that is agnostic about how tasks are scheduled.
type Runner ¶
type Runner func()
Runner is the type for a task that has been prepared to run by an executor. Invoking the runner will execute the underlying task, and trigger the signal when it completes.
type Signal ¶
type Signal <-chan struct{}
Signal is used to notify that a task has completed. Nothing is ever sent through a signal, it is closed to indicate signalled.
var FiredSignal Signal
FiredSignal is a signal that is always in the fired state.
type Task ¶
Task is the unit of work used in the task system. Tasks should generally be reentrant, they may be run more than once in more than one executor, and should generally be agnostic as to whether they are run in parallel.
Source Files