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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Main ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
Directories