jasper

package module
v0.0.0-...-3a047a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2024 License: Apache-2.0 Imports: 44 Imported by: 27

README 

========================================
``jasper`` -- Process Management Service
========================================

Overview
--------

Jasper is a library for managing groups of processes in the context of
test automation, and is a component of `Evergreen
<https://github.com/evergreen-ci/evergreen>`_ and related tools.

Documentation
-------------

The core API documentation is in the `godoc
<https://godoc.org/github.com/mongodb/jasper/>`_.

Until there's documentation of the REST and gRPC interfaces, you can use
the `rest interface declaration
<https://github.com/mongodb/jasper/blob/master/remote/rest_service.go>`_
and the `proto file
<https://github.com/mongodb/jasper/blob/master/jasper.proto>`_.

Documentation

Index

Constants

View Source 
const (
	// EnvironID is the environment variable that is set on all processes. The
	// value of this environment variable is always the ID of the process.
	EnvironID = "JASPER_ID"

	// ManagerEnvironID is the environment variable that is set on
	// all managed process that always identifies the process'
	// manager. Used for process tracking and forensics.
	ManagerEnvironID = "JASPER_MANAGER"

	// DefaultCachePruneDelay is the duration between LRU cache prunes.
	DefaultCachePruneDelay = 10 * time.Second
	// DefaultMaxCacheSize is the maximum allowed size of the LRU cache.
	DefaultMaxCacheSize = 1024 * 1024 * 1024
)

Variables

View Source 
var ErrCachedLoggerNotFound = errors.New("logger not found")

ErrCachedLoggerNotFound indicates that a logger was not found in the cache.

Functions

func GetInMemoryLogStream 

func GetInMemoryLogStream(ctx context.Context, proc Process, count int) ([]string, error)

GetInMemoryLogStream gets at most count logs from the in-memory output logs for the given Process proc. If the process has not been called with Process.Wait(), this is not guaranteed to produce all the logs. This function assumes that there is exactly one in-memory logger attached to this process's output. It returns io.EOF if the stream is done. For remote interfaces, this function will not work; use (remote.Manager).GetLogStream() instead.

func Kill 

func Kill(ctx context.Context, p Process) error

Kill sends a SIGKILL signal to the given process under the given context. This guarantees that the process will die. This function does not Wait() on the given process upon sending the signal.

func KillAll 

func KillAll(ctx context.Context, procs []Process) error

KillAll sends a SIGKILL signal to each of the given processes under the given context. This guarantees that each process will actually die. This function calls Wait() on each process after sending them SIGKILL signals. Use Kill() in a loop if you do not wish to potentially hang on Wait().

func NewInMemoryLogger 

func NewInMemoryLogger(maxSize int) (*options.LoggerConfig, error)

NewInMemoryLogger is a basic constructor that constructs a logger configuration for plain formatted in-memory buffered logger. The logger will capture up to maxSize messages.

func RegisterJobs 

func RegisterJobs(pc ProcessConstructor)

RegisterJobs adds factories for the job types provided by these packages to make it possible to dispatch these jobs to a remote/distributed queue.

func RegisterSignalTriggerFactory 

func RegisterSignalTriggerFactory(id SignalTriggerID, factory SignalTriggerFactory) error

RegisterSignalTriggerFactory registers a factory to create the signal trigger represented by the id.

func SetupDownloadMongoDBReleases 

func SetupDownloadMongoDBReleases(ctx context.Context, cache *lru.Cache, opts options.MongoDBDownload) error

SetupDownloadMongoDBReleases performs necessary setup to download MongoDB with the given options.

func SignalEvent 

func SignalEvent(context.Context, string) error

SignalEvent is a no-op on Unix-based systems.

func Terminate 

func Terminate(ctx context.Context, p Process) error

Terminate sends a SIGTERM signal to the given process under the given context. This does not guarantee that the process will actually die. This function does not Wait() on the given process upon sending the signal.

func TerminateAll 

func TerminateAll(ctx context.Context, procs []Process) error

