Documentation
¶
Overview ¶
Package task provides some helper to work with common routines so that it can be cancellable or repeatable.
In this and derived packages (like forge), the term "Tiny" indicates the source function does not receives a context, and "Micro" is a never-fail "Tiny".
Index ¶
- Variables
- func IgnoreErrs(errorList ...error) func(error) error
- func OnlyErrs(errorList ...error) func(error) error
- type CtxMod
- type Task
- func Copy(dst io.Writer, src io.ReadCloser) Task
- func CopyBuffer(dst io.Writer, src io.ReadCloser, buf []byte) Task
- func First(tasks ...Task) Task
- func FromServer(start func() error, stop func()) Task
- func Iter(tasks ...Task) Task
- func Micro(f func()) Task
- func Skip(tasks ...Task) Task
- func Sleep(timeout time.Duration) Task
- func Tiny(f func() error) Task
- func Wait(tasks ...Task) Task
- func (t Task) Exec() error
- func (t Task) Go(ctx context.Context) <-chan error
- func (t Task) GoWithChan(ctx context.Context, ch chan<- error)
- func (t Task) HandleErr(f func(error) error) Task
- func (t Task) HandleErrWithContext(f func(context.Context, error) error) Task
- func (t Task) IgnoreErr() Task
- func (t Task) IgnoreErrs(errorList ...error) Task
- func (t Task) Loop() Task
- func (t Task) Once() Task
- func (t Task) OnlyErrs(errorList ...error) Task
- func (t Task) Retry() Task
- func (t Task) RetryN(n int) Task
- func (t Task) Run(ctx context.Context) error
- func (t Task) Timed(dur time.Duration) Task
- func (t Task) TimedDone(dur time.Duration) Task
- func (t Task) TimedDoneF(f func(time.Duration) time.Duration) Task
- func (t Task) TimedF(f func(time.Duration) time.Duration) Task
- func (t Task) TimedFail(dur time.Duration) Task
- func (t Task) TimedFailF(f func(time.Duration) time.Duration) Task
- func (t Task) With(modder CtxMod) Task
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrOnce = errors.New("the task can only be executed once.")
Functions ¶
func IgnoreErrs ¶ added in v0.1.0
IgnoreErrs creates a function to be used in Task.IgnoreErrs that ignores specific errors.
Errors are compared using errors.Is.
Types ¶
type Task ¶
Task repeasents a (maybe) cancellable routine.
func Copy ¶
func Copy(dst io.Writer, src io.ReadCloser) Task
Copy wraps io.Copy into a cancellable task. Cancelling context will close src.
func CopyBuffer ¶ added in v0.1.0
Copy wraps io.CopyBuffer into a cancellable task. Cancelling context will close src.
func First ¶ added in v0.1.0
First creates a task that runs tasks concurrently, return first result and cancel others.
Take care of Tiny tasks as it cannot be cancelled by context.
func FromServer ¶
FromServer creates a task from something can be started or stopped. Running the task calls start, and cancelling context calls stop.
func Iter ¶
Iter creates a task run tasks with same context and stops at first error.
Example ¶
e := errors.New("err")
a := func(_ context.Context) error { fmt.Println("a"); return nil }
b := func(_ context.Context) error { fmt.Println("b"); return e }
c := func(_ context.Context) error { fmt.Println("c"); return nil }
err := Iter(a, b, c).Run(context.Background())
if err != e {
fmt.Println("unexpected error:", err)
return
}
Output: a b
func Micro ¶ added in v0.1.0
func Micro(f func()) Task
Micro wraps a never-fail, non-cancellable function into task.
func Skip ¶
Skip creates a task that runs tasks concurrently, cancel others if any error, and wait them done.
Take care of Tiny tasks as it cannot be cancelled by context.
Example ¶
e := errors.New("err")
a := func(ctx context.Context) error {
if err := Sleep(time.Minute).Run(ctx); err != nil {
fmt.Println("context canceled")
return err
}
fmt.Println("a")
return nil
}
b := func(_ context.Context) error { fmt.Println("b"); return e }
c := func(ctx context.Context) error {
if err := Sleep(time.Minute).Run(ctx); err != nil {
fmt.Println("context canceled")
return err
}
fmt.Println("c")
return nil
}
err := Skip(a, b, c).Run(context.Background())
if err != e {
fmt.Println("unexpected error:", err)
return
}
Output: b context canceled context canceled
func Wait ¶
Wait creates a task that runs all task concurrently, wait them get done, and return first non-nil error.
func (Task) Exec ¶ added in v0.1.0
Exec runs the task with empty context (context.Background).
func (Task) Go ¶ added in v0.1.0
Go runs t in separated goroutine and returns a channel to retrieve error.
It's safe to ignore the channel if you don't need the result.
func (Task) GoWithChan ¶ added in v0.1.0
GoWithChan runs t in separated goroutine and sends returned error into ch.
func (Task) HandleErr ¶ added in v0.1.0
HandleErr creates a task that handles specific error after running t. It could change the error returned by Run. f is called only if t.Run returns an error.
func (Task) HandleErrWithContext ¶ added in v0.1.0
HandleErrWithContext is like HandleErr, but uses same context used in f.
func (Task) IgnoreErr ¶ added in v0.1.0
IgnoreErr ignores the error returned by t.Run if it is not context error.
Context error means context.Canceled and context.DeadlineExceeded.
func (Task) IgnoreErrs ¶ added in v0.1.0
IgnoreErrs ignores specific error.
func (Task) Loop ¶ added in v0.1.0
Loop creates a task that repeatedly runs t with same context until it returns an error.
func (Task) Once ¶ added in v0.1.0
Once creates a task that can be run only for once, further attempt returns ErrOnce.
func (Task) Retry ¶ added in v0.1.0
Retry creates a task thats repeatedly runs t with same context until it returns nil.
Retrying Micro task is resource-wasting as it never fail.
func (Task) RetryN ¶ added in v0.1.0
RetryN is like Retry, but retries no more than n times.
In other words, RetryN(2) will run at most 3 times:
- first try
- first retry
- second retry
Retrying Micro task is resource-wasting as it never fail.
Example ¶
ctx := context.Background()
n := 1
errTask := func(_ context.Context) error {
fmt.Println(n)
n++
return errors.New("")
}
retry := Task(errTask).RetryN(2)
retry.Run(ctx)
Output: 1 2 3
func (Task) Timed ¶ added in v0.1.0
Timed wraps t into a task ensures that it is not returned before dur passed.
It focuses on "How long I should wait before returning". Take a look at example for how it works.
If you're looking for rate limiting solution, you should take a look at "rated" subdirectory.
Example ¶
ctx := context.Background()
begin := time.Now()
quickTask := Task(func(_ context.Context) error {
// simulates a quick task like computing 1+1
fmt.Printf("quick done at +%d socond\n", time.Since(begin)/time.Second)
return nil
}).Timed(time.Second)
quickTask.Run(ctx)
fmt.Printf("quick returns at +%d second\n", time.Since(begin)/time.Second)
begin = time.Now()
slowTask := Task(func(_ context.Context) error {
// simulates a slow task like calling web api
time.Sleep(2 * time.Second)
fmt.Printf("slow done at +%d socond\n", time.Since(begin)/time.Second)
return nil
}).Timed(time.Second)
slowTask.Run(ctx)
fmt.Printf("slow returns at +%d second\n", time.Since(begin)/time.Second)
Output: quick done at +0 socond quick returns at +1 second slow done at +2 socond slow returns at +2 second
func (Task) TimedDone ¶ added in v0.1.0
TimedDone is like Timed, but limits only successful run.
If you're looking for rate limiting solution, you should take a look at "rated" subdirectory.
Example ¶
ctx := context.Background()
begin := time.Now()
doneTask := Task(func(_ context.Context) error {
// a task which always success
return nil
}).TimedDone(time.Second)
doneTask.Run(ctx)
fmt.Printf("done returns at +%d second\n", time.Since(begin)/time.Second)
begin = time.Now()
failTask := Task(func(_ context.Context) error {
return errors.New("a task which always fail")
}).TimedDone(time.Second)
failTask.Run(ctx)
fmt.Printf("fail returns at +%d second\n", time.Since(begin)/time.Second)
Output: done returns at +1 second fail returns at +0 second
func (Task) TimedDoneF ¶ added in v0.1.0
TimedDoneF is like TimedDone, but use function instead.
func (Task) TimedFail ¶ added in v0.1.0
TimedFail is like Timed, but limits only failed run.
If you're looking for rate limiting solution, you should take a look at "rated" subdirectory.
func (Task) TimedFailF ¶ added in v0.1.0
TimedFailF is like TimedFail, but use function instead.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package deptask provides a tool, [Runner], to run tasks in order according to its dependency.
|
Package deptask provides a tool, [Runner], to run tasks in order according to its dependency. |
|
Package forge defines [Generator], a (maybe) cancellable funtion that generates one value on each run.
|
Package forge defines [Generator], a (maybe) cancellable funtion that generates one value on each run. |
|
Package future defines [Future], a value which is determined some time in future.
|
Package future defines [Future], a value which is determined some time in future. |
|
Package httptask provides some helper to wrap http server and some client job into task.
|
Package httptask provides some helper to wrap http server and some client job into task. |
|
Package lossy contains wait/notify and pub/sub implementations that can lose data.
|
Package lossy contains wait/notify and pub/sub implementations that can lose data. |
|
Package rated controls rate of a task with [rate.Limiter].
|
Package rated controls rate of a task with [rate.Limiter]. |