run

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 8, 2020 License: Apache-2.0 Imports: 4 Imported by: 958

README

run

GoDoc Build Status Go Report Card Apache 2 licensed

run.Group is a universal mechanism to manage goroutine lifecycles.

Create a zero-value run.Group, and then add actors to it. Actors are defined as a pair of functions: an execute function, which should run synchronously; and an interrupt function, which, when invoked, should cause the execute function to return. Finally, invoke Run, which concurrently runs all of the actors, waits until the first actor exits, invokes the interrupt functions, and finally returns control to the caller only once all actors have returned. This general-purpose API allows callers to model pretty much any runnable task, and achieve well-defined lifecycle semantics for the group.

run.Group was written to manage component lifecycles in func main for OK Log. But it's useful in any circumstance where you need to orchestrate multiple goroutines as a unit whole. Click here to see a video of a talk where run.Group is described.

Examples

context.Context
ctx, cancel := context.WithCancel(context.Background())
g.Add(func() error {
	return myProcess(ctx, ...)
}, func(error) {
	cancel()
})
net.Listener
ln, _ := net.Listen("tcp", ":8080")
g.Add(func() error {
	return http.Serve(ln, nil)
}, func(error) {
	ln.Close()
})
io.ReadCloser
var conn io.ReadCloser = ...
g.Add(func() error {
	s := bufio.NewScanner(conn)
	for s.Scan() {
		println(s.Text())
	}
	return s.Err()
}, func(error) {
	conn.Close()
})

Comparisons

Package run is somewhat similar to package errgroup, except it doesn't require actor goroutines to understand context semantics.

It's somewhat similar to package tomb.v1 or tomb.v2, except it has a much smaller API surface, delegating e.g. staged shutdown of goroutines to the caller.

Documentation

Overview

Package run implements an actor-runner with deterministic teardown. It is somewhat similar to package errgroup, except it does not require actor goroutines to understand context semantics. This makes it suitable for use in more circumstances; for example, goroutines which are handling connections from net.Listeners, or scanning input from a closable io.Reader.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func SignalHandler added in v1.1.0

func SignalHandler(ctx context.Context, signals ...os.Signal) (execute func() error, interrupt func(error))

SignalHandler returns an actor, i.e. an execute and interrupt func, that terminates with SignalError when the process receives one of the provided signals, or the parent context is canceled.

Types

type Group

type Group struct {
	// contains filtered or unexported fields
}

Group collects actors (functions) and runs them concurrently. When one actor (function) returns, all actors are interrupted. The zero value of a Group is useful.

func (*Group) Add

func (g *Group) Add(execute func() error, interrupt func(error))

Add an actor (function) to the group. Each actor must be pre-emptable by an interrupt function. That is, if interrupt is invoked, execute should return. Also, it must be safe to call interrupt even after execute has returned.

The first actor (function) to return interrupts all running actors. The error is passed to the interrupt functions, and is returned by Run.

Example (Basic)
package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/oklog/run"
)

func main() {
	var g run.Group
	{
		cancel := make(chan struct{})
		g.Add(func() error {
			select {
			case <-time.After(time.Second):
				fmt.Printf("The first actor had its time elapsed\n")
				return nil
			case <-cancel:
				fmt.Printf("The first actor was canceled\n")
				return nil
			}
		}, func(err error) {
			fmt.Printf("The first actor was interrupted with: %v\n", err)
			close(cancel)
		})
	}
	{
		g.Add(func() error {
			fmt.Printf("The second actor is returning immediately\n")
			return errors.New("immediate teardown")
		}, func(err error) {
			// Note that this interrupt function is called, even though the
			// corresponding execute function has already returned.
			fmt.Printf("The second actor was interrupted with: %v\n", err)
		})
	}
	fmt.Printf("The group was terminated with: %v\n", g.Run())
}
Output:

The second actor is returning immediately
The first actor was interrupted with: immediate teardown
The second actor was interrupted with: immediate teardown
The first actor was canceled
The group was terminated with: immediate teardown
Example (Context)
package main

import (
	"context"
	"fmt"

	"github.com/oklog/run"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	var g run.Group
	{
		ctx, cancel := context.WithCancel(ctx) // note: shadowed
		g.Add(func() error {
			return runUntilCanceled(ctx)
		}, func(error) {
			cancel()
		})
	}
	go cancel()
	fmt.Printf("The group was terminated with: %v\n", g.Run())
}

func runUntilCanceled(ctx context.Context) error {
	<-ctx.Done()
	return ctx.Err()
}
Output:

The group was terminated with: context canceled
Example (Listener)
package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"

	"github.com/oklog/run"
)

func main() {
	var g run.Group
	{
		ln, _ := net.Listen("tcp", ":0")
		g.Add(func() error {
			defer fmt.Printf("http.Serve returned\n")
			return http.Serve(ln, http.NewServeMux())
		}, func(error) {
			ln.Close()
		})
	}
	{
		g.Add(func() error {
			return errors.New("immediate teardown")
		}, func(error) {
			//
		})
	}
	fmt.Printf("The group was terminated with: %v\n", g.Run())
}
Output:

http.Serve returned
The group was terminated with: immediate teardown

func (*Group) Run

func (g *Group) Run() error

Run all actors (functions) concurrently. When the first actor returns, all others are interrupted. Run only returns when all actors have exited. Run returns the error returned by the first exiting actor.

type SignalError added in v1.1.0

type SignalError struct {
	Signal os.Signal
}

SignalError is returned by the signal handler's execute function when it terminates due to a received signal.

func (SignalError) Error added in v1.1.0

func (e SignalError) Error() string

Error implements the error interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL