threads

Documentation

Index

• type OnFinishFunc
• type Thread
  • func NewThread(ctx context.Context, id string, work WorkFunc, onFinish OnFinishFunc) Thread
  • func (t *Thread) Cancel()
  • func (t *Thread) Context() context.Context
  • func (t *Thread) ID() string
  • func (t *Thread) OnFinishFunc() OnFinishFunc
  • func (t *Thread) WorkFunc() WorkFunc
• type ThreadManager
  • func NewThreadManager(mgrCtx context.Context, onFinish OnFinishFunc) *ThreadManager
  • func (tm *ThreadManager) IsRunning() bool
  • func (tm *ThreadManager) IsStarted() bool
  • func (tm *ThreadManager) IsStopped() bool
  • func (tm *ThreadManager) Restart(_ context.Context, tr ThreadReturn)
  • func (tm *ThreadManager) RestartOnError(ctx context.Context, tr ThreadReturn)
  • func (tm *ThreadManager) RestartOnSuccess(ctx context.Context, tr ThreadReturn)
  • func (tm *ThreadManager) Run(ctx context.Context, id string, work func(context.Context) error, ...)
  • func (tm *ThreadManager) RunThread(t Thread)
  • func (tm *ThreadManager) Start()
  • func (tm *ThreadManager) Stop()
• type ThreadReturn
  • func NewThreadReturn(thread *Thread, err error) ThreadReturn
• type WorkFunc

Types

type OnFinishFunc

type OnFinishFunc func(context.Context, ThreadReturn)

OnFinishFunc can be used to react to a thread finishing. Note that its context might already be cancelled (if the ThreadManager is being stopped).

type Thread

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

Thread represents a thread that can be run by the ThreadManager.

func NewThread

func NewThread(ctx context.Context, id string, work WorkFunc, onFinish OnFinishFunc) Thread

NewThread creates a new thread with the given id, work function and onFinish function. It is usually not required to call this function directly, instead use the ThreadManager's Run method. A new context with a cancel function is derived from the context passed to the constructor. The Thread's fields are considered immutable after creation.

func (*Thread) Cancel

func (t *Thread) Cancel()

Cancel cancels the thread's context. The thread manager cancels all threads' contexts when it is stopped, so calling this manually is usually not necessary.

func (*Thread) Context

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

Context returns the context of the thread.

func (*Thread) ID

func (t *Thread) ID() string

ID returns the id of the thread.

func (*Thread) OnFinishFunc

func (t *Thread) OnFinishFunc() OnFinishFunc

OnFinishFunc returns the onFinish function of the thread.

func (*Thread) WorkFunc

func (t *Thread) WorkFunc() WorkFunc

WorkFunc returns the workload function of the thread.

type ThreadManager

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

func NewThreadManager

func NewThreadManager(mgrCtx context.Context, onFinish OnFinishFunc) *ThreadManager

NewThreadManager creates a new ThreadManager. The mgrCtx is used for two purposes:

1. If the context is cancelled, the ThreadManager is stopped. Alternatively, its Stop() method can be called.
2. If the context contains a logger, it is used for logging.

If onFinish is not nil, it will be called whenever a thread finishes. It is called after the thread's own onFinish function, if any.

func (*ThreadManager) IsRunning

func (tm *ThreadManager) IsRunning() bool

IsRunning returns true if the ThreadManager is currently running, meaning it has been started and not yet been stopped. This is a convenience function that is equivalent to calling IsStarted() && !IsStopped().

func (*ThreadManager) IsStarted

func (tm *ThreadManager) IsStarted() bool

IsStarted returns true if the ThreadManager has been started. Note that this will return true if the ThreadManager has been started at some point, even if it has been stopped by now.

func (*ThreadManager) IsStopped

func (tm *ThreadManager) IsStopped() bool

IsStopped returns true if the ThreadManager has been stopped. Note that this will return false if the ThreadManager has not been started yet.

func (*ThreadManager) Restart