TerminateAll sends a SIGTERM signal to each of the given processes under the given context. This does not guarantee that each process will actually die. This function calls Wait() on each process after sending them SIGTERM signals. On Windows, this function sends a SIGKILL instead of SIGTERM. Use Terminate() in a loop if you do not wish to potentially hang on Wait().

Types

type Command 

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

Command objects allow a quick and lightweight interface for firing off ad-hoc processes for smaller tasks. Command immediately supports features such as output and error functionality and remote execution. Command methods are not thread-safe.

func BuildCommand 

func BuildCommand(id string, pri level.Priority, args []string, dir string, env map[string]string) *Command

BuildCommand builds the Command given the configuration of arguments.

func BuildCommandGroup 

func BuildCommandGroup(id string, pri level.Priority, cmds [][]string, dir string, env map[string]string) *Command

BuildCommandGroup runs the group of sub-commands given the configuration of arguments.

func BuildCommandGroupContinueOnError 

func BuildCommandGroupContinueOnError(id string, pri level.Priority, cmds [][]string, dir string, env map[string]string) *Command

BuildCommandGroupContinueOnError runs the group of sub-commands given the configuration of arguments, continuing execution despite any errors.

func BuildRemoteCommand 

func BuildRemoteCommand(id string, pri level.Priority, host string, args []string, dir string, env map[string]string) *Command

BuildRemoteCommand builds the Command remotely given the configuration of arguments.

func BuildRemoteCommandGroup 

func BuildRemoteCommandGroup(id string, pri level.Priority, host string, cmds [][]string, dir string) *Command

BuildRemoteCommandGroup runs the group of sub-commands remotely given the configuration of arguments.

func BuildRemoteCommandGroupContinueOnError 

func BuildRemoteCommandGroupContinueOnError(id string, pri level.Priority, host string, cmds [][]string, dir string) *Command

BuildRemoteCommandGroupContinueOnError runs the group of sub-commands remotely given the configuration of arguments, continuing execution despite any errors.

func NewCommand 

func NewCommand() *Command

NewCommand returns a blank Command. New blank Commands will use basicProcess as their default Process for executing sub-commands unless it is changed via ProcConstructor().

func (*Command) Add 

func (c *Command) Add(args []string) *Command

Add adds on a sub-command.

func (*Command) AddEnv 

func (c *Command) AddEnv(k, v string) *Command

AddEnv adds a key value pair of environment variable to value into the Command's environment variable map. If this is a remote command, it sets the environment of the command being run remotely.

func (*Command) AddWhen 

func (c *Command) AddWhen(cond bool, args []string) *Command

AddWhen adds a command only when the conditional is true.

func (*Command) Append 

func (c *Command) Append(cmds ...string) *Command

Append takes a series of strings and splits them into sub-commands and adds them to the Command.

func (*Command) AppendArgs 

func (c *Command) AppendArgs(args ...string) *Command

AppendArgs is the variadic equivalent of Add, which adds a command in the form of arguments.

func (*Command) AppendArgsWhen 

func (c *Command) AppendArgsWhen(cond bool, args ...string) *Command

AppendArgsWhen is the variadic equivalent of AddWhen, which adds a command in the form of arguments only when the conditional is true.

func (*Command) AppendLoggers 

func (c *Command) AppendLoggers(l ...*options.LoggerConfig) *Command

AppendLoggers adds one or more loggers to the existing configured loggers in the command.

func (*Command) AppendTags 

func (c *Command) AppendTags(t ...string) *Command

AppendTags adds the specified tags to the existing tag slice. Tags are used to filter process with the manager.

func (*Command) AppendWhen 

func (c *Command) AppendWhen(cond bool, cmds ...string) *Command

AppendWhen adds a sequence of subcommands to the Command only when the conditional is true.

func (*Command) ApplyFromOpts 

func (c *Command) ApplyFromOpts(opts *options.Create) *Command

ApplyFromOpts uses the options.Create to configure the Command. All existing options will be overwritten. Use of this function is discouraged unless all desired options are populated in the given opts. If Args is set on the options.Create, it will be ignored; the command arguments can be added using Add, Append, AppendArgs, or Extend.

