ev

Documentation

Overview

Package ev provides standardized goroutine management

events contain thread completions, failures and any type of data items. A manager launches and controls a set of goroutines

ctx.Result is defered by a gorutine, captures panics and sends the goroutine’s result using Success or Failure

func (ctx ev.Callee) {
  var err error
  defer func() {
    ctx.Result(&err, recover())
  }()
…

© 2020–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)

Index

• type Callee
  • func NewCallee(name string, gID GoID, eventTx chan<- Event, ctx0 context.Context) (ctx Callee)
• type CalleeContext
  • func (ctx *CalleeContext) Failure(err error)
  • func (ctx *CalleeContext) Result(errp *error)
  • func (ctx *CalleeContext) ResultV(errp *error, recoverValue interface{})
  • func (ctx *CalleeContext) Send(payload interface{})
  • func (ctx *CalleeContext) Success()
  • func (ctx *CalleeContext) Thread() (name string, gID GoID)
• type CancelAction
• type DataEvent
  • func (ev *DataEvent) Payload() (payload interface{})
• type EmptyEvent
  • func NewEmptyEvent(gID GoID) *EmptyEvent
  • func (ev *EmptyEvent) GoID() (gID GoID)
• type EvThread
  • func NewEvThread(name string) (ti *EvThread)
• type Event
  • func NewDataEvent(gID GoID, payload interface{}) (evt Event)
  • func NewExitEvent(e error, gID GoID) (evt Event)
• type EventRx
• type ExitEvent
• type GoID
• type Manager
  • func NewManager(ctx0 context.Context) (mgr Manager)
• type ThreadManager
  • func (mgr *ThreadManager) Action(threadResult error, action CancelAction) (isEnd bool)
  • func (mgr *ThreadManager) CalleeContext(ID ...string) (env Callee)
  • func (mgr *ThreadManager) Cancel() (isEnd bool)
  • func (mgr *ThreadManager) Count() (count int64)
  • func (mgr *ThreadManager) Events() (out EventRx)
  • func (mgr *ThreadManager) IsEnd() (isEnd bool)
  • func (mgr *ThreadManager) ProcessEvent(ev Event) (err error)
  • func (mgr *ThreadManager) Threads() (names []string, IDs []GoID)

Types

type Callee

type Callee interface {
	context.Context                                // Deadline Done Err Value
	Success()                                      // Success indicates this goruote terminated successfully
	Failure(err error)                             // Failure indicates this goroutine failed with err
	Result(errp *error)                            // recovery for gorutines: usage: defer ctx.Result(&err)
	ResultV(errp *error, recoverValue interface{}) // recovery for gorutines
	Thread() (name string, ID GoID)                // Thread provides information about the thread
	Send(payload interface{})                      // Send allows a goroutine to send custom types
}

Callee provides functions for a called goroutine

func NewCallee

func NewCallee(name string, gID GoID, eventTx chan<- Event, ctx0 context.Context) (ctx Callee)

NewCallee provides a Calle implementation, data used by a managed goroutine

type CalleeContext

type CalleeContext struct {
	context.Context
	// contains filtered or unexported fields
}

CalleeContext provides for a goroutine to communicate with the caller

func (*CalleeContext) Failure

func (ctx *CalleeContext) Failure(err error)

func (*CalleeContext) Result

func (ctx *CalleeContext) Result(errp *error)

func (*CalleeContext) ResultV

func (ctx *CalleeContext) ResultV(errp *error, recoverValue interface{})

func (*CalleeContext) Send

func (ctx *CalleeContext) Send(payload interface{})

Send allows a groutine to send any event

func (*CalleeContext) Success

func (ctx *CalleeContext) Success()

func (*CalleeContext) Thread

func (ctx *CalleeContext) Thread() (name string, gID GoID)

type CancelAction

type CancelAction uint8

CancelAction holds strategy for when a goruotine terminates

const (
	// TerminateAll terminates other goroutines on first termination
	TerminateAll CancelAction = iota
	// KeepGoing waits for all goroutines to complete even on errors
	KeepGoing
	// WhileOk terminates if any goroutine errors
	WhileOk
)

