README
¶
some helpers to write common routines
Work in progress
This library is still WORK IN PROGRESS. Codes here are used in several small projects in production for few months, should be safe I think. But it still need some refinement like writting docs, better test cases and benchmarks.
Graceful shutdown made easy
func myCrawler(ctx context.Context) (err error) {
req, err := http.NewRequestWithContext(
ctx, "GET", "https://google.com", nil,
)
if err != nil {
// log the error and
return err
}
data, err := grab(req)
if err != nil {
// log the error and
return
}
err = saveDB(ctx, data)
// log the error and
return
}
func main() {
r := Loop( // infinite loop
RunAtLeast( // do not run crawler too fast
10*time.Second,
CTXRunner(myCrawler),
))
// cancel og signal, and log the returned error
log.Print(CancelOnSignal(r, os.Interrupt, os.Kill))
}
Race conditions
Codes in this library are thread-safe unless specified. However, thread-safety of external function is not covered.
Considering this example:
f := Loop(FuncRunner(cancel, yourFunc))
f is thread-safe iff cancel and yourFunc are thread-safe.
License
Copyright Chung-Ping Jen ronmi.ren@gmail.com 2021-
MPL v2.0
Documentation
¶
Overview ¶
Package ctxroutines prevides some helpers to write common routines and handle gracefully shutdown procedure
Index ¶
- func CancelAll(rs ...Runner) context.CancelFunc
- func CancelOnSignal(r Runner, sig ...os.Signal) (err error)
- func IsCanceled(r Runner) bool
- func Run(rs ...Runner) (err []error)
- type ErrSignalReceived
- type RecordedRunner
- type Runner
- func AnyErr(rs ...Runner) (ret Runner)
- func CTXRunner(f func(context.Context) error) Runner
- func CTXRunnerWith(ctx context.Context, f func(context.Context) error) Runner
- func FirstErr(rs ...Runner) (ret Runner)
- func FromRunner(r Runner, f func() error) Runner
- func FuncRunner(cancel context.CancelFunc, f func() error) Runner
- func Loop(r Runner) (ret Runner)
- func NewRunner(ctx context.Context, cancel context.CancelFunc, f func() error) Runner
- func NoCancelRunner(f func() error) Runner
- func NoLessThan(dur time.Duration, f Runner) Runner
- func NonInterruptRunner(f func() error) Runner
- func OnceFailedWithin(dur time.Duration, f Runner) (ret Runner)
- func OnceSuccessWithin(dur time.Duration, f Runner) (ret Runner)
- func OnceWithin(dur time.Duration, f Runner) (ret Runner)
- func RatelimitRunner(l *rate.Limiter, r Runner) (ret Runner)
- func Retry(r Runner) (ret Runner)
- func RetryWithCB(r Runner, cb func(error)) (ret Runner)
- func RetryWithChan(r Runner, ch chan<- error) (ret Runner)
- func RunAtLeast(dur time.Duration, f Runner) (ret Runner)
- func RunAtLeastFailed(dur time.Duration, f Runner) (ret Runner)
- func RunAtLeastSuccess(dur time.Duration, f Runner) (ret Runner)
- func SignalRunner(sig ...os.Signal) Runner
- func Skip(rs ...Runner) Runner
- func SomeErr(rs ...Runner) (ret Runner)
- func TilErr(r Runner) (ret Runner)
- func TryAtMost(n uint64, f Runner) (ret Runner)
- type StatefulRunner
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CancelAll ¶
func CancelAll(rs ...Runner) context.CancelFunc
CancelAll creates a function that calls Cancel() for every Runner of rs
func CancelOnSignal ¶
CancelOnSignal runs r and calls r.Cancel when receiving first signal in sig
func IsCanceled ¶
Types ¶
type ErrSignalReceived ¶ added in v0.0.3
ErrSignalReceived indicates the signal that SignalRunner received
func (ErrSignalReceived) Error ¶ added in v0.0.3
func (s ErrSignalReceived) Error() string
type RecordedRunner ¶
RecordedRunner is a Runner remembers how many times has been run
func Counter ¶
func Counter(f func(uint64) error) RecordedRunner
Counter creates RecordedRunner from function
type Runner ¶
type Runner interface {
Context() context.Context
Cancel()
// Run SHOULD always return some error after canceled
Run() error
}
Runner defines a cancelable function
func CTXRunner ¶
CTXRunner creates a Runner from a context-controlled function
Typical usage is to wrap a cancelable function for further use (like, passing to Loop()
You have to call Cancel() to release resources.
func CTXRunnerWith ¶
CTXRunnerWith creates a Runner from a context-controlled function with predefined context
Typical usage is to wrap a cancelable function for further use (like, passing to Loop()
You have to call Cancel() to release resources.
func FirstErr ¶
FirstErr creates a Runner that runs every Runner of rs in order, until first error occured
func FromRunner ¶
FromRunner reuses context and cancel function from r, but runs different function
func FuncRunner ¶
func FuncRunner(cancel context.CancelFunc, f func() error) Runner
FuncRunner creates a runner from function
Typical usage is like FuncRunner(someStruct.Cancel, someStruct.Run) or
srv := &http.Server{Addr: ":8080"}
r := FuncRunner(srv.Shutdown, srv.ListenAndServe)
func Loop ¶
Loop creates a Runner that runs r until canceled
You have to call Cancel() to release resources.
func NoCancelRunner ¶
NoCancelRunner represents a function that cannot be canceled.
In other words, Cancel() is always ignored.
func NoLessThan ¶
NoLessThan is a wrapper of RatelimitRunner
func NonInterruptRunner ¶ added in v0.0.2
NonInterruptRunner creates a runner that calling Cancel() does not interrupt it
In other words, Cancel() only affects further Run(), which always returns context.Canceled.
func OnceFailedWithin ¶
OnceFailedWithin is like OnceWithin, but only failed call counts.
func OnceSuccessWithin ¶
OnceSuccessWithin is like OnceWithin, but only successful call counts.
func OnceWithin ¶
OnceWithin ensures f is not run more than once within duration dur
Additional calls are just ignored. Say you have an empty Runner f
r := OnceWithin(time.Second, f) r.Run() // runs f r.Run() // skipped time.Sleep(time.Second) r.Run() // runs f
func RatelimitRunner ¶
RatelimitRunner creates a Runner that respects the rate limit.
Say you have an empty Runner r with rate limit to once per second:
go r.Run() // returns immediatly go r.Run() // returns after a second
Once the Runner has been canceled, Run() always return context.Canceled.
RatelimitRunner() looks like RunAtLeast,
func RetryWithCB ¶
RetryWithCB creates a Runner runs r until it returns nil
It calls cb if r returns error.
You have to call Cancel() to release resources.
func RetryWithChan ¶
RetryWithChan is shortcut for RetryWithCB(r, func(e error) { ch <- e })
You have to call Cancel() to release resources.
func RunAtLeast ¶
RunAtLeast ensures the execution time of f is longer than dur
Say you have an empty Runner f
r := RunAtLeast(time.Second, f) r.Run() // runs f immediately, blocks 1s
func RunAtLeastFailed ¶
RunAtLeastFailed is like RunAtLeast, but only failed call counts
func RunAtLeastSuccess ¶
RunAtLeastSuccess is like RunAtLeast, but only successful call counts
func SignalRunner ¶ added in v0.0.3
SignalRunner creates a Runner that waits first signal in sig and returns it as error
func Skip ¶ added in v0.0.3
Skip creates a Runner that runs every Runner of rs in separated goroutine, returns first result and cancels others.
func SomeErr ¶
SomeErr creates a Runner runs every Runner of rs, and returns an error if there's one
- It checks error by the order of rs
- Returns first non-context.Canceled error
- Returns context.Canceled if no other errors
- Returns nil if everything's fine
func TilErr ¶
TilErr creates a Runner runs r until it returns any error
You have to call Cancel() to release resources.
func TryAtMost ¶
TryAtMost creates a Runner that runs f for at most n times before it returns nil
Say you have a f only success on third try:
r := TryAtMost(5, f) r.Run() // run f 3 times, and returs nil r := TryAtMost(2, f) r.Run() // run f 2 times, and returs the error from second run r := TryAtMost(3, f) r.Run() // run f 3 times, and returs nil
type StatefulRunner ¶
type StatefulRunner interface {
Runner
IsRunning() bool
// Try to run the Runner if it's not running. ran will be true if it runs.
TryRun() (err error, ran bool)
// Lock the runner, pretending that it's running. Call release() to unlock.
// It's safe to call release more than once.
//
// It will block until previous Run() has finished.
Lock() (release func())
}
StatefulRunner represents a Runner that can inspect its running state
func NewStatefulRunner ¶
func NewStatefulRunner(f Runner) (ret StatefulRunner)
NewStatefulRunner creates a StatefulRunner from existing Runner
Source Files