func (*Command) Background 

func (c *Command) Background(runBackground bool) *Command

Background allows you to set the command to run in the background when you call Run(), the command will begin executing but will not complete when run returns.

func (*Command) Bash 

func (c *Command) Bash(script string) *Command

Bash adds a script using "bash -c", as syntactic sugar for the ShellScript2 method.

func (*Command) BashWhen 

func (c *Command) BashWhen(cond bool, script string) *Command

BashWhen adds a bash script only when the conditional is true.

func (*Command) Close 

func (c *Command) Close() error

Close closes this command and its resources.

func (*Command) ContinueOnError 

func (c *Command) ContinueOnError(cont bool) *Command

ContinueOnError sets a flag for determining if the Command should continue executing its sub-commands even if one of them errors.

func (*Command) Directory 

func (c *Command) Directory(d string) *Command

Directory sets the working directory. If this is a remote command, it sets the working directory of the command being run remotely.

func (*Command) Enqueue 

func (c *Command) Enqueue(ctx context.Context, q amboy.Queue) error

Enqueue adds separate jobs to the queue for every operation captured in the command. These operations will execute in parallel. The output of the operations is captured in the body of the job.

func (*Command) EnqueueForeground 

func (c *Command) EnqueueForeground(ctx context.Context, q amboy.Queue) error

EnqueueForeground adds separate jobs to the queue for every operation captured in the command. These operations will execute in parallel. The output of the commands are logged, using the default grip sender in the foreground.

func (*Command) Environment 

func (c *Command) Environment(e map[string]string) *Command

Environment replaces the current environment map with the given environment map. If this is a remote command, it sets the environment of the command being run remotely.

func (*Command) Export 

func (c *Command) Export() ([]*options.Create, error)

Export returns all of the options.Create that will be used to spawn the processes that run all subcommands.

func (*Command) Extend 

func (c *Command) Extend(cmds [][]string) *Command

Extend adds on multiple sub-commands.

func (*Command) ExtendLoggers 

func (c *Command) ExtendLoggers(l []*options.LoggerConfig) *Command

ExtendLoggers takes the existing slice of loggers and adds that to any existing configuration.

func (*Command) ExtendRemoteArgs 

func (c *Command) ExtendRemoteArgs(args ...string) *Command

ExtendRemoteArgs allows you to add arguments, when needed, to the Password sets the password in order to authenticate to a remote host. underlying ssh command, for remote commands.

func (*Command) ExtendTags 

func (c *Command) ExtendTags(t []string) *Command

ExtendTags adds all tags in the specified slice to the tags will be added to the process after creation. Tags are used to filter process with the manager.

func (*Command) ExtendWhen 

func (c *Command) ExtendWhen(cond bool, cmds [][]string) *Command

ExtendWhen adds on multiple sub-commands, only when the conditional is true.

func (*Command) GetProcIDs 

func (c *Command) GetProcIDs() []string

GetProcIDs returns an array of Process IDs associated with the sub-commands being run. This method will return a nil slice until processes have actually been created by the Command for execution.

func (*Command) Host 

func (c *Command) Host(h string) *Command

Host sets the hostname for connecting to a remote host.

func (*Command) ID 

func (c *Command) ID(id string) *Command

ID sets the ID of the Command, which is independent of the IDs of the subcommands that are executed.

func (*Command) IgnoreError 

func (c *Command) IgnoreError(ignore bool) *Command

IgnoreError sets a flag for determining if the Command should return a nil error despite errors in its sub-command executions.

func (*Command) Jobs 

func (c *Command) Jobs(ctx context.Context) ([]amboy.Job, error)

Jobs returns a slice of jobs for every operation in the command. The output of the commands are captured in the body of the job.

func (*Command) JobsForeground 

func (c *Command) JobsForeground(ctx context.Context) ([]amboy.Job, error)

JobsForeground returns a slice of jobs for every operation captured in the command. The output of the commands are logged, using the default grip sender in the foreground.

func (*Command) PostHook 

func (c *Command) PostHook(h options.CommandPostHook) *Command

