mediocregopher/mediocre-go-lib
1
0
Fork 0
Code Releases Activity

mrun: update docs

Browse Source
This commit is contained in:
Brian Picciano 2019-05-18 12:36:53 -06:00
parent d5044ad7cb
commit 60ea7d98eb
2 changed files with 33 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
mrun/hook.go
View File

@ -105,23 +105,7 @@ func triggerHooks(ctx context.Context, userKey interface{}, next func([]hookEl)
//
// If the Context has children (see the mctx package), and those children have
// Hooks registered under this key, then their Hooks will be called in the
// expected order. For example:
//
// // parent context has hookA registered
// ctx := context.Background()
// ctx = WithHook(ctx, 0, hookA)
//
// // child context has hookB registered
// childCtx := mctx.NewChild(ctx, "child")
// childCtx = WithHook(childCtx, 0, hookB)
// ctx = mctx.WithChild(ctx, childCtx) // needed to link childCtx to ctx
//
// // parent context has another Hook, hookC, registered
// ctx = WithHook(ctx, 0, hookC)
//
// // The Hooks will be triggered in the order: hookA, hookB, then hookC
// err := TriggerHooks(ctx, 0)
//
// expected order. See package docs for an example.
func TriggerHooks(ctx context.Context, key interface{}) error {
return triggerHooks(ctx, key, func(hookEls []hookEl) (hookEl, []hookEl) {
return hookEls[0], hookEls[1:]

38
mrun/mrun.go
View File

@ -1,5 +1,31 @@
// Package mrun extends mctx to include runtime event hooks and tracking of the
// liveness of spawned go-routines.
// Package mrun provides the ability to register callback hooks on contexts, as
// well as some convenience functions which allow using a context as a
// wait-group.
//
// Hooks
//
// Hooks are registered onto contexts and later called in bulk. mrun will take
// into account the order Hooks are registered, including Hooks within a
// context's children (see mctx 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
// }
// }
//
// ctx := context.Background()
// ctx = mrun.WithStartHook(ctx, newHook(0))
//
// child := mctx.NewChild(ctx, "child")
// child = mrun.WithStartHook(child, newHook(1))
// ctx = mctx.WithChild(ctx, child)
//
// ctx = mrun.WithStartHook(ctx, newHook(2))
// mrun.Start(ctx) // prints "0", "1", then "2"
//
package mrun
import (
@ -36,9 +62,9 @@ func (fe *futureErr) set(err error) {
type threadCtxKey int
// 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.
// 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.
func WithThreads(ctx context.Context, n uint, fn func() error) context.Context {
// I dunno why this would happen, but it wouldn't actually hurt anything
if n == 0 {
@ -68,7 +94,7 @@ var ErrDone = errors.New("Wait is done waiting")
// 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
// be from the same WithThreads call.
// 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