README
¶
GoAsync - Flexible processes management library
Go Async is designed to simplify managing multi-process applications into easily understandable single purpose units of work.
The Task Manager is responsible for running and managing any number of assigned tasks.
For the Task Manager to operate, each task must follow 1 of two patterns.
Long Running Task
Is expected to run for the entire process's execution.
- Each task added to the Task Manager will initialize serially in the order they were added to the Task Manager a. If an error occurs, stop Initializng any remaning tasks. Also Run Cleanup for any tasks that have already been Initialized
- In Parallel Run all Execute(...) functions for any tasks a. All tasks are expected to run and not error. b. If any tasks return an error, the Task Manager will cancel all running tasks and then run the Cleanup for each task.
- When the Task Manager's context is canceled, each task process will have their context canceled
- Each Task's Cleanup function is called in reverse order they were added to the Task Manager
Task interface:
// A Task is anything that can be managed by the TaskManager and added before the taskmanager
// start running. Any errors will cause the process to exit as all tasks are expected to run without erros
type Task interface {
// Initializate functions are ran serially in the order they were added to the TaskManager.
// These are useful when one Goroutine dependency requires a previous Worker to setup some common
// dendency like a DB connection.
Initialize() error
// Execute is the main Async function to house all the multi-threaded logic handled by GoAsync.
Execute(ctx context.Context) error
// Clenup functions are ran serially in reverse order they were added to the TaskManager.
// This way the 1st Initialze dependency is stopped last
Cleanup() error
}
Execute Task
Can be added to a process that is already running
Exeute Task interface:
// A ExecuteTask can be added to a Task Manager before or after it has already started managin the tasks.
// These tasks are expected to already be properly Initialized and don't require any Cleanup Code.
type ExecuteTask interface {
// Execute is the main Async function to house all the multi-threaded logic handled by GoAsync.
Execute(ctx context.Context) error
}
Provided tasks
For a number of common basic tasks provided, see tasks directory
Installation
go get -u github.com/DanLavine/goasync
Examples
For a few simple and basic real world example check out the internal/examples dir
Running tests
To run all tests:
go test --race ./...
If we want to run one specific test we can use:
go test --race -run [NAME OF TEST] ./...
To ignore the test cache:
go test --race -count=1 ./...
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AsyncTaskManager ¶
type AsyncTaskManager interface {
// Add a task before running the task manager
AddTask(name string, task Task) error
// add a task to an already running task manager
AddExecuteTask(name string, task ExecuteTask) error
// run the task manager
Run(context context.Context) []NamedError
}
AsyncTaskManager manages any number of tasks
type Config ¶
type Config struct {
// When set to 'true' and TaskManager.Execute(...) returning will cause the task mangager to shut down.
// When set to 'false' a TaskManager.Execute(...) returning will not cause the task manager to shut down. It
// will only shutdown when the original context is canceled.
AllowExecuteFailures bool
// Paramter is only used when AllowExecuteFailures = true.
// If set to 'true', will hold on to and report errors when context is canceled
// If set to 'false', will not report any errors when context is canceled
ReportErrors bool
// When set tot 'true', this will allow the TaskManager to run even if no tasks are currently being managed. The use case
// here is to allow for the the TaskManager.AddRunningTask(...) to periodically be called and
// those process might just end. For example a TCP server that has clients connecting and disconnecting
// can be used to add tasks here. But we would still want to cancel them when the original context
// is told to close (aka shutdown the server)
AllowNoManagedProcesses bool
}
func RelaxedConfig ¶
func RelaxedConfig() Config
Default configuration that allows tasks stop executing without a failure and no errors will be reported
func StrictConfig ¶
func StrictConfig() Config
Default configuration that will cause an error if any tasks stop executing
type ExecuteTask ¶
type ExecuteTask interface {
// Execute is the main Async function to contain all the multi-threaded logic handled by GoAsync.
Execute(ctx context.Context) error
}
A ExecuteTask can be added to an AsyncTaskManager before or after it has already started managin the tasks. These tasks are expected to already be properly Initialized and don't require any Cleanup Code.
type NamedError ¶
type Task ¶
type Task interface {
// Initializate functions are ran serially in the order they were added to the AsyncTaskManager.
// These are useful when one go routine dependency requires a previous Worker to setup some common
// dendency like a DB connection.
Initialize() error
// Execute is the main Async function to contain all the multi-threaded logic handled by GoAsync.
Execute(ctx context.Context) error
// Clenup functions are ran serially in reverse order they were added to the AsyncTaskManager.
// This way the 1st Initialze dependency is cleaned up last
Cleanup() error
}
A Task is anything that can be managed by the AsyncTaskManager and added before the taskmanager start running. Any errors will cause the process to exit as all tasks are expected to run without errors
type TaskManager ¶
type TaskManager struct {
// contains filtered or unexported fields
}
TaskManager implements the AsyncTaskManager interface and contains the logic for managing any Tasks proovided to this struct.
func NewTaskManager ¶
func NewTaskManager(config Config) *TaskManager
PARAMS: * config - configuration to use. Handles error reporting and use cases for terminating the managed tasks RETURNS: * *TaskManager - configured task manager
Create a new task manager for async tasks
func (*TaskManager) AddExecuteTask ¶
func (t *TaskManager) AddExecuteTask(name string, task ExecuteTask) error
PARAMS: * name - name of the task. On any errors this will be reported with the name * task - task to be managed RETURNS * error - any errors when adding the task to be managed
AddExecuteTask can be used to add a new task to the Taskmanger before or after it is already running
func (*TaskManager) AddTask ¶
func (t *TaskManager) AddTask(name string, task Task) error
PARAMS: * name - name of the task. On any errors this will be reported with the name * task (required) - task to be managed, cannot be nil RETURNS * error - any errors when adding the task to be managed
Add a task to the TaskManager. All tasks added this way must be called before the Run(...) function so their Inintialize() function can be called in the proper order
func (*TaskManager) Run ¶
func (t *TaskManager) Run(ctx context.Context) []NamedError
PARAMS: * ctx - context to stop the TaskManager RETURNS: * []NamedError - slice of errors with the name of the failed task
Run any tasks added to the TaskManager.
Rules for Tasks (added before Run):
1. Run each Initialize process serially in the order they were added to the TaskManager
a. If an error occurs, stop Initializng any remaning tasks. Also Run Cleanup for any tasks that have been Initialized.
2. In Parallel Run all Execute(...) functions for any tasks
a. All tasks are expected to run and not error.
b. If any tasks return an error, the TaskManager will cancel all running tasks and then run the Cleanup for each task if configured to do so.
3. Once the context ic canceled, each task process will have their context canceled
4. Each Task's Cleanup function is called in reverse order they were added to the TaskManager
Rules for adding tasks (added after Run):
1. These tasks will also cause the Task Manager to shutdown if an error is encountered depending on configuration
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Code generated by counterfeiter.
|
Code generated by counterfeiter. |
|
internal
|
|