PostHook allows you to add a function that runs (locally) after the each subcommand in the Command completes. When specified, the PostHook can override or annotate any error produced by the command execution. The error returned is subject to the IgnoreError options. The PostHook is not run when using SetRunFunction.

func (*Command) PreHook 

func (c *Command) PreHook(fn options.CommandPreHook) *Command

PreHook allows you to add a function that runs (locally) before each subcommand executes, and allows you to log or modify the creation option. The PreHook is not run when using SetRunFunction.

func (*Command) Prerequisite 

func (c *Command) Prerequisite(chk func() bool) *Command

Prerequisite sets a function on the Command such that the Command will only execute if the function returns true. The Prerequisite function runs once per Command object regardless of how many subcommands are present. Prerequsite functions run even if the command's RunFunction is set.

func (*Command) Priority 

func (c *Command) Priority(l level.Priority) *Command

Priority sets the logging priority.

func (*Command) ProcConstructor 

func (c *Command) ProcConstructor(processConstructor ProcessConstructor) *Command

ProcConstructor returns a blank Command that will use the process created by the given ProcessConstructor.

func (*Command) RedirectErrorToOutput 

func (c *Command) RedirectErrorToOutput(v bool) *Command

RedirectErrorToOutput sets a flag for determining if the Command should send all standard error content to standard output.

func (*Command) RedirectOutputToError 

func (c *Command) RedirectOutputToError(v bool) *Command

RedirectOutputToError sets a flag for determining if the Command should send all standard output content to standard error.

func (*Command) Run 

func (c *Command) Run(ctx context.Context) error

Run starts and then waits on the Command's execution.

func (*Command) RunParallel 

func (c *Command) RunParallel(ctx context.Context) error

RunParallel is the same as Run(), but will run all sub-commands in parallel. Use of this function effectively ignores the ContinueOnError flag.

func (*Command) SetCombinedSender 

func (c *Command) SetCombinedSender(l level.Priority, s send.Sender) *Command

SetCombinedSender is the combination of SetErrorSender() and SetOutputSender().

func (*Command) SetCombinedWriter 

func (c *Command) SetCombinedWriter(writer io.WriteCloser) *Command

SetCombinedWriter is the combination of SetErrorWriter() and SetOutputWriter().

func (*Command) SetErrorSender 

func (c *Command) SetErrorSender(l level.Priority, s send.Sender) *Command

SetErrorSender sets a Sender to be used by this Command for its output to stderr.

func (*Command) SetErrorWriter 

func (c *Command) SetErrorWriter(writer io.WriteCloser) *Command

SetErrorWriter sets a Writer to be used by this Command for its output to stderr.

func (*Command) SetGroupLeader 

func (c *Command) SetGroupLeader() *Command

SetGroupLeader marks the command as a group leader so when the process is started the pgid is set to the process's pid. This is a noop for remote and non-unix commands.

func (*Command) SetInput 

func (c *Command) SetInput(r io.Reader) *Command

SetInput sets the standard input.

func (*Command) SetInputBytes 

func (c *Command) SetInputBytes(b []byte) *Command

SetInputBytes is the same as SetInput but sets b as the bytes to be read from standard input.

func (*Command) SetLoggers 

func (c *Command) SetLoggers(l []*options.LoggerConfig) *Command

SetLoggers sets the logging output on this command to the specified slice. This removes any loggers previously configured.

func (*Command) SetOutputOptions 

func (c *Command) SetOutputOptions(opts options.Output) *Command

SetOutputOptions sets the output options for a command. This overwrites an existing output options.

func (*Command) SetOutputSender 

func (c *Command) SetOutputSender(l level.Priority, s send.Sender) *Command

SetOutputSender sets a Sender to be used by this Command for its output to stdout.

func (*Command) SetOutputWriter 

func (c *Command) SetOutputWriter(writer io.WriteCloser) *Command

SetOutputWriter sets a Writer to be used by this Command for its output to stdout.

func (*Command) SetRemoteOptions 

func (c *Command) SetRemoteOptions(opts *options.Remote) *Command

SetRemoteOptions sets the configuration for remote operations. This overrides any existing remote configuration.

