README
¶
tasks
This repository helps manage long or recurring tasks
This API is stable. Newly added API that is not yet stable will be clearly marked as draft API.
Using
import "github.com/keep94/tasks"
Documentation
¶
Overview ¶
Package tasks handles tasks that can be started and stopped
Index ¶
- func Run(task Task) error
- func RunForTesting(task Task, clock Clock) (err error)
- func SetTime(newTime time.Time)
- type Clock
- type ClockForTesting
- type Execution
- func (e *Execution) Done() <-chan struct{}
- func (e *Execution) End()
- func (e *Execution) Ended() <-chan struct{}
- func (e *Execution) Error() error
- func (e *Execution) IsDone() bool
- func (e *Execution) IsEnded() bool
- func (e *Execution) SetError(err error)
- func (e *Execution) Sleep(d time.Duration) bool
- func (e *Execution) Yield(sleepFunc func()) bool
- type FakeClock
- type MultiExecutor
- type SingleExecutor
- type Task
- type TaskCollection
- type TaskFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunForTesting ¶
RunForTesting work just like Run except it allows caller to specify an implementation of the Clock interface for testing.
func SetTime ¶
SetTime sets the time for the system implementation of Clock to some other time besides the actual system time. See SystemClock() function. SetTime needs to be called only to simulate a certain time for testing purposes. After, SetTime is called, the clock continues to advance at the normal rate from the new time. If SetTime is called, it should be called once at program startup. It is not safe to call after there are multiple goroutines. Note that SetTime does not change the system clock. Instead, it adds a fixed offset to achieve the new time.
Types ¶
type Clock ¶
type Clock interface {
// Now returns the current time
Now() time.Time
// After waits for given duration to elapse and then sends current time on
// the returned channel.
After(d time.Duration) <-chan time.Time
}
Clock represents the system clock.
func SystemClock ¶
func SystemClock() Clock
SystemClock returns the system implementation of the Clock interface.
type ClockForTesting ¶
ClockForTesting is a test implementation of Clock. Unlike the real clock, current time remains the same unless client changes it directly or calls After()
func (*ClockForTesting) After ¶
func (c *ClockForTesting) After(d time.Duration) <-chan time.Time
After immediately advances current time by d and sends that currnet time on the returned channel.
func (*ClockForTesting) Now ¶
func (c *ClockForTesting) Now() time.Time
type Execution ¶
type Execution struct {
Clock
// contains filtered or unexported fields
}
Execution represents a particular execution of some task. Execution instances are safe to use with multiple goroutines.
func Start ¶
Start starts a task in a separate goroutine and returns immediately. Start returns that particular execution of the task.
func (*Execution) Done ¶
func (e *Execution) Done() <-chan struct{}
Done returns a channel that gets closed when this execution is done.
func (*Execution) Ended ¶
func (e *Execution) Ended() <-chan struct{}
Ended returns a channel that gets closed when this execution is signaled to end.
func (*Execution) IsDone ¶
IsDone returns true if this execution is done or false if it is still in progress.
func (*Execution) Sleep ¶
Sleep sleeps for the specified duration or until this execution should end, whichever comes first. Sleep returns false if it returned early because this execution should end; otherwise it returns true. If paused, the sleep timer continues to run normally; however, after the sleep timer runs out, Sleep will continue to block until either this execution is signaled to end (in which case it returns false) or unpaused (in which case it returns true).
func (*Execution) Yield ¶
Yield runs sleepFunc and after that returns true unless this exeuction was signaled to end in which case it returns false. sleepFunc can be nil. If paused, sleepFunc continues to run uninterrupted; however, after sleepFunc returns, Yield will continue to block until either this execution is signaled to end (in which case it returns false) or unpaused (in which case it returns true).
type FakeClock ¶
type FakeClock struct {
// contains filtered or unexported fields
}
FakeClock is a test implementation of clock that is safe with multiple goroutines. This clock's time stays the same, unless moved forwared with the Advance method.
func NewFakeClock ¶
NewFakeClock creates a new FakeClock with a particular current time.
func (*FakeClock) Advance ¶
Advance moves the current time forward by d. Current time cannot be moved backward.
type MultiExecutor ¶
type MultiExecutor struct {
// contains filtered or unexported fields
}
MultiExecutor executes multiple tasks at one time while ensuring that no conflicting tasks execute in parallel. MultiExecutor is safe to use with multiple goroutines. Because of TaskCollection.Remove, tasks used with MultiExecutor must support equality. For instance, the underlying type used for Task could be a pointer type.
func NewMultiExecutor ¶
func NewMultiExecutor(tc TaskCollection) *MultiExecutor
NewMultiExecutor returns a new MultiExecutor. tc is the TaskCollection that will hold running tasks. tc shall be safe to use with multiple goroutines and each MultiExecutor shall have its own TaskCollection instance.
func NewMultiExecutorWithClock ¶
func NewMultiExecutorWithClock(tc TaskCollection, clock Clock) *MultiExecutor
NewMultiExecutorWithClock works just like NewMultiExecutor but creates a MultiExecutor that uses a clock that differs from the system clock.
func (*MultiExecutor) Close ¶
func (me *MultiExecutor) Close() error
Close frees the resources of this instance and always returns nil. Close interrupts any currently running tasks.
func (*MultiExecutor) Pause ¶
func (me *MultiExecutor) Pause()
Pause pauses this executor. Pause blocks until all running tasks in this executor have either ended or called Yield or Sleep on their Execution instance. Pause() and Resume() must be called from the same goroutine. Calling Pause() and Resume() concurrently from different goroutines causes undefined behavior and may cause Pause() to block indefinitely.
func (*MultiExecutor) Resume ¶
func (me *MultiExecutor) Resume()
Resume resumes this once paused executor by letting any in-progress tasks that had called Yield or Sleep on their Execution instance continue. Pause() and Resume() must be called from the same goroutine. Calling Pause() and Resume() concurrently from different goroutines causes undefined behavior and may cause Pause() to block indefinitely.
func (*MultiExecutor) Start ¶
func (me *MultiExecutor) Start(t Task) *Execution
Start starts task t and returns its Execution. Start blocks until this instance actually starts t. Start interrupts any currently running conflicting tasks before starting t.
func (*MultiExecutor) Tasks ¶
func (me *MultiExecutor) Tasks() TaskCollection
Tasks returns the running tasks.
type SingleExecutor ¶
type SingleExecutor MultiExecutor
SingleExecutor executes tasks one at a time. SingleExecutor instances are safe to use with multiple goroutines. Tasks used with SingleExecutor must support equality. For instance, the underlying type used for Task could be a pointer type. Clients should consider SingleExecutor and MultiExecutor using the same underlying type an implementation detail that could change in the future.
func NewSingleExecutor ¶
func NewSingleExecutor() *SingleExecutor
NewSingleExecutor returns a new SingleExecutor.
func (*SingleExecutor) Close ¶
func (se *SingleExecutor) Close() error
Close frees the resources of this instance and always returns nil. Close interrupts any currently running task.
func (*SingleExecutor) Current ¶
func (se *SingleExecutor) Current() (Task, *Execution)
Current returns the current running task and its execution. If no task is running, Current returns nil, nil.
func (*SingleExecutor) Pause ¶
func (se *SingleExecutor) Pause()
Pause pauses this executor. Pause blocks until all running tasks in this executor have either ended or called Yield or Sleep on their Execution instance. Pause() and Resume() must be called from the same goroutine. Calling Pause() and Resume() concurrently from different goroutines causes undefined behavior and may cause Pause() to block indefinitely.
func (*SingleExecutor) Resume ¶
func (se *SingleExecutor) Resume()
Resume resumes this once paused executor by letting any in-progress tasks that had called Yield or Sleep on their Execution instance continue. Pause() and Resume() must be called from the same goroutine. Calling Pause() and Resume() concurrently from different goroutines causes undefined behavior and may cause Pause() to block indefinitely.
func (*SingleExecutor) Start ¶
func (se *SingleExecutor) Start(t Task) *Execution
Start starts task t and returns its Execution. Start blocks until this instance actually starts t. Start interrupts any currently running task before starting t.
type Task ¶
type Task interface {
// Do performs the task. execution is the specific execution of this task.
Do(execution *Execution)
}
Task represents any task
func ParallelTasks ¶
ParallelTasks returns a task that performs all the passed in tasks in parallel.
func RecurringTask ¶
RecurringTask returns a task that does t at each time that r specifies. The returned task ends when there are no more times from r or if some error happens while executing one of the tasks.
func RepeatingTask ¶
RepeatingTask returns a task that performs the pased in task n times.
func SeriesTasks ¶
SeriesTasks returns a task that performas all the passed in tasks in series. If one of the tasks reports an error, the others following it don't get executed.
type TaskCollection ¶
type TaskCollection interface {
// Add adds a task and execution of that task to this collection.
Add(t Task, e *Execution)
// Remove removes task t from this collection.
Remove(t Task)
// Conflicts returns the execution of all tasks that conflict with t.
// If t is nil it means return the executions of all tasks in this
// collection.
Conflicts(t Task) []*Execution
}
Interface TaskCollection represents a collection of running tasks. Clients must not call the Add() or Remove() method directly. Implementations of this interface can provide additional methods giving clients a read-only view of running tasks and executions.
Source Files
Directories