plumber

package module
v4.36.0 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2023 License: MIT Imports: 30 Imported by: 2

README

plumber

Description

A library for creating quick and effective CLI applications that have the process management build inside it.

API Documentation

You can find the API documentation here.

Documentation

Index

Constants

View Source 
const (
	LOG_LEVEL_DEFAULT LogLevel = 0
	LOG_LEVEL_PANIC   LogLevel = logrus.PanicLevel
	LOG_LEVEL_FATAL   LogLevel = logrus.FatalLevel
	LOG_LEVEL_ERROR   LogLevel = logrus.ErrorLevel
	LOG_LEVEL_WARN    LogLevel = logrus.WarnLevel
	LOG_LEVEL_INFO    LogLevel = logrus.InfoLevel
	LOG_LEVEL_DEBUG   LogLevel = logrus.DebugLevel
	LOG_LEVEL_TRACE   LogLevel = logrus.TraceLevel
	LOG_FIELD_CONTEXT string   = "context"
	LOG_FIELD_STATUS  string   = "status"
)
View Source 
const CLI_FLAGS_CATEGORY = "CLI"
View Source 
const (
	COMMAND_RETRY_DELAY time.Duration = time.Second
)

Variables

View Source 
var CliDefaultFlags = []cli.Flag{
	&cli.BoolFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "ci",
		Usage:    "Sets whether this is running inside a CI/CD environment.",
		Hidden:   true,
		EnvVars:  []string{"CI"},
	},

	&cli.BoolFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "debug",
		Usage:    "Enable debugging for the application.",
		EnvVars:  []string{"DEBUG"},
		Hidden:   true,
	},

	&cli.StringFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "log-level",
		Usage:    `Define the log level for the application. enum("panic", "fatal", "warn", "info", "debug", "trace")`,
		EnvVars:  []string{"LOG_LEVEL"},
		Value:    logrus.InfoLevel.String(),
	},

	&cli.StringSliceFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "env-file",
		Usage:    "Environment files to inject.",
		EnvVars:  []string{"ENV_FILE"},
	},
}

flags for a Plumber application.

Functions

func EditCliFlag added in v4.27.1 

func EditCliFlag[Flag any](flags []cli.Flag, fn func(f Flag) bool, apply func(f Flag) Flag) []cli.Flag

func InlineTemplate added in v4.36.0 

func InlineTemplate[Ctx any](tmpl string, ctx Ctx) (string, error)

func OverwriteCliFlag added in v4.27.0 

func OverwriteCliFlag[Flag any](flags []cli.Flag, fn func(f Flag) bool, apply func(f Flag) Flag)

func ParseEnvironmentVariablesToMap added in v4.31.0 

func ParseEnvironmentVariablesToMap() map[string]string

func TemplateFuncMap added in v4.23.0 

func TemplateFuncMap() template.FuncMap

Types

type AppChannel 

type AppChannel struct {
	// to communicate the errors while not blocking
	Err chan error
	// to communicate the errors while not blocking
	CustomErr chan ErrorWithLogger
	// Fatal errors
	Fatal chan error
	// to communicate the errors while not blocking
	CustomFatal chan ErrorWithLogger
	// terminate channel
	Interrupt chan os.Signal
	// exit channel
	Exit *broadcaster.Broadcaster[int]
}

type AppEnvironment 

type AppEnvironment struct {
	Debug bool
	CI    bool
}

type Command 

type Command[Pipe TaskListData] struct {
	Plumber *Plumber

	Log *logrus.Entry

	Command *exec.Cmd
	// contains filtered or unexported fields
}

func NewCommand 

func NewCommand[Pipe TaskListData](
	task *Task[Pipe],
	command string,
	args ...string,
) *Command[Pipe]

NewCommand Creates a new command to be run as a job.

func (*Command[Pipe]) AddSelfToTheParentTask 

func (c *Command[Pipe]) AddSelfToTheParentTask(pt *Task[Pipe]) *Command[Pipe]

Adds the current command to the task with a wrapper.

func (*Command[Pipe]) AddSelfToTheTask 

func (c *Command[Pipe]) AddSelfToTheTask() *Command[Pipe]

Adds the current command to the parent task.

func (*Command[Pipe]) AppendArgs 

func (c *Command[Pipe]) AppendArgs(args ...string) *Command[Pipe]

Appends arguments to the command.

func (*Command[Pipe]) AppendDirectEnvironment 

func (c *Command[Pipe]) AppendDirectEnvironment(environment ...string) *Command[Pipe]

Appends environment variables to command directly.