func (*Command) SetRunFunc 

func (c *Command) SetRunFunc(f func(options.Command) error) *Command

SetRunFunc sets the function that overrides the default behavior when a command is run, allowing the caller to run the command with their own custom function given all the given inputs to the command.

func (*Command) SetTags 

func (c *Command) SetTags(tags []string) *Command

SetTags overrides any existing tags for a process with the specified list. Tags are used to filter process with the manager.

func (*Command) Sh 

func (c *Command) Sh(script string) *Command

Sh adds a script using "sh -c", as syntactic sugar for the ShellScript method.

func (*Command) ShWhen 

func (c *Command) ShWhen(cond bool, script string) *Command

ShWhen adds a shell script (e.g. "sh -c") only when the conditional is true.

func (*Command) ShellScript 

func (c *Command) ShellScript(shell, script string) *Command

ShellScript adds an operation to the command that runs a shell script, using the shell's "-c" option).

func (*Command) ShellScriptWhen 

func (c *Command) ShellScriptWhen(cond bool, shell, script string) *Command

ShellScriptWhen a shell script option only when the conditional of true.

func (*Command) String 

func (c *Command) String() string

String returns a stringified representation.

func (*Command) Sudo 

func (c *Command) Sudo(sudo bool) *Command

Sudo runs each command with superuser privileges with the default target user. This will cause the commands to fail if the commands are executed in Windows. If this is a remote command, the command being run remotely uses superuser privileges.

func (*Command) SudoAs 

func (c *Command) SudoAs(user string) *Command

SudoAs runs each command with sudo but allows each command to be run as a user other than the default target user (usually root). This will cause the commands to fail if the commands are executed in Windows. If this is a remote command, the command being run remotely uses superuser privileges.

func (*Command) SuppressStandardError 

func (c *Command) SuppressStandardError(v bool) *Command

SuppressStandardError sets a flag for determining if the Command should discard all standard error content.

func (*Command) SuppressStandardOutput 

func (c *Command) SuppressStandardOutput(v bool) *Command

SuppressStandardOutput sets a flag for determining if the Command should discard all standard output content.

func (*Command) User 

func (c *Command) User(u string) *Command

User sets the username for connecting to a remote host.

func (*Command) Wait 

func (c *Command) Wait(ctx context.Context) (int, error)

Wait returns the exit code and error waiting for the underlying process to complete. For commands run with RunParallel, Wait only returns a zero exit code if all the underlying processes return exit code zero; otherwise, it returns a non-zero exit code. Similarly, it will return a non-nil error if any of the underlying processes encounter an error while waiting.

type Job 

type Job amboy.Job

Job is an alias for an amboy.Job

func NewJob 

func NewJob(pc ProcessConstructor, cmd string) Job

NewJob constructs an amboy job that wraps a provided ProcessConstructor. The identifier of the job includes a hash of the command, so running the same command repeatedly may result in job collisions.

Pass the process constructor to allow the amboy jobs to manipulate processes in an existing Manager.

func NewJobBasic 

func NewJobBasic(cmd string) Job

NewJobBasic constructs an amboy job that uses jasper process management internally. The identifier of the job includes a hash of the command, so running the same command repeatedly may result in job collisions.

func NewJobBasicExtended 

func NewJobBasicExtended(cmd string, env map[string]string, wd string) Job

NewJobBasicExtended builds a job that creates a process with environment variables and a working directory defined. The identifier of the job includes a hash of the command, so running the same command repeatedly may result in job collisions.

func NewJobBasicForeground 

func NewJobBasicForeground(opts *options.Create) Job

NewJobBasicForeground creates an amboy job that writes all output linewise to the current processes global grip logging instance with error and output separated by level.

func NewJobExtended 

func NewJobExtended(pc ProcessConstructor, cmd string, env map[string]string, wd string) Job

NewJobExtended builds a job that creates a process with environment variables and a working directory defined. The identifier of the job includes a hash of the command, so running the same command repeatedly may result in job collisions.

Pass the process constructor to allow the amboy jobs to manipulate processes in an existing Manager.

