package supervisor

Import Path
	go.pact.im/x/supervisor (on go.dev)

Dependency Relation
	imports 9 packages, and imported by 0 packages

Involved Source Files

	      errors.go
	      options.go
	      restart.go
	      startstop.go
	   #d supervisor.go
		Package supervisor provides a supervisor implementation for starting,
		stopping, and monitoring its child processes.

	      table.go
Package-Level Type Names (total 5, in which 4 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Iterator[K, V] (interface)

		Type Parameters:
			K: comparable
			V: any

		Iterator iterates over key and value pairs in the Table. It follows the
		semantics of the standard sql.Rows type and does not necessarily correspond
		to any consistent snapshot of the Table’s contents.

		Methods (total 4, all are exported)
			( Iterator[K, V]) Close() error
				Close closes the iterator.

			( Iterator[K, V]) Err() error
				Err returns any error that occurred during iteration.

			( Iterator[K, V]) Get(ctx context.Context) (K, V, error)
				Get returns the key and value for the current iteration.

			( Iterator[K, V]) Next() bool
				Next prepares the value for the next iteration. It returns true on
				success, and false if there is no next value. Consult Err to check
				whether iterator successfully reached the end or an error occurred.

		Implements (at least one exported)
			 Iterator : io.Closer
		As Outputs Of (at least one exported)
			func Table[K, V].Iter(ctx context.Context) (Iterator[K, V], error)

	 type Options (struct)
		Options is a set of options for supervisor constructor.

		Fields (only one, which is exported)
			Clock *clock.Clock
				Clock is the clock to use. Defaults to system clock.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*Options) setDefaults()
				setDefaults sets default values for unspecified options.

		As Inputs Of (at least one exported)
			func NewSupervisor[K, P](t Table[K, P], o Options) *Supervisor[K, P]

	 type Supervisor[K, P] (struct)

		Type Parameters:
			K: comparable
			P: process.Runnable

		Supervisor is responsible for starting, stopping, and monitoring its child
		processes.

		Fields (total 8, none are exported)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			clock *clock.Clock
			parent context.Context
				parent is the parent context for all processes. It is set to the
				context passed to Run method and is guarded by startMu.

			processes syncx.Map[K, *managedProcess[P]]
				processes is a map of managed processes. It is used to track process
				state and allows returning an ErrProcessExists error to guarantee
				that at most one processes is active per key.

			runLock syncx.Lock
				runLock ensures that at most one Run method is executing at a time.

			start bool
			startMu sync.RWMutex
				startMu guards startProcess and startProcessForKey calls when
				Supervisor is not running. It also allows waiting for the ongoing
				calls to complete on shutdown.

			table Table[K, P]
			wg sync.WaitGroup
				wg is the wait group for running processes and watchdogs. It is
				indirectly guarded by startMu and start.

		Methods (total 16, in which 5 are exported)
			(*Supervisor[K, P]) Get(ctx context.Context, pk K) (P, error)
				Get returns a running process or either a ErrProcessNotFound error if the
				process does not exist or ErrProcessNotRunning is the process exists but is
				not running.

			(*Supervisor[K, P]) Keys() []K
				Keys returns a list of all process keys.

			(*Supervisor[K, P]) Run(ctx context.Context, callback process.Callback) error
				Run starts the supervisor and executes callback on successful initialization.

			(*Supervisor[K, P]) Start(ctx context.Context, pk K) (P, error)
				Start starts the process with the given key from the table. It returns
				ErrNotRunning if the supervisor is not running and ErrProcessExists if the
				process already exists. Otherwise it returns an error from process
				initialization.

			(*Supervisor[K, P]) Stop(ctx context.Context, pk K) error
				Stop stops the process with the given key. It returns ErrProcessNotFound if
				the process does not exist, and an error from running the process otherwise.

			/* 11 unexporteds ... *//* 11 unexporteds: */
			(*Supervisor[K, P]) restart(ctx context.Context, wait time.Duration) error
				restart starts processes from the table that are not currently running.

				If wait duration is not zero, it waits until background startProcess calls
				complete. This allows ensuring that we restore at least partial state in
				restoreInitial before invoking Supervisor’s Run callback.

			(*Supervisor[K, P]) restartInitial(ctx context.Context)
				restartInitial restores the last state from the underlying table.

			(*Supervisor[K, P]) restartLoop(ctx context.Context)
				restartLoop runs a loop that calls restart.

			(*Supervisor[K, P]) restartProcessInBackground(ctx context.Context, pk K, r P) <-chan struct{}
				restartProcessInBackground starts the process for the given key in the
				background. It returns a channel that is closed when startProcess call
				completes.

			(*Supervisor[K, P]) spawnRestartLoop(ctx context.Context) func()
				spawnRestartLoop spawns a restartLoop using the given context and returns
				a function that stops restart loop and waits completion.

			(*Supervisor[K, P]) startProcess(ctx context.Context, pk K, r P) (*managedProcess[P], error)
				startProcess starts the process for the given key. Unlike startProcessForKey,
				it uses the given r Runnable instance instead of getting it from the table.

			(*Supervisor[K, P]) startProcessForKey(ctx context.Context, pk K) (*managedProcess[P], error)
				startProcessForKey starts the process for the given key. An error is returned
				if Supervisor’s Run method is not currently running.

			(*Supervisor[K, P]) startProcessUnlocked(ctx context.Context, pk K, r P) (*managedProcess[P], error)
				startProcessUnlocked starts the given process assuming that the start lock
				was acquired and an entry in the processes map exists. It removes this entry
				on error.

			(*Supervisor[K, P]) stopAll(ctx context.Context)
				stopAll stops all the processes in the underlying map. It does not wait for
				processes to complete the termination.

			(*Supervisor[K, P]) stopProcess(ctx context.Context, pk K) error
				stopProcess stops the process with the given key. If the processes does not
				exist, it returns ErrProcessNotFound.

			(*Supervisor[K, P]) watchdog(pk K, p *managedProcess[P])
				watchdog waits for process shutdown and removes it from processes map on such
				event.

		Implements (at least one exported)
			*Supervisor : go.pact.im/x/process.Runnable
		As Outputs Of (at least one exported)
			func NewSupervisor[K, P](t Table[K, P], o Options) *Supervisor[K, P]

	 type Table[K, V] (interface)

		Type Parameters:
			K: comparable
			V: any

		Table defines a table of key and value pairs that is potentially backed by a
		persistent and shared storage.

		Methods (total 2, both are exported)
			( Table[K, V]) Get(ctx context.Context, key K) (V, error)
				Get returns the value for the given key.

			( Table[K, V]) Iter(ctx context.Context) (Iterator[K, V], error)
				Iter returns an iterator for key and value pairs in the table.

		As Inputs Of (at least one exported)
			func NewSupervisor[K, P](t Table[K, P], o Options) *Supervisor[K, P]

	/* one unexported ... *//* one unexported: */
	 type managedProcess[P] (struct)

		Type Parameters:
			P: process.Runnable

		managedProcess contains a process.Process and associated process.Runnable
		managed by Supervisor.

		Fields (total 11, in which 1 are exported)
			Process *process.Process
			/* 10 unexporteds ... *//* 10 unexporteds: */
			proc P
				proc is the underlying process instance with parametrized P type.

			Process.cancel context.CancelFunc
			Process.done chan struct{}
			Process.err atomic.Error
			Process.parent context.Context
			Process.proc process.Runnable
			Process.state process.State
			Process.stateMu sync.Mutex
			Process.stop chan struct{}
			stopped atomic.Bool
				stopped is used by Supervisor to remove the process instance from
				internal map at most once.

		Methods (total 6, in which 5 are exported)
			( managedProcess) Done() <-chan struct{}
				Done returns a channel that is closed when process terminates.

			( managedProcess) Err() error
				Err returns the error from running the process.

			( managedProcess) Start(ctx context.Context) error
				Start starts the process or cancels the underlying process context on error.

				The startup deadline may be set using the given ctx context. Note that the
				context would not be used by process directly so the associated values are
				not propagated.

				It returns ErrProcessInvalidState if the process is not in the initial state.

			( managedProcess) State() process.State
				State returns the current process state.

			( managedProcess) Stop(ctx context.Context) error
				Stop stops the process by returning from the Run method callback and waiting
				for the termination.

				The shutdown deadline may be set using the given ctx context. If the deadline
				is exceeded, underlying context is canceled, signaling a forced shutdown to
				the process.

				It returns ErrProcessInvalidState if the process was not started or has
				already been stopped.

			/* one unexported ... *//* one unexported: */
			( managedProcess) transition(next process.State, advance func()) bool
				transition advances to the next process state. It returns false if there is
				not transition from the current to the given next state.

		As Outputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func (*Supervisor)[K, P].startProcess(ctx context.Context, pk K, r P) (*managedProcess[P], error)
			func (*Supervisor)[K, P].startProcessForKey(ctx context.Context, pk K) (*managedProcess[P], error)
			func (*Supervisor)[K, P].startProcessUnlocked(ctx context.Context, pk K, r P) (*managedProcess[P], error)
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func (*Supervisor)[K, P].watchdog(pk K, p *managedProcess[P])