func (*Command[Pipe]) AppendEnvironment 

func (c *Command[Pipe]) AppendEnvironment(environment map[string]string) *Command[Pipe]

Appends environment variables to command as map.

func (*Command[Pipe]) EnableStreamRecording 

func (c *Command[Pipe]) EnableStreamRecording() *Command[Pipe]

Sets the option where this command will save its output to be later accessed in the shouldRunAfterFn.

func (*Command[Pipe]) EnableTerminator 

func (c *Command[Pipe]) EnableTerminator() *Command[Pipe]

Enables global plumber terminator on this command to terminate the current command when the application is terminated.

func (*Command[Pipe]) EnsureIsAlive 

func (c *Command[Pipe]) EnsureIsAlive() *Command[Pipe]

Sets the option where it will raise an error if the underlying command stops.

func (*Command[Pipe]) GetCombinedStream 

func (c *Command[Pipe]) GetCombinedStream() []string

Fetches the saved streams that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) GetFormattedCommand 

func (c *Command[Pipe]) GetFormattedCommand() string

Fetches the name of this command, that is formatted for the logger.

func (*Command[Pipe]) GetStderrStream 

func (c *Command[Pipe]) GetStderrStream() []string

Fetches the saved stderr stream that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) GetStdoutStream 

func (c *Command[Pipe]) GetStdoutStream() []string

Fetches the saved stdout stream that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) HasExited added in v4.28.0 

func (c *Command[Pipe]) HasExited() bool

Returns whether the command has exited properly or not.

func (*Command[Pipe]) HasFailed added in v4.28.0 

func (c *Command[Pipe]) HasFailed() bool

Returns whether the command has failed or not.

func (*Command[Pipe]) IsDisabled 

func (c *Command[Pipe]) IsDisabled() bool

Checks whether current command is disabled.

func (*Command[Pipe]) Job 

func (c *Command[Pipe]) Job() Job

Convert Command.Run to a floc job.

func (*Command[Pipe]) Run 

func (c *Command[Pipe]) Run() error

Run the command as defined.

func (*Command[Pipe]) Set 

func (c *Command[Pipe]) Set(fn CommandFn[Pipe]) *Command[Pipe]

Sets the function that should manipulate the command depending on the pipe variables.

func (*Command[Pipe]) SetDir 

func (c *Command[Pipe]) SetDir(dir string) *Command[Pipe]

Sets the current directory where the command will be executed.

func (*Command[Pipe]) SetIgnoreError 

func (c *Command[Pipe]) SetIgnoreError() *Command[Pipe]

Sets the option to ignore errors raised by this command therefore a failing command will not fail the application.

func (*Command[Pipe]) SetJobWrapper added in v4.35.0 

func (c *Command[Pipe]) SetJobWrapper(fn JobWrapperFn) *Command[Pipe]

Extend the job of the current task.

func (*Command[Pipe]) SetLogLevel 

func (c *Command[Pipe]) SetLogLevel(
	stdout LogLevel,
	stderr LogLevel,
	lifetime LogLevel,
) *Command[Pipe]

Sets the log level specific to this command.

func (*Command[Pipe]) SetMaskOsEnvironment 

func (c *Command[Pipe]) SetMaskOsEnvironment() *Command[Pipe]

Sets the option where underlying environment variables are not passed to the command.

func (*Command[Pipe]) SetOnTerminator 