func NewJobForeground 

func NewJobForeground(pc ProcessConstructor, opts *options.Create) Job

NewJobForeground creates an amboy job that writes all output linewise to the current processes global grip logging instance with error and output separated by level.

Pass the process constructor to allow the amboy jobs to manipulate processes in an existing Manager.

func NewJobOptions 

func NewJobOptions(pc ProcessConstructor, opts *options.Create) Job

NewJobOptions creates a new job using the options to define the parameters of the job. The identifier of the job is the hash of the options structure.

Pass the process constructor to allow the amboy jobs to manipulate processes in an existing Manager.

type LogStream 

type LogStream struct {
	Logs []string `bson:"logs,omitempty" json:"logs,omitempty"`
	Done bool     `bson:"done" json:"done"`
}

LogStream represents the output of reading the in-memory log buffer as a stream, containing the logs (if any) and whether or not the stream is done reading.

type LoggingCache 

type LoggingCache interface {
	// Create creates and caches a new logger based on the given output options.
	// If a logger with the given ID already exists, implementations should
	// return an error.
	Create(id string, opts *options.Output) (*options.CachedLogger, error)
	// Put adds an existing logger to the cache.
	Put(id string, logger *options.CachedLogger) error
	// Get gets an existing cached logger. Implementations should return an
	// error if the logger cannot be found.
	Get(id string) (*options.CachedLogger, error)
	// Remove removes an existing logger from the logging cache without closing
	// it. Implementations should return an error if no such logger exists.
	Remove(id string) error
	// CloseAndRemove closes and removes an existing logger from the logging
	// cache. If it fails to close the logger, implementations should not remove
	// it from the cache.
	CloseAndRemove(ctx context.Context, id string) error
	// Clear attempts to close and remove all loggers in the logging cache. It
	// will only remove loggers that are successfully closed.
	Clear(ctx context.Context) error
	// Prune closes and removes all loggers that were last accessed before the
	// given timestamp.
	Prune(lastAccessed time.Time) error
	// Len returns the number of loggers. Implementations should return
	// -1 if the length cannot be retrieved successfully.
	Len() (int, error)
}

LoggingCache provides an interface to a cache of loggers.

func NewLoggingCache 

func NewLoggingCache() LoggingCache

NewLoggingCache produces a thread-safe implementation of a local logging cache.

type Manager 

type Manager interface {
	ID() string
	CreateProcess(context.Context, *options.Create) (Process, error)
	CreateCommand(context.Context) *Command
	Register(context.Context, Process) error

	List(context.Context, options.Filter) ([]Process, error)
	Group(context.Context, string) ([]Process, error)
	Get(context.Context, string) (Process, error)
	Clear(context.Context)
	Close(context.Context) error

	LoggingCache(context.Context) LoggingCache
	WriteFile(ctx context.Context, opts options.WriteFile) error
}

Manager provides a basic, high level process management interface for processes, and supports creation and introspection. External interfaces and remote management tools can be implemented in terms of this interface.

func MakeSynchronizedManager 

func MakeSynchronizedManager(mngr Manager) Manager

MakeSynchronizedManager wraps the given manager in a thread-safe Manager, which also uses thread-safe processes.

func NewRemoteManager 

func NewRemoteManager(m Manager, remote *options.Remote) Manager

NewRemoteManager builds a remote manager that wraps an existing manager, but creates all commands with the specified remote options. Commands and processes with non-nil remote options will run over SSH.

func NewSelfClearingProcessManager 

func NewSelfClearingProcessManager(maxProcs int, trackProcs bool) (Manager, error)

NewSelfClearingProcessManager creates and returns a process manager that places a limit on the number of concurrent processes stored by Jasper at any given time, and will clear itself of dead processes when necessary without the need for calling Clear() from the user. Clear() can, however, be called proactively. This manager therefore gives no guarantees on the persistence of a process in its memory that has already completed.

The self clearing process manager is not thread safe. Wrap with the synchronized process manager for multithreaded use.

func NewSynchronizedManager 

func NewSynchronizedManager(trackProcs bool) (Manager, error)