func (tm *ThreadManager) Restart(_ context.Context, tr ThreadReturn)

Restart is a pre-defined onFinish function that can be used to restart a thread after it has finished. This method is not meant to be called directly, instead pass it to the ThreadManager's Run method as the onFinish parameter:

tm.Run(ctx, "myThread", myWorkFunc, tm.Restart)

func (*ThreadManager) RestartOnError

func (tm *ThreadManager) RestartOnError(ctx context.Context, tr ThreadReturn)

RestartOnError is a pre-defined onFinish function that can be used to restart a thread after it has finished, if it finished with an error. It is the opposite of RestartOnSuccess. This method is not meant to be called directly, instead pass it to the ThreadManager's Run method as the onFinish parameter:

tm.Run(ctx, "myThread", myWorkFunc, tm.RestartOnError)

func (*ThreadManager) RestartOnSuccess

func (tm *ThreadManager) RestartOnSuccess(ctx context.Context, tr ThreadReturn)

RestartOnSuccess is a pre-defined onFinish function that can be used to restart a thread after it has finished, if it didn't throw an error. It is the opposite of RestartOnError. This method is not meant to be called directly, instead pass it to the ThreadManager's Run method as the onFinish parameter:

tm.Run(ctx, "myThread", myWorkFunc, tm.RestartOnSuccess)

func (*ThreadManager) Run

func (tm *ThreadManager) Run(ctx context.Context, id string, work func(context.Context) error, onFinish OnFinishFunc)

Run gives a new thread to run to the ThreadManager. The context is used to create a new context with a cancel function for the thread. id is used for logging and debugging purposes. Note that when a thread with the same id as an already running thread is added, the running thread will be cancelled. If the ThreadManager has not been started yet, the previously added thread with the conflicting id will be discarded and the newly added one will be run when the ThreadManager is started instead. A thread MUST NOT start another thread with the same id as itself during its work function. If a thread wants to restart itself, this must happen in the onFinish function. work is the actual workload of the thread. onFinish can be used to react to the thread having finished. There are some pre-defined functions that can be used as onFinish functions, e.g. the ThreadManager's Restart method.

func (*ThreadManager) RunThread

func (tm *ThreadManager) RunThread(t Thread)

RunThread is the same as Run, but takes a Thread struct instead of the individual parameters.

func (*ThreadManager) Start

func (tm *ThreadManager) Start()

Start starts the ThreadManager. This starts a goroutine that listens for thread returns and os signals. Calling Start() multiple times is a no-op, unless the ThreadManager has already been stopped, then it panics. It is possible to add threads before the ThreadManager is started, but they will only be run after Start() is called. Threads added after Start() will be run immediately. There are three ways to stop the ThreadManager again:

1. Cancel the context passed to the ThreadManager during creation.
2. Call the ThreadManager's Stop() method.
3. Send a SIGINT or SIGTERM signal to the process.

func (*ThreadManager) Stop

func (tm *ThreadManager) Stop()

Stop stops the ThreadManager. Panics if the ThreadManager has not been started yet. Calling Stop() multiple times is a no-op. It is not possible to start the ThreadManager again after it has been stopped, a new instance must be created. Adding threads after the ThreadManager has been stopped is a no-op. The ThreadManager is also stopped when the context passed to the ThreadManager during creation is cancelled or when a SIGINT or SIGTERM signal is received.

type ThreadReturn

type ThreadReturn struct {
	Err    error
	Thread *Thread
}

ThreadReturn represents the result of a thread's execution. It contains a reference to the thread and an error, if any occurred.

func NewThreadReturn

func NewThreadReturn(thread *Thread, err error) ThreadReturn

NewThreadReturn constructs a new ThreadReturn object. This is used by the ThreadManager internally and it should rarely be necessary to call this function directly.

type WorkFunc

type WorkFunc func(context.Context) error

WorkFunc is the function that holds the actual workload of a thread. The ThreadManager cancels the provided context when being stopped, so the workload should listen to the context's Done channel.