Package-Level Functions (only one, which is exported)

	 func NewSupervisor[K, P](t Table[K, P], o Options) *Supervisor[K, P]

		Type Parameters:
			K: comparable
			P: process.Runnable

		NewSupervisor returns a new Supervisor instance. The given table is used to
		lookup managed processes and periodically restart failed units (or processes
		that were added externally). Managed processes are uniquely identifiable by
		key.

		A managed process may remove itself from the Supervisor by deleting the
		associated entry from the table before terminating. Likewise, to stop a
		process, it must be removed from the table prior to Stop call. That is,
		processes must be aware of being managed and the removal is tighly coupled
		with the table.

		As a rule of thumb, to keep the underlying table consistent, processes should
		not be re-added to table after being removed from the table. It is possible
		to implement re-adding on top of the Supervisor but that requires handling
		possible orderings of table removal, addition, re-addition and process
		startup, shutdown and self-removal (or a subset of these operations depending
		on the use cases).


Package-Level Variables (total 4, all are exported)

	  var ErrNotRunning error
		ErrNotRunning is an error that is returned when a process
		supervisor temporarily unavailable (i.e. it is not running).

	  var ErrProcessExists error
		ErrProcessExists is an error that is returned if the process already
		exists for the given ID.

	  var ErrProcessNotFound error
		ErrProcessNotFound is an error that is returned if the requested
		process was not found.

	  var ErrProcessNotRunning error
		ErrProcessNotRunning is an error that is returned when a process is
		not running (i.e. exists but is in the starting state).


Package-Level Constants (total 3, none are exported)

	/* 3 unexporteds ... *//* 3 unexporteds: */
	const restartInitialWait time.Duration = 1000000000
	const restartLoopInterval time.Duration = 60000000000
	const restartLoopWait = 0

The pages are generated with Golds v0.4.9. (GOOS=linux GOARCH=amd64)