NewSynchronizedManager is a constructor for a thread-safe basic Manager.

type ManagerTestCase 

type ManagerTestCase struct {
	Name string
	Case func(context.Context, *testing.T, Manager, testoptions.ModifyOpts)
}

ManagerTestCase represents a test case including a manager and options.ModifyOpts to modify process creation options.

func ManagerTests 

func ManagerTests() []ManagerTestCase

ManagerTests returns the common test suite for the Manager interface. This should be used for testing purposes only.

type OOMTracker 

type OOMTracker interface {
	Check(context.Context) error
	Clear(context.Context) error
	Report() ([]string, []int)
}

OOMTracker provides a tool for detecting if there have been OOM events on the system. The Clear operation may affect the state the system logs and the data reported will reflect the entire system, not simply processes managed by Jasper tools.

func NewOOMTracker 

func NewOOMTracker() OOMTracker

NewOOMTracker returns an implementation of the OOMTracker interface for the current platform.

type Process 

type Process interface {
	// Returns a UUID for the process. Use this ID to retrieve
	// processes from managers using the Get method.
	ID() string

	// Info returns a copy of a structure that reports the current
	// state of the process. If the context is canceled or there
	// is another error, an empty struct may be returned.
	Info(context.Context) ProcessInfo

	// Running provides a quick predicate for checking to see if a
	// process is running.
	Running(context.Context) bool
	// Complete provides a quick predicate for checking if a
	// process has finished.
	Complete(context.Context) bool

	// Signal sends the specified signals to the underlying
	// process. Its error response reflects the outcome of sending
	// the signal, not the state of the process signaled.
	Signal(context.Context, syscall.Signal) error

	// Wait blocks until the process exits or the context is
	// canceled or is not properly defined. Wait will return the
	// exit code as -1 if it was unable to return a true code due
	// to some other error, but otherwise will return the actual
	// exit code of the process. Returns nil if the process has
	// completed successfully.
	//
	// Note that death by signal does not return the signal code
	// and instead is returned as -1.
	Wait(context.Context) (int, error)

	// Respawn respawns a near-identical version of the process on
	// which it is called. It will spawn a new process with the same
	// options and return the new, "respawned" process.
	//
	// However, it is not guaranteed to read the same bytes from
	// (options.Create).StandardInput as the original process; if
	// standard input must be duplicated,
	// (options.Create).StandardInputBytes should be set.
	Respawn(context.Context) (Process, error)

	// RegisterSignalTrigger associates triggers with a process,
	// which execute before the process is about to be signaled.
	RegisterSignalTrigger(context.Context, SignalTrigger) error

	// RegisterSignalTriggerID associates triggers represented by
	// identifiers with a process, which execute before
	// the process is about to be signaled.
	RegisterSignalTriggerID(context.Context, SignalTriggerID) error

	// RegisterTrigger associates triggers with a process,
	// erroring when the context is canceled, the process is
	// complete.
	RegisterTrigger(context.Context, ProcessTrigger) error

	// Tag adds a tag to a process. Implementations should avoid
	// allowing duplicate tags to exist.
	Tag(string)
	// GetTags should return all tags for a process.
	GetTags() []string
	// ResetTags should clear all existing tags.
	ResetTags()
}

Process objects reflect ways of starting and managing processes. Process generally reflect only the primary process at the top of a tree and "child" processes are not directly reflected. Process implementations either wrap Go's own process management calls (e.g. os/exec.Cmd) or may wrap remote process management tools (e.g. jasper services on remote systems.)

func NewProcess 

func NewProcess(ctx context.Context, opts *options.Create) (Process, error)

NewProcess is a factory function which constructs a thread-safe standalone process outside of the context of a manager.

type ProcessConstructor 

type ProcessConstructor func(context.Context, *options.Create) (Process, error)

ProcessConstructor is a function type that, given a context.Context and a options.Create struct, returns a Process and an error.

type ProcessInfo 

