task

Documentation

Index

• Variables
• func DebugTaskList() []string
• func GracefulShutdown(timeout time.Duration) (err error)
• func OnProgramExit(about string, fn func())
• func RootContext() context.Context
• func RootContextCanceled() <-chan struct{}
• type Callback
• type Parent
• type Task
  • func RootTask(name string, needFinish ...bool) *Task
  • func (t *Task) Context() context.Context
  • func (t *Task) Finish(reason any)
  • func (t *Task) FinishCause() error
  • func (t *Task) Finished() <-chan struct{}
  • func (t *Task) MarshalText() ([]byte, error)
  • func (t *Task) Name() string
  • func (t *Task) OnCancel(about string, fn func())
  • func (t *Task) OnFinished(about string, fn func())
  • func (t *Task) String() string
  • func (t *Task) Subtask(name string, needFinish ...bool) *Task
• type TaskFinisher
• type TaskStarter

Variables

var ErrProgramExiting = errors.New("program exiting")

Functions

func DebugTaskList

func DebugTaskList() []string

DebugTaskList returns list of all tasks.

The returned string is suitable for printing to the console.

func GracefulShutdown

func GracefulShutdown(timeout time.Duration) (err error)

GracefulShutdown waits for all tasks to finish, up to the given timeout.

If the timeout is exceeded, it prints a list of all tasks that were still running when the timeout was reached, and their current tree of subtasks.

func OnProgramExit

func OnProgramExit(about string, fn func())

func RootContext

func RootContext() context.Context

func RootContextCanceled

func RootContextCanceled() <-chan struct{}

Types

type Callback

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

type Parent

type Parent interface {
	Context() context.Context
	Subtask(name string, needFinish ...bool) *Task
	Name() string
	Finish(reason any)
	OnCancel(name string, f func())
}

type Task

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

Task controls objects' lifetime.

Objects that uses a Task should implement the TaskStarter and the TaskFinisher interface.

Use Task.Finish to stop all subtasks of the Task.

func RootTask

func RootTask(name string, needFinish ...bool) *Task

RootTask returns a new Task with the given name, derived from the root context.

func (*Task) Context

func (t *Task) Context() context.Context

func (*Task) Finish

func (t *Task) Finish(reason any)

Finish cancel all subtasks and wait for them to finish, then marks the task as finished, with the given reason (if any).

func (*Task) FinishCause

func (t *Task) FinishCause() error

FinishCause returns the reason / error that caused the task to be finished.

func (*Task) Finished

func (t *Task) Finished() <-chan struct{}

func (*Task) MarshalText

func (t *Task) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Task) Name

func (t *Task) Name() string

Name returns the name of the task without parent names.

func (*Task) OnCancel

func (t *Task) OnCancel(about string, fn func())

OnCancel calls fn when the task is canceled.

It should not be called after Finish is called.

func (*Task) OnFinished

func (t *Task) OnFinished(about string, fn func())

OnFinished calls fn when the task is canceled and all subtasks are finished.

It should not be called after Finish is called.

func (*Task) String

func (t *Task) String() string

String returns the full name of the task.

func (*Task) Subtask

func (t *Task) Subtask(name string, needFinish ...bool) *Task

Subtask returns a new subtask with the given name, derived from the parent's context.

This should not be called after Finish is called.

type TaskFinisher

type TaskFinisher interface {
	Finish(reason any)
}

type TaskStarter

type TaskStarter interface {
	// Start starts the object that implements TaskStarter,
	// and returns an error if it fails to start.
	//
	// callerSubtask.Finish must be called when start fails or the object is finished.
	Start(parent Parent) E.Error
	Task() *Task
}