package goroutine

import "github.com/sourcegraph/sourcegraph/internal/goroutine"

Index

Examples

Package Files

background.go bounded.go gen.go goroutine.go parallel.go periodic.go pool.go

Variables 

var GracefulShutdownTimeout = env.MustGetDuration("SRC_GRACEFUL_SHUTDOWN_TIMEOUT", 10*time.Second, "Graceful shutdown timeout")

func Go 

func Go(f func())

Go runs the given function in a goroutine and catches and logs panics.

This prevents a single panicking goroutine from crashing the entire binary, which is undesirable for services with many different components, like our frontend service, where one location of code panicking could be catastrophic.

More advanced use cases should copy this implementation and modify it.

func MonitorBackgroundRoutines 

func MonitorBackgroundRoutines(ctx context.Context, routines ...BackgroundRoutine)

MonitorBackgroundRoutines will start the given background routines in their own goroutine. If the given context is canceled or a signal is received, the Stop method of each routine will be called. This method blocks until the Stop methods of each routine have returned. Two signals will cause the app to shutdown immediately.

func Parallel 

func Parallel(fns ...func() error) (err error)

Parallel calls each of the given functions in a goroutine. This method blocks until all goroutines have unblocked. The errors from each of the function invocations will be combined into a single error.

func RunWorkers 

func RunWorkers(worker PoolWorker) error

RunWorkers invokes the given worker a number of times proportional to the maximum number of CPUs that can be executing simultaneously.

func RunWorkersN 

func RunWorkersN(n int, worker PoolWorker) (err error)

RunWorkersN invokes the given worker n times and collects the errors from each invocation.

func RunWorkersOverStrings 

func RunWorkersOverStrings(values []string, worker func(index int, value string) error) error

RunWorkersOverStrings invokes the given worker once for each of the given string values. The worker function will receive the index as well as the string value as parameters. Workers will be invoked in a number of concurrent routines proportional to the maximum number of CPUs that can be executing simultaneously.

func RunWorkersOverStringsN 

func RunWorkersOverStringsN(n int, values []string, worker func(index int, value string) error) error

RunWorkersOverStrings invokes the given worker once for each of the given string values. The worker function will receive the index as well as the string value as parameters. Workers will be invoked in n concurrent routines.

type BackgroundRoutine 

type BackgroundRoutine interface {
    StartableRoutine

    // Stop signals the Start method to stop accepting new work and complete its
    // current work. This method can but is not required to block until Start has
    // returned.
    Stop()
}

BackgroundRoutine represents a component of a binary that consists of a long running process with a graceful shutdown mechanism.

See https://docs.sourcegraph.com/dev/background-information/backgroundroutine for more information and a step-by-step guide on how to implement a BackgroundRoutine.

Example

Code: 

r := &exampleRoutine{
    done: make(chan struct{}),
}

ctx, cancel := context.WithCancel(context.Background())

go MonitorBackgroundRoutines(ctx, r)

time.Sleep(500 * time.Millisecond)
cancel()
time.Sleep(200 * time.Millisecond)

func NoopRoutine 

func NoopRoutine() BackgroundRoutine

NoopRoutine does nothing for start or stop.

type Bounded 

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

Bounded runs a bounded number of goroutines. It supports waiting for them all to run, as well as reporting any error that may occur.

func NewBounded 

func NewBounded(capacity int) *Bounded

NewBounded initializes Bounded with a capacity.

func (*Bounded) Go 

func (s *Bounded) Go(f func() error)

Go runs f in a new goroutine. It will only run upto Bounded.N goroutines at a time. Go will block until it can start the goroutine.

The first f to return a non-nil error will have that error returned by Wait. If an f fails, this does not stop future runs.

func (*Bounded) Wait 

func (s *Bounded) Wait() error

Wait until all goroutines have finished running. If a goroutine returns a non-nil error, the first non-nil error recorded will be returned.

type CombinedRoutine 

type CombinedRoutine []BackgroundRoutine

CombinedRoutine is a list of routines which are started and stopped in unison.

func (CombinedRoutine) Start 

func (r CombinedRoutine) Start()

