cockroach: github.com/cockroachdb/cockroach/pkg/util/stop Index | Files

package stop

import "github.com/cockroachdb/cockroach/pkg/util/stop"

Index

Package Files

stopper.go

Variables

var ErrThrottled = errors.New("throttled on async limiting semaphore")

ErrThrottled is returned from RunLimitedAsyncTask in the event that there is no more capacity for async tasks, as limited by the semaphore.

var ErrUnavailable = &roachpb.NodeUnavailableError{}

ErrUnavailable indicates that the server is quiescing and is unable to process new work.

func HandleDebug Uses

func HandleDebug(w http.ResponseWriter, r *http.Request)

HandleDebug responds with the list of stopper tasks actively running.

type Closer Uses

type Closer interface {
    Close()
}

Closer is an interface for objects to attach to the stopper to be closed once the stopper completes.

type CloserFn Uses

type CloserFn func()

CloserFn is type that allows any function to be a Closer.

func (CloserFn) Close Uses

func (f CloserFn) Close()

Close implements the Closer interface.

type Option Uses

type Option interface {
    // contains filtered or unexported methods
}

An Option can be passed to NewStopper.

func OnPanic Uses

func OnPanic(handler func(interface{})) Option

OnPanic is an option which lets the Stopper recover from all panics using the provided panic handler.

When Stop() is invoked during stack unwinding, OnPanic is also invoked, but Stop() may not have carried out its duties.

type Stopper Uses

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

A Stopper provides a channel-based mechanism to stop an arbitrary array of workers. Each worker is registered with the stopper via the RunWorker() method. The system further allows execution of functions through RunTask() and RunAsyncTask().

Stopping occurs in two phases: the first is the request to stop, which moves the stopper into a quiescing phase. While quiescing, calls to RunTask() & RunAsyncTask() don't execute the function passed in and return ErrUnavailable. When all outstanding tasks have been completed, the stopper closes its stopper channel, which signals all live workers that it's safe to shut down. When all workers have shutdown, the stopper is complete.

An arbitrary list of objects implementing the Closer interface may be added to the stopper via AddCloser(), to be closed after the stopper has stopped.

func NewStopper Uses

func NewStopper(options ...Option) *Stopper

NewStopper returns an instance of Stopper.

func (*Stopper) AddCloser Uses

func (s *Stopper) AddCloser(c Closer)

AddCloser adds an object to close after the stopper has been stopped.

WARNING: memory resources acquired by this method will stay around for the lifetime of the Stopper. Use with care to avoid leaking memory.

func (*Stopper) IsStopped Uses

func (s *Stopper) IsStopped() <-chan struct{}

IsStopped returns a channel which will be closed after Stop() has been invoked to full completion, meaning all workers have completed and all closers have been closed.

func (*Stopper) NumTasks Uses

func (s *Stopper) NumTasks() int

NumTasks returns the number of active tasks.

func (*Stopper) Quiesce Uses

func (s *Stopper) Quiesce(ctx context.Context)

Quiesce moves the stopper to state quiescing and waits until all tasks complete. This is used from Stop() and unittests.

func (*Stopper) Recover Uses

func (s *Stopper) Recover(ctx context.Context)

Recover is used internally by Stopper to provide a hook for recovery of panics on goroutines started by the Stopper. It can also be invoked explicitly (via "defer s.Recover()") on goroutines that are created outside of Stopper.

func (*Stopper) RunAsyncTask Uses

func (s *Stopper) RunAsyncTask(
    ctx context.Context, taskName string, f func(context.Context),
) error

RunAsyncTask is like RunTask, except the callback is run in a goroutine. The method doesn't block for the callback to finish execution.

func (*Stopper) RunLimitedAsyncTask Uses

func (s *Stopper) RunLimitedAsyncTask(
    ctx context.Context, taskName string, sem chan struct{}, wait bool, f func(context.Context),
) error

RunLimitedAsyncTask runs function f in a goroutine, using the given channel as a semaphore to limit the number of tasks that are run concurrently to the channel's capacity. If wait is true, blocks until the semaphore is available in order to push back on callers that may be trying to create many tasks. If wait is false, returns immediately with an error if the semaphore is not available. Returns an error if the Stopper is quiescing, in which case the function is not executed.

func (*Stopper) RunTask Uses

func (s *Stopper) RunTask(ctx context.Context, taskName string, f func(context.Context)) error

RunTask adds one to the count of tasks left to quiesce in the system. Any worker which is a "first mover" when starting tasks must call this method before starting work on a new task. First movers include goroutines launched to do periodic work and the kv/db.go gateway which accepts external client requests.

taskName is used as the "operation" field of the span opened for this task and is visible in traces. It's also part of reports printed by stoppers waiting to stop. The convention is <package name>.<struct name>: <succinct description of the task's action>

Returns an error to indicate that the system is currently quiescing and function f was not called.

func (*Stopper) RunTaskWithErr Uses

func (s *Stopper) RunTaskWithErr(
    ctx context.Context, taskName string, f func(context.Context) error,
) error

RunTaskWithErr is like RunTask(), but takes in a callback that can return an error. The error is returned to the caller.

func (*Stopper) RunWorker Uses

func (s *Stopper) RunWorker(ctx context.Context, f func(context.Context))

RunWorker runs the supplied function as a "worker" to be stopped by the stopper. The function <f> is run in a goroutine.

func (*Stopper) RunningTasks Uses

func (s *Stopper) RunningTasks() TaskMap

RunningTasks returns a map containing the count of running tasks keyed by call site.

func (*Stopper) ShouldQuiesce Uses

func (s *Stopper) ShouldQuiesce() <-chan struct{}

ShouldQuiesce returns a channel which will be closed when Stop() has been invoked and outstanding tasks should begin to quiesce.

func (*Stopper) ShouldStop Uses

func (s *Stopper) ShouldStop() <-chan struct{}

ShouldStop returns a channel which will be closed when Stop() has been invoked and outstanding tasks have quiesced.

func (*Stopper) Stop Uses

func (s *Stopper) Stop(ctx context.Context)

Stop signals all live workers to stop and then waits for each to confirm it has stopped.

func (*Stopper) WithCancelOnQuiesce Uses

func (s *Stopper) WithCancelOnQuiesce(ctx context.Context) (context.Context, func())

WithCancelOnQuiesce returns a child context which is canceled when the returned cancel function is called or when the Stopper begins to quiesce, whichever happens first.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

func (*Stopper) WithCancelOnStop Uses

func (s *Stopper) WithCancelOnStop(ctx context.Context) (context.Context, func())

WithCancelOnStop returns a child context which is canceled when the returned cancel function is called or when the Stopper begins to stop, whichever happens first.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

type TaskMap Uses

type TaskMap map[string]int

A TaskMap is returned by RunningTasks().

func (TaskMap) String Uses

func (tm TaskMap) String() string

String implements fmt.Stringer and returns a sorted multi-line listing of the TaskMap.

Package stop imports 14 packages (graph) and is imported by 118 packages. Updated 2019-07-23. Refresh now. Tools for package owners.