diff options
Diffstat (limited to 'README.md')
| -rwxr-xr-x | README.md | 131 |
1 files changed, 76 insertions, 55 deletions
@@ -5,7 +5,7 @@ Package Rutina (russian "рутина" - ordinary boring everyday work) is routi It seems like https://godoc.org/golang.org/x/sync/errgroup with some different: 1) propagates context to every routines. So routine can check if context stopped (`ctx.Done()`). -2) by default cancels context when any routine ends with any result (not only when error result). Can be configured by option `OptionCancelByError`. +2) has flexible run/stop policy. i.e. one routine restarts when it fails (useful on daemons) but if fails another - all routines will be cancelled 3) already has optional signal handler `ListenOsSignals()` ## When it need? @@ -16,88 +16,109 @@ Usually, when your program consists of several routines (i.e.: http server, metr ### New instance -`r := rutina.New()` +```go +r := rutina.New() +``` -or with options (see below): +or with optional mixins (see below): -`r := rutina.New(...Option)` or `r.WithOptions(...Option)` +```go +r := rutina.New(...Mixins) +``` +or +```go +r.With(...Mixins) +``` ### Start new routine -``` +```go r.Go(func (ctx context.Context) error { ...do something... -}) +}, ...runOptions) ``` -### Wait routines to complete +Available options of run policy: + +* `ShutdownIfFail` - Shutdown all routines if this routine fails +* `RestartIfFail` - Restart this routine if it fail +* `DoNothingIfFail` - Do nothing just stop this routine if it fail +* `ShutdownIfDone` - Shutdown all routines if this routine done without errors +* `RestartIfDone` - Restart if this routine done without errors +* `DoNothingIfDone` - Do nothing if this routine done without errors + +Default policy: + +`ShutdownIfFail` && `DoNothingIfDone` + +#### Example of run policies + +```go + r.Go(func(ctx context.Context) error { + // If this routine produce no error - it just restarts + // If it returns error - all other routines will shutdown (because context cancels) + }, rutina.RestartIfDone, rutina.ShutdownIfFail) + + r.Go(func(ctx context.Context) error { + // If this routine produce no error - it just completes + // If it returns error - all other routines will shutdown (because context cancels) + }, rutina.DoNothingIfDone, rutina.ShutdownIfFail) + r.Go(func(ctx context.Context) error { + // If this routine produce no error - all other routines will shutdown (because context cancels) + // If it returns error - it will be restarted + }, rutina.RestartIfFail) + + r.Go(func(ctx context.Context) error { + // If this routine stopped by any case - all other routines will shutdown (because context cancels) + }, rutina.ShutdownIfDone) + + r.ListenOsSignals() // Shutdown all routines by OS signal ``` + +### Wait routines to complete + +```go err := r.Wait() ``` -Here err = first error in any routine +Here err = error that shutdowns all routines (may be will be changed at future) -## Options +## Mixins -### Usage options +### Usage -`r := rutina.New(option1, option2, ...)` -or +```go +r := rutina.New(mixin1, mixin2, ...) ``` +or +```go r := rutina.New() -r = r.WithOptions(option1, option2, ...) // Returns new instance of Rutina! +r = r.With(mixin1, mixin2, ...) // Returns new instance of Rutina! ``` ### Logger -`rutina.WithLogger(logger log.Logger) Option` or `rutina.WithStdLogger() Option` - -### Custom context +```go +r.With(rutina.WithStdLogger()) +``` +or +```go +r.With(rutina.WithLogger(logger log.Logger)) +``` -`rutina.WithContext(ctx context.Context) Option` +Sets standard or custom logger. By default there is no logger. -### Cancel only by errors +### Custom context -`rutina.WithCancelByError() Option` +```go +r.With(rutina.WithContext(ctx context.Context)) +```` -If this option set, rutina doesnt cancel context if routine completed without error. +Propagates your own context to Rutina. By default it use own context. ## Example -HTTP server with graceful shutdown (`example/http_server.go`): +HTTP server with graceful shutdown [`example/http_server.go`](https://github.com/NeonXP/rutina/blob/master/example/http_server.go) -``` -// New instance with builtin context. Alternative: r, ctx := rutina.WithContext(ctx) -r := rutina.New(rutina.WithStdLogger()) - -srv := &http.Server{Addr: ":8080"} -http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { - io.WriteString(w, "hello world\n") -}) - -// Starting http server and listen connections -r.Go(func(ctx context.Context) error { - if err := srv.ListenAndServe(); err != nil { - return err - } - log.Println("Server stopped") - return nil -}) - -// Gracefully stoping server when context canceled -r.Go(func(ctx context.Context) error { - <-ctx.Done() - log.Println("Stopping server...") - return srv.Shutdown(ctx) -}) - -// OS signals listener -r.ListenOsSignals() - -if err := r.Wait(); err != nil { - log.Fatal(err) -} - -log.Println("All routines successfully stopped") -```
\ No newline at end of file +Different run policies [`example/policies.go`](https://github.com/NeonXP/rutina/blob/master/example/policies.go) |