Documentation
¶
Overview ¶
Package routine helps in starting background tasks.
Example (ClusterBackgroundTask) ¶
package main
import (
"context"
"fmt"
"log"
"os"
"testing"
"time"
"github.com/pace/bricks/pkg/routine"
)
func main() {
// This example is an integration test because it requires redis to run. If
// we are running the short tests just print the output that is expected to
// circumvent the test runner. Because there is no way to skip an example.
if testing.Short() {
fmt.Println("task run 0\ntask run 1\ntask run 2")
return
}
out := make(chan string)
// start the routine in the background
cancel := routine.RunNamed(context.Background(), "task",
func(ctx context.Context) {
for i := 0; ; i++ {
select {
case <-ctx.Done():
return
default:
}
out <- fmt.Sprintf("task run %d", i)
time.Sleep(100 * time.Millisecond)
}
},
// KeepRunningOneInstance will cause the routine to be restarted if it
// finishes. It also will use the default redis database to synchronize
// with other instances running this routine so that in all instances
// exactly one routine is running at all time.
routine.KeepRunningOneInstance(),
)
// Cancel after 3 results. Cancel will only cancel the routine in this
// instance. It will not cancel the synchronized routines of other
// instances.
for i := 0; i < 3; i++ {
println(<-out)
}
cancel()
}
// Prints the string normally so that it can be consumed by the test runner.
// Additionally go around the test runner in case of a integration test that
// wants examine the output of another test.
func println(s string) {
if os.Getenv("TEST_SUBPROCESS") == "1" {
_, _ = log.Writer().Write([]byte(s + "\n"))
}
fmt.Println(s)
}
Output: task run 0 task run 1 task run 2
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run runs the given function in a new background context. The new context inherits the logger and oauth2 authentication of the parent context. Panics thrown in the function are logged and sent to sentry. The routines context is canceled if the program receives a shutdown signal (SIGINT, SIGTERM), if the returned CancelFunc is called, or if the routine returned.
func RunNamed ¶ added in v0.1.33
func RunNamed(parentCtx context.Context, name string, routine func(context.Context), opts ...Option) (cancel context.CancelFunc)
RunNamed runs a routine like Run does. Additionally it assigns the routine a name and allows using options to control how the routine is run. Routines with the same name show consistent behaviour for the options, like mutual exclusion, across their group. By default all callers that share the same redis database are members of the same group, no matter whether they are goroutines of a single process or of processes running on different hosts. The default redis database is configured via the REDIS_* environment variables.
Types ¶
type Option ¶ added in v0.1.33
type Option func(*options)
Option specifies how a routine is run.
func KeepRunningOneInstance ¶ added in v0.1.33
func KeepRunningOneInstance() Option
KeepRunningOneInstance returns an option that runs the routine once simultaneously and keeps it running, restarting it if necessary. Subsequent calls of the routine are stalled until the previous call returned.
In clusters with multiple processes only one caller actually executes the routine, but it can be any one of the callers. If the routine finishes any caller including the same caller can execute it. If the process of the caller executing the routine is stopped another caller executes the routine. If the last caller is stopped, the routine stops executing due to lack of callers that can continue execution. There is no automatic takeover of the routine by other running members of the group, that did not call it explicitly.
Due to lack of a better name, the name of this option is quite verbose. Feel free to propose any better name as an alias for this option.
Source Files