type DataEvent

type DataEvent struct {
	EmptyEvent
	// contains filtered or unexported fields
}

DataEvent is an event with an empty interface data value. The goroutine defines an exported unique type that it sends using ctx.Send(payload). The main evvent loop checks the type of the pyload against the exported unique type

func (*DataEvent) Payload

func (ev *DataEvent) Payload() (payload interface{})

Payload returns the data value of a DataEvent

type EmptyEvent

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

EmptyEvent is an event with no data

func NewEmptyEvent

func NewEmptyEvent(gID GoID) *EmptyEvent

func (*EmptyEvent) GoID

func (ev *EmptyEvent) GoID() (gID GoID)

GoID returns the id of the sending goroutine

type EvThread

type EvThread struct {
	ID   GoID
	Name string
}

EvThread holds manager information for a running goroutine

func NewEvThread

func NewEvThread(name string) (ti *EvThread)

NewEvThread holds manager information for a running goroutine

type Event

type Event interface {
	GoID() (gID GoID) // [16]byte
}

Event is a message passed from goroutines

func NewDataEvent

func NewDataEvent(gID GoID, payload interface{}) (evt Event)

NewDataEvent creates an event with payload of a single data value

func NewExitEvent

func NewExitEvent(e error, gID GoID) (evt Event)

NewExitEvent holds the outcome of a goruotine

type EventRx

type EventRx <-chan Event

EventRx receives events from goroutines

type ExitEvent

type ExitEvent struct {
	EmptyEvent
	Err       error
	IsCancel  bool
	IsTimeout bool
}

ExitEvent holds the outcome of a goruotine

type GoID

type GoID uuid.UUID

GoID is a unique value identifying a goroutine

type Manager

type Manager interface {
	Cancel() (isEnd bool)                    // Cancel signals to all goroutines to terminate
	Events() (ch EventRx)                    // Events provides the channel emitting events from goroutines
	CalleeContext(ID ...string) (ctx Callee) // CalleeContext context for a new goroutine, 0 or 1 argument
	ProcessEvent(event Event) (err error)    // ProcessEvent sanity checks an EventRx event
	Action(evResult error, action CancelAction) (awaitThreads bool)
	IsEnd() (isEnd bool)                   // IsEnd returns true if all goroutines have terminated
	Threads() (names []string, IDs []GoID) // Threads provide information on currently managed goroutines
}

Manager provides management of goroutines

func NewManager

func NewManager(ctx0 context.Context) (mgr Manager)

NewManager obtains instance for executing goroutines

type ThreadManager

type ThreadManager struct {
	Launch time.Time
	// contains filtered or unexported fields
}

ThreadManager provides thread-safe management of go routines

func (*ThreadManager) Action

func (mgr *ThreadManager) Action(threadResult error, action CancelAction) (isEnd bool)

Action determines whether the executable should continue to wait for additional threads

func (*ThreadManager) CalleeContext

func (mgr *ThreadManager) CalleeContext(ID ...string) (env Callee)

CalleeContext produces an environment for calling a goroutine - thread safe

func (*ThreadManager) Cancel

func (mgr *ThreadManager) Cancel() (isEnd bool)

Cancel shuts down all goroutines

func (*ThreadManager) Count

func (mgr *ThreadManager) Count() (count int64)

Count determines remaining goroutines

func (*ThreadManager) Events

func (mgr *ThreadManager) Events() (out EventRx)

Events gets the channel emitting messages from goroutines

func (*ThreadManager) IsEnd

func (mgr *ThreadManager) IsEnd() (isEnd bool)

IsEnd determines if all goroutines have terminated

func (*ThreadManager) ProcessEvent

func (mgr *ThreadManager) ProcessEvent(ev Event) (err error)

ProcessExit indicates whether this event is the final event from a terminating goroutine

func (*ThreadManager) Threads

func (mgr *ThreadManager) Threads() (names []string, IDs []GoID)