func (c *Command[Pipe]) SetOnTerminator(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that fires on when the application is globally terminated through plumber.

func (*Command[Pipe]) SetPath 

func (c *Command[Pipe]) SetPath(dir string) *Command[Pipe]

Sets the current directory where the command will be executed.

func (*Command[Pipe]) SetRetries added in v4.28.0 

func (c *Command[Pipe]) SetRetries(retries int, always bool, delay time.Duration) *Command[Pipe]

Sets the option to retry the command if failed.

func (*Command[Pipe]) ShouldDisable 

func (c *Command[Pipe]) ShouldDisable(fn TaskPredicateFn[Pipe]) *Command[Pipe]

Adds a predicate to check whether this command should be disabled depending on the pipe variables.

func (*Command[Pipe]) ShouldRunAfter 

func (c *Command[Pipe]) ShouldRunAfter(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that should run after the main command has exited successfully.

func (*Command[Pipe]) ShouldRunBefore added in v4.32.41 

func (c *Command[Pipe]) ShouldRunBefore(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that should run after the main command has exited successfully.

type CommandFn 

type CommandFn[Pipe TaskListData] func(*Command[Pipe]) error

type CommandOptions 

type CommandOptions[Pipe TaskListData] struct {
	Disable TaskPredicateFn[Pipe]
	// contains filtered or unexported fields
}

type CommandStatus added in v4.32.1 

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

type DeprecationNotice 

type DeprecationNotice struct {
	Message     string
	Environment []string
	Flag        []string
	Level       LogLevel
}

type DocumentationOptions added in v4.24.0 

type DocumentationOptions struct {
	MarkdownOutputFile          string
	EmbeddedMarkdownOutputFile  string
	MarkdownBehead              int
	ExcludeFlags                bool
	ExcludeEnvironmentVariables bool
	ExcludeHelpCommand          bool
}

type ErrorWithLogger 

type ErrorWithLogger struct {
	Log *logrus.Entry
	Err error
}

type GuardHandlerFn 

type GuardHandlerFn[Pipe TaskListData] func(*TaskList[Pipe])

type Job 

type Job = floc.Job

type JobPredicate 

type JobPredicate = floc.Predicate

type JobWrapperFn 

type JobWrapperFn func(job Job) Job

type LogLevel 

type LogLevel = logrus.Level

type Plumber 

type Plumber struct {
	Cli         *cli.App
	Log         *logrus.Logger
	Environment AppEnvironment
	Channel     AppChannel
	Terminator
	// contains filtered or unexported fields
}

func NewPlumber added in v4.21.0 

func NewPlumber(fn PlumberNewFn) *Plumber

Creates a new Plumber instance and initiates it.

func (*Plumber) AppendFlags 

func (p *Plumber) AppendFlags(flags ...[]cli.Flag) []cli.Flag

Appends flags together.

func (*Plumber) AppendSecrets 

func (p *Plumber) AppendSecrets(secrets ...string) *Plumber

Adds sensitive information so that the logger will not log out the given secrets.

func (*Plumber) EnableTerminator 

func (p *Plumber) EnableTerminator() *Plumber

Enables terminator globally for the current application.

If terminator functions are going to be used inside task lists, tasks and commands, terminator should be globally enabled. The terminate information will be propagated through the channels to the subcomponents.

func (*Plumber) New 

func (p *Plumber) New(
	fn PlumberNewFn,
) *Plumber

Creates a new plumber.

func (*Plumber) RegisterTerminated 

func (p *Plumber) RegisterTerminated() *Plumber

Register a component as successfully terminated.

func (*Plumber) RegisterTerminator 

func (p *Plumber) RegisterTerminator() *Plumber

Registers a new component that should be handled by the terminator.

func (*Plumber) Run 

func (p *Plumber) Run()

Starts the application.

func (*Plumber) SendCustomError 

func (p *Plumber) SendCustomError(log *logrus.Entry, err error) *Plumber

Sends an error with its custom instance of logger through the channel.

func (*Plumber) SendCustomFatal 

func (p *Plumber) SendCustomFatal(log *logrus.Entry, err error) *Plumber

Sends an fatal error with its custom instance of logger through the channel.

func (*Plumber) SendError 

func (p *Plumber) SendError(err error) *Plumber

Sends an error through the channel.

func (*Plumber) SendExit 

func (p *Plumber) SendExit(code int) *Plumber

Sends exit code to terminate the application.

func (*Plumber) SendFatal 

func (p *Plumber) SendFatal(err error) *Plumber

Sends an fatal error through the channel.

func (*Plumber) SendTerminate 

func (p *Plumber) SendTerminate(sig os.Signal, code int)

Sends a terminate request to the application via interruption signal.

func (*Plumber) Set added in v4.24.0 

func (p *Plumber) Set(fn PlumberFn) *Plumber

Sets additional configuration fields.

func (*Plumber) SetDelimiter added in v4.24.0 

func (p *Plumber) SetDelimiter(delimiter string) *Plumber

Sets delimiter for the application.

func (*Plumber) SetDeprecationNotices added in v4.24.0 

func (p *Plumber) SetDeprecationNotices(notices ...[]DeprecationNotice) *Plumber

Sets the deprecation notices for the application.

func (*Plumber) SetDocumentationOptions added in v4.24.0 

func (p *Plumber) SetDocumentationOptions(options DocumentationOptions) *Plumber

Sets documentation options of the application.

func (*Plumber) SetFormatter added in v4.35.1 

func (p *Plumber) SetFormatter(formatter *logger.Formatter) *Plumber

sets formatter for the plumber.

func (*Plumber) SetOnTerminate 

func (p *Plumber) SetOnTerminate(fn PlumberOnTerminateFn) *Plumber

Sets the action that would be executed on terminate.

func (*Plumber) SetTerminatorTimeout added in v4.30.0 

func (p *Plumber) SetTerminatorTimeout(timeout time.Duration) *Plumber

Sets timeout for terminator of the application.

func (*Plumber) Terminate 

func (p *Plumber) Terminate(code int)

Sends a terminate request through the application.

This will gracefully try to stop the application components that are registered and listening for the terminator.

type PlumberFn added in v4.24.0 

type PlumberFn func(p *Plumber) error

type PlumberNewFn added in v4.21.0 

type PlumberNewFn func(p *Plumber) *cli.App

type PlumberOnTerminateFn 

type PlumberOnTerminateFn func() error

type PlumberOptions added in v4.20.0 

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

type Result 

type Result = floc.Result
const (
	TASK_ANY       Result = floc.None
	TASK_COMPLETED Result = floc.Completed
	TASK_CANCELLED Result = floc.Canceled
	TASK_FAILED    Result = floc.Failed
)

type ResultMask 

type ResultMask = floc.ResultMask

type StatusStopCases added in v4.32.1 

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

type Task 

type Task[Pipe TaskListData] struct {
	Plumber *Plumber

	Log     *logrus.Entry
	Channel *AppChannel
	Lock    *sync.RWMutex

	Pipe    *Pipe
	Control floc.Control

	Name string
	// contains filtered or unexported fields
}

func NewTask 

func NewTask[Pipe TaskListData](tl *TaskList[Pipe], name ...string) *Task[Pipe]

NewTask Creates a new task to be run as a job.

func (*Task[Pipe]) AddCommands 

func (t *Task[Pipe]) AddCommands(commands ...*Command[Pipe]) *Task[Pipe]

Attaches existing commands to this task.

func (*Task[Pipe]) AddSelfToTheParent 

func (t *Task[Pipe]) AddSelfToTheParent(
	fn func(pt *Task[Pipe], st *Task[Pipe]),
) *Task[Pipe]

Attaches this task to the parent task with a wrapper.

func (*Task[Pipe]) AddSelfToTheParentAsParallel 

func (t *Task[Pipe]) AddSelfToTheParentAsParallel() *Task[Pipe]

Attaches this task to the parent task in parallel.

func (*Task[Pipe]) AddSelfToTheParentAsSequence 

func (t *Task[Pipe]) AddSelfToTheParentAsSequence() *Task[Pipe]

Attaches this task to the parent task in sequence.

func (*Task[Pipe]) CreateCommand 

func (t *Task[Pipe]) CreateCommand(command string, args ...string) *Command[Pipe]

Creates a NewCommand attached to the current task.

func (*Task[Pipe]) CreateSubtask 

func (t *Task[Pipe]) CreateSubtask(name ...string) *Task[Pipe]

Creates a subtask that is attached to the current task.

func (*Task[Pipe]) EnableTerminator 

func (t *Task[Pipe]) EnableTerminator() *Task[Pipe]

Enables global plumber terminator on this task.

func (*Task[Pipe]) ExtendSubtask 

func (t *Task[Pipe]) ExtendSubtask(fn JobWrapperFn) *Task[Pipe]

Extends the subtask of the current task with a wrapper.

func (*Task[Pipe]) GetCommandJobAsJobParallel 

func (t *Task[Pipe]) GetCommandJobAsJobParallel() Job

Returns the attached commands to this task as a job to run as parallel depending on their definition order.

func (*Task[Pipe]) GetCommandJobAsJobSequence 

func (t *Task[Pipe]) GetCommandJobAsJobSequence() Job

Returns the attached commands to this task as a job to run as sequence depending on their definition order.

func (*Task[Pipe]) GetCommandJobs 

func (t *Task[Pipe]) GetCommandJobs() []Job

Returns the attached commands to this task as a slice of jobs.

func (*Task[Pipe]) GetCommands 

func (t *Task[Pipe]) GetCommands() []*Command[Pipe]

Returns the attached commands to this task.

func (*Task[Pipe]) GetSubtasks 

func (t *Task[Pipe]) GetSubtasks() Job

Returns the subtasks of this task.

func (*Task[Pipe]) HasParent 

func (t *Task[Pipe]) HasParent() bool

Checks whether this task has a parent task.

func (*Task[Pipe]) IsDisabled 

func (t *Task[Pipe]) IsDisabled() bool

Checks whether the current task is disabled or not.

func (*Task[Pipe]) IsSkipped 

func (t *Task[Pipe]) IsSkipped() bool

Checks whether the current task is skipped or not.

func (*Task[Pipe]) Job 

func (t *Task[Pipe]) Job() Job

Runs the current task as a job.

func (*Task[Pipe]) Run 

func (t *Task[Pipe]) Run() error

Runs the current task.

func (*Task[Pipe]) RunCommandJobAsJobParallel 

func (t *Task[Pipe]) RunCommandJobAsJobParallel() error

Runs the commands that are attached to this task as parallel.

func (*Task[Pipe]) RunCommandJobAsJobParallelWithExtension 

func (t *Task[Pipe]) RunCommandJobAsJobParallelWithExtension(fn JobWrapperFn) error

Runs the commands that are attached to this task as parallel with the given wrapper.

func (*Task[Pipe]) RunCommandJobAsJobSequence 

func (t *Task[Pipe]) RunCommandJobAsJobSequence() error

Runs the commands that are attached to this task as sequence.

func (*Task[Pipe]) RunCommandJobAsJobSequenceWithExtension 

func (t *Task[Pipe]) RunCommandJobAsJobSequenceWithExtension(fn JobWrapperFn) error

Runs the commands that are attached to this task as sequence with the given wrapper.

func (*Task[Pipe]) RunSubtasks 

func (t *Task[Pipe]) RunSubtasks() error

Runs the subtasks of the current task.

func (*Task[Pipe]) RunSubtasksWithExtension 

func (t *Task[Pipe]) RunSubtasksWithExtension(fn func(job Job) Job) error

Runs the subtasks of the current task with a wrapper.

func (*Task[Pipe]) SendError 

func (t *Task[Pipe]) SendError(err error) *Task[Pipe]

Send the error message to plumber while running inside a routine.

func (*Task[Pipe]) SendExit 

func (t *Task[Pipe]) SendExit(code int) *Task[Pipe]

Trigger the exit protocol of plumber.

func (*Task[Pipe]) SendFatal 

func (t *Task[Pipe]) SendFatal(err error) *Task[Pipe]

Send the fatal error message to plumber while running inside a routine.

func (*Task[Pipe]) Set 

func (t *Task[Pipe]) Set(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run as task.

func (*Task[Pipe]) SetJobWrapper 

func (t *Task[Pipe]) SetJobWrapper(fn JobWrapperFn) *Task[Pipe]

Extend the job of the current task.

func (*Task[Pipe]) SetOnTerminator 

func (t *Task[Pipe]) SetOnTerminator(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should fire whenever the application is globally terminated.

func (*Task[Pipe]) SetSubtask 

func (t *Task[Pipe]) SetSubtask(job Job) *Task[Pipe]

Sets the subtask of this task directly.

func (*Task[Pipe]) ShouldDisable 

func (t *Task[Pipe]) ShouldDisable(fn TaskPredicateFn[Pipe]) *Task[Pipe]

Sets the predicate that should conditionally disable the task depending on the pipe variables.

func (*Task[Pipe]) ShouldRunAfter 

func (t *Task[Pipe]) ShouldRunAfter(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run after the task.

func (*Task[Pipe]) ShouldRunBefore 

func (t *Task[Pipe]) ShouldRunBefore(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run before the task.

func (*Task[Pipe]) ShouldSkip 

func (t *Task[Pipe]) ShouldSkip(fn TaskPredicateFn[Pipe]) *Task[Pipe]

Sets the predicate that should conditionally skip the task depending on the pipe variables.

func (*Task[Pipe]) ToParent 

func (t *Task[Pipe]) ToParent(
	parent *Task[Pipe],
	fn func(pt *Task[Pipe], st *Task[Pipe]),
) *Task[Pipe]

Attaches this task to the given parent task.

type TaskFn 

type TaskFn[Pipe TaskListData] func(t *Task[Pipe]) error

type TaskList 

type TaskList[Pipe TaskListData] struct {
	Plumber    *Plumber
	CliContext *cli.Context
	Pipe       Pipe
	Channel    *AppChannel
	Control    floc.Control

	Name string

	Lock *sync.RWMutex
	Log  *logrus.Entry
	// contains filtered or unexported fields
}

func NewTaskList added in v4.21.0 

func NewTaskList[Pipe TaskListData](p *Plumber) *TaskList[Pipe]

Creates a new task list and initiates it.

func (*TaskList[Pipe]) CreateBasicJob 

func (t *TaskList[Pipe]) CreateBasicJob(fn func() error) Job

func (*TaskList[Pipe]) CreateJob 

func (t *TaskList[Pipe]) CreateJob(fn func(tl *TaskList[Pipe]) error) Job

func (*TaskList[Pipe]) CreateTask 

func (t *TaskList[Pipe]) CreateTask(name ...string) *Task[Pipe]

Creates a new task.

func (*TaskList[Pipe]) GetTasks 

func (t *TaskList[Pipe]) GetTasks() Job

Returns the current tasks inside the task list as job.

func (*TaskList[Pipe]) GuardAlways 

func (t *TaskList[Pipe]) GuardAlways(job Job) Job

Always run this job!

func (*TaskList[Pipe]) GuardIgnorePanic 

func (t *TaskList[Pipe]) GuardIgnorePanic(job Job) Job

func (*TaskList[Pipe]) GuardOnPanic 

func (t *TaskList[Pipe]) GuardOnPanic(job Job, fn GuardHandlerFn[Pipe]) Job

OnPanic protects the job from falling into panic. In addition it takes PanicTrigger func which is called in case of panic. Guarding the job from falling into panic is effective only if the job runs in the current goroutine.

func (*TaskList[Pipe]) GuardOnTimeout 

func (t *TaskList[Pipe]) GuardOnTimeout(
	job Job,
	fn GuardHandlerFn[Pipe],
	timeout time.Duration,
) Job

OnTimeout protects the job from taking too much time on execution. In addition it takes TimeoutTrigger func (t *TaskList[Pipe]) which called if time is out. The job is run in it's own goroutine while the current goroutine waits until the job finished or time went out or the flow is finished.

func (*TaskList[Pipe]) GuardPanic 

func (t *TaskList[Pipe]) GuardPanic(job Job) Job

Panic protects the job from falling into panic. On panic the flow will be canceled with the ErrPanic result. Guarding the job from falling into panic is effective only if the job runs in the current goroutine.

func (*TaskList[Pipe]) GuardResume 

func (t *TaskList[Pipe]) GuardResume(job Job, mask Result) Job

Resume resumes execution of the flow possibly finished by the job. If the mask is empty execution will be resumed regardless the reason it was finished. Otherwise execution will be resumed if the reason it finished with is masked.

func (*TaskList[Pipe]) GuardTimeout 

func (t *TaskList[Pipe]) GuardTimeout(job Job, timeout time.Duration) Job

GuardTimeout protects the job from taking too much time on execution. The job is run in it's own goroutine while the current goroutine waits until the job finished or time went out or the flow is finished.

func (*TaskList[Pipe]) IsDisabled added in v4.17.0 

func (t *TaskList[Pipe]) IsDisabled() bool

Checks whether the current task is disabled or not.

func (*TaskList[Pipe]) IsSkipped added in v4.17.0 

func (t *TaskList[Pipe]) IsSkipped() bool

Checks whether the current task is skipped or not.

func (*TaskList[Pipe]) Job 

func (t *TaskList[Pipe]) Job() Job

Returns this task list as a job.

func (*TaskList[Pipe]) JobBackground 

func (t *TaskList[Pipe]) JobBackground(job Job) Job

JobBackground starts the job in it's own goroutine. The function does not track the lifecycle of the job started and does no synchronization with it therefore the job running in background may remain active even if the flow is finished. The function assumes the job is aware of the flow state and/or synchronization and termination of it is implemented outside. 

floc.Run(run.Background(
	func(ctx floc.Context, ctrl floc.Control) error {
		for !ctrl.IsFinished() {
			fmt.Println(time.Now())
		}

		return nil
	}
})

Summary:

  • Run jobs in goroutines : YES
  • Wait all jobs finish : NO
  • Run order : SINGLE

Diagram: 

--+----------->
  |
  +-->[JOB]

func (*TaskList[Pipe]) JobDelay 

func (t *TaskList[Pipe]) JobDelay(job Job, delay time.Duration) Job

JobDelay does delay before starting the job.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

--(DELAY)-->[JOB]-->

func (*TaskList[Pipe]) JobElse 

func (t *TaskList[Pipe]) JobElse(job Job) Job

JobElse just returns the job unmodified. Else is used for expressiveness and can be omitted.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

----[JOB]--->

func (*TaskList[Pipe]) JobIf 

func (t *TaskList[Pipe]) JobIf(predicate JobPredicate, jobs ...Job) Job

JobIf runs the first job if the condition is met and runs the second job, if it's passed, if the condition is not met. The function panics if no or more than two jobs are given.

For expressiveness Then() and Else() can be used. 

flow := run.If(testSomething,
  run.Then(doSomething),
  run.Else(doSomethingElse),
)

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                    +----->[JOB_1]---+
                    | YES            |
--(CONDITION MET?)--+                +-->
                    | NO             |
                    +----->[JOB_2]---+

func (*TaskList[Pipe]) JobIfNot 

func (t *TaskList[Pipe]) JobIfNot(predicate JobPredicate, jobs ...Job) Job

JobIfNot runs the first job if the condition is not met and runs the second job, if it's passed, if the condition is met. The function panics if no or more than two jobs are given.

For expressiveness Then() and Else() can be used. 

flow := run.IfNot(testSomething,
  run.Then(doSomething),
  run.Else(doSomethingElse),
)

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                    +----->[JOB_1]---+
                    | NO             |
--(CONDITION MET?)--+                +-->
                    | YES            |
                    +----->[JOB_2]---+

func (*TaskList[Pipe]) JobLoop 

func (t *TaskList[Pipe]) JobLoop(job Job) Job

JobLoop repeats running the job forever.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

  +----------+
  |          |
  V          |
----->[JOB]--+

func (*TaskList[Pipe]) JobLoopWithWaitAfter 

func (t *TaskList[Pipe]) JobLoopWithWaitAfter(job Job, delay time.Duration) Job

func (*TaskList[Pipe]) JobParallel 

func (t *TaskList[Pipe]) JobParallel(jobs ...Job) Job

JobParallel runs jobs in their own goroutines and waits until all of them finish.

Summary:

  • Run jobs in goroutines : YES
  • Wait all jobs finish : YES
  • Run order : PARALLEL

Diagram: 

  +-->[JOB_1]--+
  |            |
--+-->  ..   --+-->
  |            |
  +-->[JOB_N]--+

func (*TaskList[Pipe]) JobRepeat 

func (t *TaskList[Pipe]) JobRepeat(job Job, times int) Job

JobRepeat repeats running the job for N times.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                        NO
  +-----------[JOB]<---------+
  |                          |
  V                          | YES
----(ITERATED COUNT TIMES?)--+---->

func (*TaskList[Pipe]) JobSequence 

func (t *TaskList[Pipe]) JobSequence(jobs ...Job) Job

JobSequence runs jobs sequentially, one by one.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SEQUENCE

Diagram: 

-->[JOB_1]-...->[JOB_N]-->

func (*TaskList[Pipe]) JobThen 

func (t *TaskList[Pipe]) JobThen(job Job) Job

Then just returns the job unmodified. Then is used for expressiveness and can be omitted.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

----[JOB]--->

func (*TaskList[Pipe]) JobWait 

func (t *TaskList[Pipe]) JobWait(predicate JobPredicate, sleep time.Duration) Job

JobWait waits until the condition is met. The function falls into sleep with the duration given between condition checks. The function does not run any job actually and just repeatedly checks predicate's return value. When the predicate returns true the function finishes.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

                  NO
  +------(SLEEP)------+
  |                   |
  V                   | YES
----(CONDITION MET?)--+----->

func (*TaskList[Pipe]) JobWaitForTerminator 

func (t *TaskList[Pipe]) JobWaitForTerminator() Job

func (*TaskList[Pipe]) JobWhile 

func (t *TaskList[Pipe]) JobWhile(predicate JobPredicate, job Job) Job

JobWhile repeats running the job while the condition is met.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                  YES
  +-------[JOB]<------+
  |                   |
  V                   | NO
----(CONDITION MET?)--+---->

func (*TaskList[Pipe]) New 

func (t *TaskList[Pipe]) New(p *Plumber) *TaskList[Pipe]

Creates a new task list.

func (*TaskList[Pipe]) NewResultMask 

func (t *TaskList[Pipe]) NewResultMask(mask Result) ResultMask

NewResultMask constructs new instance from the mask given.

func (*TaskList[Pipe]) Predicate 

func (t *TaskList[Pipe]) Predicate(fn TaskListPredicateFn[Pipe]) JobPredicate

Creates a new floc predicate out of the given conditions.

func (*TaskList[Pipe]) PredicateAnd 

func (t *TaskList[Pipe]) PredicateAnd(predicates ...JobPredicate) JobPredicate

PredicateAnd returns a predicate which chains multiple predicates into a condition with AND logic. The result predicate finishes calculation of the condition as fast as the result is known. The function panics if the number of predicates is less than 2.

The result predicate tests the condition as follows. 

[PRED_1] AND ... AND [PRED_N]

func (*TaskList[Pipe]) PredicateNot 

func (t *TaskList[Pipe]) PredicateNot(predicate JobPredicate) JobPredicate

PredicateNot returns the negated value of the predicate.

The result predicate tests the condition as follows. 

NOT [PRED]

func (*TaskList[Pipe]) PredicateOr 

func (t *TaskList[Pipe]) PredicateOr(predicates ...JobPredicate) JobPredicate

PredicateOr returns a predicate which chains multiple predicates into a condition with OR logic. The result predicate finishes calculation of the condition as fast as the result is known.

The result predicate tests the condition as follows. 

[PRED_1] OR ... OR [PRED_N]

func (*TaskList[Pipe]) PredicateXor 

func (t *TaskList[Pipe]) PredicateXor(predicates ...JobPredicate) JobPredicate

Xor returns a predicate which chains multiple predicates into a condition with XOR logic. The result predicate finishes calculation of the condition as fast as the result is known.

The result predicate tests the condition as follows. 

(([PRED_1] XOR [PRED_2]) ... XOR [PRED_N])

func (*TaskList[Pipe]) Run 

func (t *TaskList[Pipe]) Run() error

Runs the current task list.

func (*TaskList[Pipe]) RunJobs 

func (t *TaskList[Pipe]) RunJobs(job Job) error

Runs a the provided job.

func (*TaskList[Pipe]) Set 

func (t *TaskList[Pipe]) Set(fn TaskListJobFn[Pipe]) *TaskList[Pipe]

Sets the tasks of the task list.

func (*TaskList[Pipe]) SetCliContext 

func (t *TaskList[Pipe]) SetCliContext(ctx *cli.Context) *TaskList[Pipe]

Sets the CLI context for urfave/cli that is coming from the action function.

func (*TaskList[Pipe]) SetRuntimeDepth added in v4.20.0 

func (t *TaskList[Pipe]) SetRuntimeDepth(depth int) *TaskList[Pipe]

Sets the runtime depth for the logger.

func (*TaskList[Pipe]) SetTasks 

func (t *TaskList[Pipe]) SetTasks(tasks Job) *TaskList[Pipe]

Sets the tasks of the task list with wrapper.

func (*TaskList[Pipe]) ShouldDisable added in v4.17.0 

func (t *TaskList[Pipe]) ShouldDisable(fn TaskListPredicateFn[Pipe]) *TaskList[Pipe]

Sets the predicate that should conditionally disable the task list depending on the pipe variables.

func (*TaskList[Pipe]) ShouldRunAfter 

func (t *TaskList[Pipe]) ShouldRunAfter(fn TaskListFn[Pipe]) *TaskList[Pipe]

Sets the function that should run after the task list.

func (*TaskList[Pipe]) ShouldRunBefore 

func (t *TaskList[Pipe]) ShouldRunBefore(fn TaskListFn[Pipe]) *TaskList[Pipe]

Sets the function that should run before the task list.

func (*TaskList[Pipe]) ShouldSkip added in v4.17.0 

func (t *TaskList[Pipe]) ShouldSkip(fn TaskListPredicateFn[Pipe]) *TaskList[Pipe]

Sets the predicate that should conditionally skip the task list depending on the pipe variables.

func (*TaskList[Pipe]) Validate 

func (t *TaskList[Pipe]) Validate(data TaskListData) error

Validates the current pipe of the task list.

type TaskListData 

type TaskListData interface {
	any
}

type TaskListFn 

type TaskListFn[Pipe TaskListData] func(*TaskList[Pipe]) error

type TaskListJobFn 

type TaskListJobFn[Pipe TaskListData] func(*TaskList[Pipe]) Job

type TaskListOptions added in v4.17.0 

type TaskListOptions[Pipe TaskListData] struct {
	Skip    TaskListPredicateFn[Pipe]
	Disable TaskListPredicateFn[Pipe]
	// contains filtered or unexported fields
}

type TaskListPredicateFn 

type TaskListPredicateFn[Pipe TaskListData] func(*TaskList[Pipe]) bool

type TaskOptions 

type TaskOptions[Pipe TaskListData] struct {
	Skip    TaskPredicateFn[Pipe]
	Disable TaskPredicateFn[Pipe]
}

type TaskPredicateFn 

type TaskPredicateFn[Pipe TaskListData] func(t *Task[Pipe]) bool

type TaskStatus added in v4.32.1 

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

type Terminator 

type Terminator struct {
	Enabled         bool
	ShouldTerminate *broadcaster.Broadcaster[os.Signal]
	Terminated      *broadcaster.Broadcaster[bool]
	Lock            *sync.RWMutex
	// contains filtered or unexported fields
}

Source Files

View all Source files

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.