type ProcessInfo struct {
	ID         string         `json:"id" bson:"id"`
	Host       string         `json:"host" bson:"host"`
	PID        int            `json:"pid" bson:"pid"`
	ExitCode   int            `json:"exit_code" bson:"exit_code"`
	IsRunning  bool           `json:"is_running" bson:"is_running"`
	Successful bool           `json:"successful" bson:"successful"`
	Complete   bool           `json:"complete" bson:"complete"`
	Timeout    bool           `json:"timeout" bson:"timeout"`
	Options    options.Create `json:"options" bson:"options"`
	StartAt    time.Time      `json:"start_at,omitempty" bson:"start_at,omitempty"`
	EndAt      time.Time      `json:"end_at,omitempty" bson:"end_at,omitempty"`
}

ProcessInfo reports on the current state of a process. It is always returned and passed by value, and reflects the state of the process when it was created.

type ProcessTestCase 

type ProcessTestCase struct {
	Name string
	Case func(context.Context, *testing.T, *options.Create, ProcessConstructor)
}

ProcessTestCase represents a test case including a constructor and options to create a process.

func ProcessTests 

func ProcessTests() []ProcessTestCase

ProcessTests returns the common test suite for the Process interface. This should be used for testing purposes only.

type ProcessTracker 

type ProcessTracker interface {
	// Add begins tracking a process identified by its ProcessInfo.
	Add(ProcessInfo) error
	// Cleanup terminates this group of processes.
	Cleanup() error
}

ProcessTracker provides a way to logically group processes that should be managed collectively. Implementation details are platform-specific since each one has its own means of managing groups of processes.

func NewProcessTracker 

func NewProcessTracker(name string) (ProcessTracker, error)

NewProcessTracker creates a cgroup for all tracked processes if supported. Cgroups functionality requires admin privileges. It also tracks the ProcessInfo for all added processes so that it can find processes to terminate in Cleanup() based on their environment variables.

type ProcessTrigger 

type ProcessTrigger func(ProcessInfo)

ProcessTrigger describes the way to write cleanup functions for processes, which provide ways of adding behavior to processes after they complete. A ProcessTrigger can read the fields within ProcessInfo.Options but should not mutate them.

type ProcessTriggerSequence 

type ProcessTriggerSequence []ProcessTrigger

ProcessTriggerSequence is simply a convenience type to simplify running more than one triggered operation.

func (ProcessTriggerSequence) Run 

func (s ProcessTriggerSequence) Run(info ProcessInfo)

Run loops over triggers and calls each of them successively.

type SignalTrigger 

type SignalTrigger func(ProcessInfo, syscall.Signal) (skipSignal bool)

SignalTrigger describes the way to write hooks that will execute before a process is about to be signaled. It returns a bool indicating if the signal should be skipped after execution of the trigger. A SignalTrigger can read the fields within ProcessInfo.Options but should not mutate them.

type SignalTriggerFactory 

type SignalTriggerFactory func() SignalTrigger

SignalTriggerFactory is a function that creates a SignalTrigger.

func GetSignalTriggerFactory 

func GetSignalTriggerFactory(id SignalTriggerID) (SignalTriggerFactory, bool)

GetSignalTriggerFactory retrieves a factory to create the signal trigger represented by the id.

type SignalTriggerID 

type SignalTriggerID string

SignalTriggerID is the unique representation of a signal trigger. 

const (
	// CleanTerminationSignalTrigger is the ID for the signal trigger to use for
	// termination of processes with exit code 0.
	CleanTerminationSignalTrigger SignalTriggerID = "clean_terminate"
)

type SignalTriggerSequence 

type SignalTriggerSequence []SignalTrigger

SignalTriggerSequence is a convenience type to simplify running more than one signal trigger.

func (SignalTriggerSequence) Run 

func (s SignalTriggerSequence) Run(info ProcessInfo, sig syscall.Signal) (skipSignal bool)

Run loops over signal triggers and calls each of them successively. It returns a boolean indicating whether or not the signal should be skipped after executing all of the signal triggers.

Source Files

View all Source files

Directories

Path Synopsis
cmd
jasper
run-benchmarks
run-linter
verify-mod-tidy
internal
executor
internal
options

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.