octopus

README

Octopus

Overview

This repository provides a simple set of tools to run a framework consisting of multiple concurrent tasks.

An Octopus object exposes a method Run(ctx context.Context) that executes a list of tasks and stops when:

• the input ctx is canceled (Canceled termination)
• a supported os.Signal is intercepted (the Termination depends on the behavior)

The user can define the Behavior of the Octopus by providing the relation between every supported signal and the corresponding desired Termination. The user may also defined a custom logger for message logging.

The user can specify the tasks to run concurrently by means of two Options:

• WithTasks defines the tasks to be executed as soon as Run is called;
• WithBlockedTasks defines the tasks that will be kept on hold until a Termination occurs.

How to clone

go get -u github.com/antonioiubatti93/octopus

How to use

A realistic example consists in setting up a framework to control the graceful shutdown of a HTTP server:

package main

import (
    "context"
    "errors"
    "net/http"
    "os"

    "github.com/antonioiubatti93/octopus"
)

func main(){
    // Define a trivial handler that replies with 200.
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    server = &http.Server{
        Addr: ":8080",
        Handler: mux,
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    
    const stop octopus.Termination = "stop"

    o := octopus.New(
        WithTasks(func() error {
            // This function starts the HTTP listener and check for errors when it returns.
            if err := server.ListenAndServe(); err != nil && !errors.As(err, &http.ErrServerClosed) {
                return err
            }
            return nil
        }),
        WithBlockedTasks(func() error {
            // This function invokes the HTTP Shutdown as soon as a termination is intercepted.
            if err := server.Shutdown(ctx); err != nil && !errors.Is(err, ctx.Err()) {
                return err
            }
            return nil
        }),
        WithBehavior(map[os.Signal]octopus.Termination{
            syscall.SIGTERM: stop,
            syscall.SIGINT: stop,
        }),
    )

    switch termination := o.Run(ctx); termination {
    case stop:
        os.Exit(0)
    default:
        os.Exit(1)
    }
}

Documentation

Index

• type Behavior
• type Octopus
  • func New(opts ...Option) *Octopus
  • func (o *Octopus) Run(ctx context.Context) Termination
• type Option
  • func WithBehavior(behavior map[os.Signal]Termination) Option
  • func WithBlockedTasks(tasks ...Task) Option
  • func WithLogger(logger logger) Option
  • func WithTasks(tasks ...Task) Option
• type Task
• type Termination

Types

type Behavior

type Behavior = map[os.Signal]Termination

Behavior defines the relation between each supported signal and a custom type of framework termination.

type Octopus

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

Octopus runs a framework consisting of multiple concurrent tasks.

func New

func New(opts ...Option) *Octopus

New returns an Octopus with custom options.

func (*Octopus) Run

func (o *Octopus) Run(ctx context.Context) Termination

Run executes the framework with an input context.

type Option

type Option func(*Octopus)

Option defines an Octopus option.

func WithBehavior

func WithBehavior(behavior map[os.Signal]Termination) Option

WithBehavior sets the behavior of Octopus with respect to each input signal. The map values are customizable and their meaning is defined by the caller.

func WithBlockedTasks

func WithBlockedTasks(tasks ...Task) Option

WithBlockedTasks defines the blocked tasks that Octopus will run. These tasks will be executed only once the framework is done: - when a supported signal is received; - when the context expires.

func WithLogger

func WithLogger(logger logger) Option

WithLogger sets the Octopus logger.

func WithTasks

func WithTasks(tasks ...Task) Option

WithTasks defines the free tasks that Octopus will run. These tasks will be launched as soon as the framework starts.

type Task

type Task func() error

Task defines the type of executable routines.

type Termination

type Termination string

Termination defines the type of workflow termination.

const (
	// Canceled defines the termination upon expired context.
	Canceled Termination = "Canceled"
	// Unexpected defines the Unexpected termination.
	Unexpected Termination = "Unexpected"
)