async

README

Async goroutine sychronization & concurrency tool

How to use:

1. Job: safely run goroutines, supports graceful shutdown. (Credits: @kai.pei)

Example:

job := MakeJob()

// register in graceful/background listener
gracefulServer.Go(job) or background.Observe(job)

// invoke in any function
job.Go(func(){

	err := SomeFunc(arg1, arg2, ...)
	if err == nil {
		// error handling
	}
})

1. Threading: handles safe concurrent read & execution of data in multiple goroutine threads, and supports graceful shutdown.

Example:

th, err := MakeThreading(Util{
	Read:         func(offset, block int) (interface{}, error) { return []int{}, nil },
	Execute:      func(data interface{}, block int) error { return nil },
	MakeInterval: func() (idx, limit int, err error) { return 0, 100, nil },
	BlockSize:    10,
	Nodes:        5,
})
if err != nil {
	// error handling
}

// register in graceful/background listener
gracefulServer.Go(th) or background.Observe(th)


// run tasks
th.Go()

1. Background: handles graceful shutdown of background jobs when server is not running. If http server is not running, graceful cannot be used to shutdown running jobs. Instead, use the background listener.

Example:

// main function
background = NewListener()
defer background.Quit()


// function call
background.Observe(Job1)
background.Observe(Job2)
background.Observe(Cron1)
background.Observe(Cron2)


// notes: if signal termination is invoked at any time, the running jobs/cron will terminate gracefully.

Documentation

Index

• type Background
  • func NewListener() *Background
  • func (b *Background) Observe(task Task)
  • func (b *Background) Quit()
• type Job
  • func MakeJob() *Job
  • func (j *Job) Go(f func())
  • func (j *Job) Run()
  • func (j *Job) Shutdown(ctx context.Context) error
• type Task
• type Threading
  • func MakeThreading(d Util) (*Threading, error)
  • func (th *Threading) Go()
  • func (th *Threading) Run()
  • func (th *Threading) Shutdown(ctx context.Context) error
• type Util

Types

type Background

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

func NewListener

func NewListener() *Background

func (*Background) Observe

func (b *Background) Observe(task Task)

func (*Background) Quit

func (b *Background) Quit()

type Job

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

Job is an object whose handle can be specified in functions to safely manage the execution of multiple goroutines

func MakeJob

func MakeJob() *Job

MakeJob safely runs goroutines

func (*Job) Go

func (j *Job) Go(f func())

Go launches a goroutine and monitors its exit

Example calling a function in a goroutine.

j.Go(func(){

    err := SomeFunc(arg1, arg2, ...)
    if err == nil {
        // error handling
    }
})

func (*Job) Run

func (j *Job) Run()

Run for fitting the graceful Job interface

func (*Job) Shutdown

func (j *Job) Shutdown(ctx context.Context) error

Shutdown waits for running goroutines to return

type Task

type Task interface {
	Shutdown(ctx context.Context) error
}

type Threading

type Threading struct {

	// Read retrieves data in blocks
	Read func(offset, block int) (interface{}, error)
	// Execute processes data
	Execute func(data interface{}, block int) error
	// BlockSize of data processed in a single round of execution.
	BlockSize int
	// Nodes refers to number of running goroutines.
	Nodes int
	// contains filtered or unexported fields
}

Threading is an organized collection of goroutines that executes a single task concurrently.

func MakeThreading

func MakeThreading(d Util) (*Threading, error)

MakeThreading safely executes multiple goroutines to process a single task! It includes a Read and Execute operation, and expects offset & limit index of data to be processed.

func (*Threading) Go

func (th *Threading) Go()

Go executes tasks in multiple go-routines

func (*Threading) Run

func (th *Threading) Run()

Run for fitting the graceful Job interface

func (*Threading) Shutdown

func (th *Threading) Shutdown(ctx context.Context) error

Shutdown waits for running goroutines to return

type Util

type Util struct {
	// Read retrieves data in blocks
	Read func(offset, block int) (interface{}, error)
	// Execute processes data
	Execute func(data interface{}, block int) error
	// MakeInterval returns the offset and limit [a,b]
	// of data to be processed
	MakeInterval func() (idx, limit int, err error)
	// BlockSize of data processed in a single round of execution.
	BlockSize int
	// Nodes refers to number of running goroutines
	Nodes int
}