camfish/actor.go

package camfish

import "context"

// Actor is a participant in the environment. All public methods on an actor
// must be safe for concurrent use by multiple goroutines. Additionally, any
// type which explicitly implements Actor should:
//   - Treat all public fields, values, indices, etc. as immutable
//   - Satisfy Actor as a pointer, not a value
//   - Not have a constructor
type Actor interface {
	// Type returns the type name of the actor. The value returned from this
	// is used to locate actors capable of performing a specific task, so it
	// absolutely must return the same string every time. Actors implemented
	// in packages besides this one (i.e. not camfish) must not return the
	// string "cron".
	Type() string
}

// FlagAdder is any object that can add [Flag]s to a [FlagSet]. Actors which
// implement this interface will be called upon to add flags during and only
// during the flag parsing phase.
type FlagAdder interface {
	// AddFlags adds flags to set. The object must not retain or distribute
	// any reference to set.
	AddFlags(set FlagSet)
}

// ConfigProcessor is any object that can read and modify a configuration before
// it is used. Actors which implement this interface will be called upon to
// process the config during and only during the configuration processing phase.
type ConfigProcessor interface {
	// Process processes the config.
	ProcessConfig(conf MutableConfig) error
}

// Configurable is any object that must be configured before use or
// initialization (if applicable). Actors which implement this interface will be
// configured during the configuration phase, or when they are added.
type Configurable interface {
	// Configure configures the object. It must not make any attempt to
	// modify conf, and it must not retain or distribute any reference to
	// conf.
	Configure(conf Config) error
}

// Initializable is any object that must be initialized before use. Actors which
// implement this interface will be initialized during the initialization phase,
// or when they are added.
type Initializable interface {
	// Init initializes the object. It must return before the context
	// expires, and must return ctx.Err if there is no other error to be
	// returned. If Init returns an error, the object must be treated as
	// invalid and any process which depends on it should be shut down.
	Init(ctx context.Context) error
}

// Runnable is any object with a central, long-running routine. Actors which
// implement this interface will be run after they have been initialized,
// configured, etc. (if applicable). The environment will attempt to restart
// actors if their run method fails, see the documentation for this package's
// [Run] function for details.
type Runnable interface {
	// Run runs the object. It must return when or before the context
	// expires, and must return ctx.Err if there is no other error to be
	// returned.
	Run(ctx context.Context) error
}

// Trimmable is any object that needs to have a task run every so often. This
// can be garbage collecting, sanity checking, etc. Actors which implement this
// interface will be routinely trimmed while running. See the documentation for
// this package's [Run] function for details.
type Trimmable interface {
	// Trim trims the object. It must return when or before the context
	// expires, and must return ctx.Err if there is no other error to be
	// returned.
	Trim(ctx context.Context) error
}

// Resettable is any object that must be reset after failure and before re-use.
// Actors which implement this interface will be reset after their Run method
// (if applicable) has failed and is about to be called again.
type Resettable interface {
	// Reset resets the object. It must return when or before the context
	// expires, and must return ctx.Err if there is no other error to be
	// returned. If Reset returns an error, the object must be treated as
	// invalid and any process which depends on it should be shut down.
	Reset(ctx context.Context) error
}

// RunShutdownable is any object that needs a context in order to shut down.
// Actors which implement this interface cannot implement the Runnable
// interface. This can be used to run an http.Server as an actor.
type RunShutdownable interface {
	// Run is similar to [Runnable.Run], but takes no context and blocks
	// until Shutdown has run and exited. It may also return when something
	// goes wrong and it cannot continue, in which case it must return a
	// non-nil error explaining why. Shutdown does not need to be called in
	// the latter case.
	Run() error
	// Shutdown shuts down the actor. It must unblock Run in all cases even
	// on failure, context expiration, etc. Shutdown must return when or
	// before the context expires, and must return ctx.Err if there is no
	// other error to be returned. If Shutdown returns any error, the object
	// must be treated as invalid and any other process which depends on it
	// should be shut down.
	Shutdown(ctx context.Context) error
}