mediocre-go-lib: github.com/mediocregopher/mediocre-go-lib/mrun Index | Files

package mrun

import "github.com/mediocregopher/mediocre-go-lib/mrun"

Package mrun provides the ability to register callback hooks on Components, as well as some convenience functions which allow using a context as a wait-group.

Hooks

Hooks are registered onto Components and later called in bulk. mrun will take into account the order Hooks are registered, including Hooks within a Component's children (see mcmp package), and execute them in the same order they were registered. For example:

newHook := func(i int) mrun.Hook {
	return func(context.Context) error {
		fmt.Println(i)
		return nil
	}
}

cmp := new(mcmp.Component)
mrun.InitHook(cmp, newHook(0))

cmpChild := cmp.Child("child")
mrun.InitHook(cmpChild, newHook(1))

mrun.InitHook(cmp, newHook(2))
mrun.Init(context.Background(), cmp) // prints "0", "1", then "2"

Index

Package Files

hook.go mrun.go

Variables

var ErrDone = errors.New("Wait is done waiting")

ErrDone is returned from Wait if cancelCh is closed before all threads have returned.

func AddHook Uses

func AddHook(cmp *mcmp.Component, key interface{}, hook Hook)

AddHook registers a Hook under a typed key. The Hook will be called when TriggerHooks is called with that same key. Multiple Hooks can be registered for the same key, and will be called sequentially when triggered.

Hooks will be called with whatever Context is passed into TriggerHooks.

func Init Uses

func Init(ctx context.Context, cmp *mcmp.Component) error

Init runs all Hooks registered using InitHook. This is a special case of TriggerHooks.

func InitHook Uses

func InitHook(cmp *mcmp.Component, hook Hook)

InitHook registers the given Hook to run when Init is called. This is a special case of AddHook.

As a convention Hooks running on the init event should block only as long as it takes to ensure that whatever is running can do so successfully. For short-lived tasks this isn't a problem, but long-lived tasks (e.g. a web server) will want to use the Hook only to initialize, and spawn off a go-routine to do their actual work. Long-lived tasks should set themselves up to shutdown on the shutdown event (see ShutdownHook).

func Shutdown Uses

func Shutdown(ctx context.Context, cmp *mcmp.Component) error

Shutdown runs all Hooks registered using ShutdownHook in the reverse order in which they were registered. This is a special case of TriggerHooks.

func ShutdownHook Uses

func ShutdownHook(cmp *mcmp.Component, hook Hook)

ShutdownHook registers the given Hook to run when Shutdown is called. This is a special case of AddHook.

See InitHook for more on the relationship between Init(Hook) and Shutdown(Hook).

func TriggerHooks Uses

func TriggerHooks(
    ctx context.Context,
    cmp *mcmp.Component,
    key interface{},
) error

TriggerHooks causes all Hooks registered with AddHook on the Component under the given key to be called in the order they were registered. The given Context is passed into all Hooks being called.

If any Hook returns an error no further Hooks will be called and that error will be returned.

If the Component has children (see the mcmp package), and those children have Hooks registered under this key, then their Hooks will be called in the expected order. See package docs for an example.

func TriggerHooksReverse Uses

func TriggerHooksReverse(ctx context.Context, cmp *mcmp.Component, key interface{}) error

TriggerHooksReverse is the same as TriggerHooks except that registered Hooks are called in the reverse order in which they were registered.

func Wait Uses

func Wait(ctx context.Context, cancelCh <-chan struct{}) error

Wait blocks until all go-routines spawned using WithThreads on the passed in Context (and its predecessors) have returned. Any number of the go-routines may have returned already when Wait is called, and not all go-routines need to be from the same WithThreads call.

If any of the thread functions returned an error during its runtime Wait will return that error. If multiple returned an error only one of those will be returned. TODO: Handle multi-errors better.

If cancelCh is not nil and is closed before all threads have returned then this function stops waiting and returns ErrDone.

Wait is safe to call in parallel, and will return the same result if called multiple times.

func WithThreads Uses

func WithThreads(ctx context.Context, n uint, fn func() error) context.Context

WithThreads spawns n go-routines, each of which executes the given function. The returned Context tracks these go-routines, and can then be passed into the Wait function to block until the spawned go-routines all return.

type Hook Uses

type Hook func(context.Context) error

Hook describes a function which can be registered to trigger on an event via the WithHook function.

Package mrun imports 3 packages (graph) and is imported by 11 packages. Updated 2019-08-02. Refresh now. Tools for package owners.