1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
# rutina
[](https://pkg.go.dev/go.neonxp.ru/rutina)
Package Rutina (russian "рутина" - ordinary boring everyday work) is routine orchestrator for your application.
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) has flexible run/stop policy. i.e. one routine restarts when it errors (useful on daemons) but if errors another - all routines will be cancelled
3) already has optional signal handler `ListenOsSignals()`
## When it need?
Usually, when your program consists of several routines (i.e.: http server, metrics server and os signals subscriber) and you want to stop all routines when one of them ends (i.e.: by TERM os signal in signal subscriber).
## Usage
### New instance
With default options:
```go
r := rutina.New()
```
or with custom options:
```go
r := rutina.New(
ParentContext(ctx context.Context), // Pass parent context to Rutina (otherwise it uses own new context)
ListenOsSignals(listenOsSignals ...os.Signal), // Auto listen OS signals and close context on Kill, Term signal
Logger(l logger), // Pass logger for debug, i.e. `log.Printf`
Errors(errCh chan error), // Set errors channel for errors from routines in Restart/DoNothing errors policy
)
```
### Start new routine
```go
r.Go(func (ctx context.Context) error {
...do something...
})
```
#### Run Options
```go
r.Go(
func (ctx context.Context) error {
...do something...
},
SetOnDone(policy Policy), // Run policy if returns no error (default: Shutdown)
SetOnError(policy Policy), // Run policy if returns error (default: Shutdown)
SetTimeout(timeout time.Duration), // Timeout to routine (after it context will be closed)
SetMaxCount(maxCount int), // Max tries on Restart policy
)
```
#### Run policies
* `DoNothing` - do not affect other routines
* `Restart` - restart current routine
* `Shutdown` - shutdown all routines
#### Example of run policies
```go
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 - all other routines will shutdown (because context cancels)
},)
r.Go(func(ctx context.Context) error {
// If this routine produce no error - it restarts
// If it returns error - all other routines will shutdown (because context cancels)
}, SetOnDone(rutina.Restart))
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 (maximum 10 times)
}, SetOnError(rutina.Restart), SetMaxCount(10))
r.Go(func(ctx context.Context) error {
// If this routine stopped by any case other routines will work as before.
}, SetOnDone(rutina.DoNothing))
r.ListenOsSignals() // Shutdown all routines by OS signal
```
### Wait routines to complete
```go
err := r.Wait()
```
Here err = error that shutdowns all routines (may be will be changed at future)
### Kill routines
```go
id := r.Go(func (ctx context.Context) error { ... })
...
r.Kill(id) // Closes individual context for #id routine that must shutdown it
```
### List of routines
```go
list := r.Processes()
```
Returns ids of working routines
### Get errors channel
```go
err := <- r.Errors()
```
Disabled by default. Used when passed errors channel to rutina options
## Example
HTTP server with graceful shutdown [`example/http_server.go`](https://gitrepo.ru/NeonXP/rutina/blob/master/example/http_server.go)
Different run policies [`example/policies.go`](https://gitrepo.ru/NeonXP/rutina/blob/master/example/policies.go)
|
