proc

Documentation

Overview

Package proc defines a lightweight primitive called a "process" and provides functions that compose processes to allow common concurrency patterns to be expressed conveniently.

A "process" is, fundamentally, just the time spent executing a function with a particular signature. A process runs in a Context, blocks until it completes (or is cancelled), and may return an error.

The implementation of a process is a function of type proc.Impl, though implementors of processes need not import this package just to define such a function.

As well as some helpers that act as combinators for processors, this package also contains helpers to easily use processes in conjunction with the Task and Region concepts from the runtime/trace package.

Index

• func Main(impl Impl) error
• type Impl
  • func Concurrent(impls ...Impl) Impl
  • func ConcurrentGroup(impls ...Impl) Impl
  • func Sequence(impls ...Impl) Impl
  • func Task(taskType string, impl Impl) Impl
  • func TraceRegion(regionType string, impl Impl) Impl
• type MultiError
  • func (errs MultiError) Error() string
• type TaskError
  • func (err TaskError) Cause() error
  • func (err TaskError) Error() string

Functions

func Main

func Main(impl Impl) error

Main is a helper for running a process as main purpose of a program. It is an opinionated function primarily aimed at long-running processes inside similarly-long-running daemon-type programs.

Main starts a process with the given implementation and then blocks until it is completed. If an interrupt signal (os.Interrupt) is recieved while the process is running then it will be cancelled via its context. Therefore process implementations used with this function should exit cleanly but promptly when cancelled.

If the process returns any error when it exits, Main returns that error verbatim to be handled by the caller.

Types

type Impl

type Impl func(ctx context.Context) error

Impl is the type for a process's implementation function.

Long-running processes should watch for the given Context signalling "done" and exit as soon as possible.

A process implementation can return an error if it is unable to complete its task successfully. Use normal Go error patterns. Some of the process combinators in this package have special behaviors for when a process returns an error.

func Concurrent

func Concurrent(impls ...Impl) Impl

Concurrent returns a process implementation that runs concurrently all of the given process implementations, blocking until they all complete, and returning any errors.

If more than one process returns an error, the result is a MultiError containing all of them in an undefined order.

func ConcurrentGroup

func ConcurrentGroup(impls ...Impl) Impl

ConcurrentGroup is similar to concurrent but treats the given implementations as a cooperating group: if any of the processes returns an error then it will signal all of the others to cancel (via their contexts) and wait for them to complete before returning.

ConcurrentGroup also cancels process contexts before returning on the happy path (no errors), so that all child processes are guaranteed cancelled before this function returns. (There may still be goroutines spawned from those processes that do not respond to cancellation, though.)

This could be useful for managing a set of long-running processes at the top level of a program where the program should bail out quickly if any of the processes fail. In that situation, process implementations should be designed to recover from problems where possible and only return errors if they encounter unrecoverable problems that prevent continued system operation.

func Sequence

func Sequence(impls ...Impl) Impl

Sequence returns a process implementation that runs all of the given implementations in sequence, returning early if any of them return an error.

If an error is returned, it's the error from the first process that failed, and any subsequent implementations were not started at all. If no error is returned then all of the processes ran to completion successfully.

func Task

func Task(taskType string, impl Impl) Impl

Task wraps a process implementation and gives it two new behaviors:

Firstly, it creates a new Task from the runtime/trace package and runs the given implementation in its context.

Secondly, if the process returns any error then it will be wrapped in a TaskError before returning it, allowing a caller that is using one of the combinator functions from this package to recognize the type of task that failed.

func TraceRegion

func TraceRegion(regionType string, impl Impl) Impl

TraceRegion creates a process implementation that runs the given implementation in the context of a Region from the runtime/trace package.

type MultiError

type MultiError []error

MultiError is an error implementation that wraps a number of other errors that occurred together.

func (MultiError) Error

func (errs MultiError) Error() string

type TaskError

type TaskError struct {
	TaskType string
	Err      error
}

TaskError is an error type that wraps another error and annotates it with a task type name. This error type is returned from process implementations created with function Task.

func (TaskError) Cause

func (err TaskError) Cause() error

Cause returns the error that was returned by the task's underlying process implementation.

func (TaskError) Error

func (err TaskError) Error() string