func (CombinedRoutine) Stop 

func (r CombinedRoutine) Stop()

type ErrorHandler 

type ErrorHandler interface {
    // HandleError is called with error values returned from Handle. This will not
    // be called with error values due to a context cancellation during a graceful
    // shutdown.
    HandleError(err error)
}

ErrorHandler is an optional extension of the Handler interface.

type Finalizer 

type Finalizer interface {
    // OnShutdown is called after the last call to Handle during a graceful shutdown.
    OnShutdown()
}

Finalizer is an optional extension of the Handler interface.

type Handler 

type Handler interface {
    // Handle performs an action with the given context.
    Handle(ctx context.Context) error
}

Handler represents the main behavior of a PeriodicGoroutine.

func NewHandlerWithErrorMessage 

func NewHandlerWithErrorMessage(name string, handler func(ctx context.Context) error) Handler

NewHandlerWithErrorMessage wraps the given function to be used as a handler, and prints a canned failure message containing the given name.

type HandlerFunc 

type HandlerFunc func(ctx context.Context) error

HandlerFunc wraps a function so it can be used as a Handler.

func (HandlerFunc) Handle 

func (f HandlerFunc) Handle(ctx context.Context) error

type PeriodicGoroutine 

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

PeriodicGoroutine represents a goroutine whose main behavior is reinvoked periodically.

See https://docs.sourcegraph.com/dev/background-information/backgroundroutine for more information and a step-by-step guide on how to implement a PeriodicBackgroundRoutine.

Example

Code: 

h := NewHandlerWithErrorMessage("example background routine", func(ctx context.Context) error {
    fmt.Println("Hello from the background!")
    return nil
})

ctx, cancel := context.WithCancel(context.Background())

r := NewPeriodicGoroutine(ctx, 200*time.Millisecond, h)

go MonitorBackgroundRoutines(ctx, r)

time.Sleep(500 * time.Millisecond)
cancel()
time.Sleep(200 * time.Millisecond)

func NewPeriodicGoroutine 

func NewPeriodicGoroutine(ctx context.Context, interval time.Duration, handler Handler) *PeriodicGoroutine

NewPeriodicGoroutine creates a new PeriodicGoroutine with the given handler. The context provided will propagate into the executing goroutine and will terminate the goroutine if cancelled.

func NewPeriodicGoroutineWithMetrics 

func NewPeriodicGoroutineWithMetrics(ctx context.Context, interval time.Duration, handler Handler, operation *observation.Operation) *PeriodicGoroutine

NewPeriodicGoroutineWithMetrics creates a new PeriodicGoroutine with the given handler. The context provided will propagate into the executing goroutine and will terminate the goroutine if cancelled.

func (*PeriodicGoroutine) Start 

func (r *PeriodicGoroutine) Start()

Start begins the process of calling the registered handler in a loop. This process will wait the interval supplied at construction between invocations.

func (*PeriodicGoroutine) Stop 

func (r *PeriodicGoroutine) Stop()

Stop will cancel the context passed to the handler function to stop the current iteration of work, then break the loop in the Start method so that no new work is accepted. This method blocks until Start has returned.

type PoolWorker 

type PoolWorker func(errs chan<- error)

Pool worker is a function invoked by RunWorkers that sends any errors that occur during execution down a shared channel.

func SimplePoolWorker 

func SimplePoolWorker(fn func() error) PoolWorker

SimplePoolWorker converts a function returning a single error value into a PoolWorker.

type StartableRoutine 

type StartableRoutine interface {
    // Start begins the long-running process. This routine may also implement
    // a Stop method that should signal this process the application is going
    // to shut down.
    Start()
}

StartableRoutine represents a component of a binary that consists of a long running process.

type WaitableBackgroundRoutine 

type WaitableBackgroundRoutine interface {
    BackgroundRoutine
    Wait()
}

WaitableBackgroundRoutine enhances BackgroundRoutine with a Wait method that blocks until the value's Start method has returned.

Version
v0.0.0 (latest)
Published
Jan 21, 2022
Platform
linux/amd64
Imports
15 packages (graph)
Last checked
1 week ago –

Tools for package owners.