ctx

func (*Context) AttachInterruptHandler ¶

func (c *Context) AttachInterruptHandler()

AttachInterruptHandler creates a new interupt handler and fuses it w/ the given context

func (*Context) BaseContext ¶

func (c *Context) BaseContext() *Context

BaseContext allows the holder of a Ctx to get the raw/underlying Context.

func (*Context) Ctx ¶

func (c *Context) Ctx() *Context

Ctx is an abstraction for a context that can be stopped and waited on.

Ctx is a bridge between a Context expressed directly as *struct or as an interface offering abstraction.

func (*Context) CtxAddChild ¶

func (c *Context) CtxAddChild(
	inChild Ctx,
	inID []byte,
)

CtxAddChild adds the given Context as a "child", where c will initiate CtxStop() on each child before c carries out its own stop.

func (*Context) CtxChildCount ¶

func (c *Context) CtxChildCount() int

CtxChildCount returns the number of child contexts that have been added to this context and have not yet stopped.

Warning: the child count returned is backward-looking (since any number of children could theoretically have stopped or been added in the time following this call executing). Therefore, in order for this call to be useful, the caller should take precautions to ensure that this possibility is removed.

func (*Context) CtxGetChildByID ¶

func (c *Context) CtxGetChildByID(
	childID []byte,
) Ctx

CtxGetChildByID returns the child Context with a matching ID (or nil if not found).

func (*Context) CtxGo ¶

func (c *Context) CtxGo(
	childTask func(),
)

CtxGo runs the given task in a new goroutine such that c.CtxWait() will block until the child task exits.

The purpose of this is to remove code you would historically maintain to wait on a task. The presumption here is that task will exit via some trigger *other* than c.CtxWait()

func (*Context) CtxOnFault ¶

func (c *Context) CtxOnFault(inErr error, inDesc string)

CtxOnFault is called when the given error has occurred an represents an unexpected fault that alone doesn't justify an emergency condition. (e.g. a db error while accessing a record). Call this on unexpected errors.

If inErr == nil, this call has no effect.

THREADSAFE

func (*Context) CtxPrintDebug ¶

func (c *Context) CtxPrintDebug()

CtxPrintDebug prints a listing of all child contexts in an indented format.

func (*Context) CtxRunning ¶

func (c *Context) CtxRunning() bool

CtxRunning returns true has been started and has not stopped. See also CtxStopped(). This is typically used to detect if/when a dependent workflow should cease.

THREADSAFE

func (*Context) CtxStart ¶

func (c *Context) CtxStart(
	onStartup func() error,
	onStopIssued func(),
	onChildAboutToStop func(inChild Ctx),
	onStopping func(),
) error

CtxStart calls the given start func and returns the error. If no error occurred, this Context is in a "running" state until CtxStop() is called.

See notes for CtxStop()

func (*Context) CtxStatus ¶

func (c *Context) CtxStatus() error

CtxStatus returns an error if this Context has not yet started, is stopping, or has stopped.

THREADSAFE

func (*Context) CtxStop ¶

func (c *Context) CtxStop(
	stopReason string,
	releaseOnComplete *sync.WaitGroup,
) bool

CtxStop initiates a stop of this Context, calling releaseOnComplete.Done() when this context is fully stopped (if provided).

If c.CtxStop() is being called for the first time, true is returned. If it has already been called (or is in-flight), then false is returned and this call effectively is a no-op (but still honors in releaseOnComplete).

The following are equivalent:

        initiated := c.CtxStop(reason, waitGroup)

        initiated := c.CtxStop(reason, nil)
        c.CtxWait()
        if waitGroup != nil {
            waitGroup.Done()
        }

When c.CtxStop() is called (for the first time):

1. c.onStopIssued() is called (if provided to c.CtxStart)
2. if c has a parent, c is detached and the parent's onChildAboutToStop(c) is called (if provided to c.CtxStart).
3. c.CtxStopChildren() is called, blocking until all children are stopped (recursive)
4. c.Context is canceled, causing any <-CtxStopping() calls to be unblocked.
5. c's onStopping() is called (if provided to c.CtxStart)
6. After the last call to c.CtxGo() has completed, c.CtxWait() is released.

func (*Context) CtxStopChildren ¶

func (c *Context) CtxStopChildren(stopReason string)

CtxStopChildren initiates a stop on each child and blocks until complete.

func (*Context) CtxStopReason ¶

func (c *Context) CtxStopReason() string

CtxStopReason returns the reason provided by the stop initiator.

func (*Context) CtxStopped ¶

func (c *Context) CtxStopped() bool

CtxStopped returns true if CtxStop() is currently in flight (or has completed).

Warning: this is NOT the opposite of CtxRunning(). c.CtxStopped() will return true when c.CtxStop() is called vs c.CtxRunning() will return true until all of c's children have stopped.

THREADSAFE

func (*Context) CtxStopping ¶

func (c *Context) CtxStopping() <-chan struct{}

CtxStopping allows callers to wait until this context is stopping.

func (*Context) CtxWait ¶

func (c *Context) CtxWait()

CtxWait blocks until this Context has completed stopping (following a CtxStop). Returns true if this call initiated the shutdown (vs another cause)

THREADSAFE

func (*Context) Debugf ¶

func (l *Context) Debugf(format string, args ...interface{})

Debugf is a convenience function that maps to Infof(2, ...)

func (*Context) Error ¶

func (l *Context) Error(args ...interface{})

Error logs to the ERROR, WARNING, and INFO logs. Arguments are handled like fmt.Print(); a newline is appended if missing.

Errors are reserved for situations that indicate an implementation deficiency, a corruption of data or resources, or an issue that if not addressed could spiral into deeper issues. Logging an error reflects that correctness or expected behavior is either broken or under threat.

func (*Context) Errorf ¶

func (l *Context) Errorf(format string, args ...interface{})

Errorf logs to the ERROR, WARNING, and INFO logs. Arguments are handled like fmt.Print; a newline is appended if missing.

See comments above for Error() for guidelines on errors vs warnings.

func (*Context) Fatalf ¶

func (l *Context) Fatalf(format string, args ...interface{})

Fatalf logs to the FATAL, ERROR, WARNING, and INFO logs, Arguments are handled like fmt.Printf(); a newline is appended if missing.

func (*Context) GetLogLabel ¶

func (l *Context) GetLogLabel() string

GetLogLabel returns the label last set via SetLogLabel()

func (*Context) GetLogPrefix ¶

func (l *Context) GetLogPrefix() string

GetLogPrefix returns the the text that prefixes all log messages for this context.

func (*Context) Info ¶

func (l *Context) Info(verboseLevel int32, args ...interface{})

Info logs to the INFO log. Arguments are handled like fmt.Print(); a newline is appended if missing.

Verbose level conventions:

0. Enabled during production and field deployment. Use this for important high-level events.
1. Enabled during testing and development. Use for high-level changes in state, mode, or connection.
2. Enabled during low-level debugging and troubleshooting.

By convention, level 0 is the default verbose level when software is deployed.

func (*Context) Infof ¶

func (l *Context) Infof(verboseLevel int32, format string, args ...interface{})

Infof logs to the INFO log. Arguments are handled like fmt.Printf(); a newline is appended if missing.

See comments above for Info() for guidelines for verboseLevel.

func (*Context) LogV ¶

func (l *Context) LogV(verboseLevel int32) bool

LogV returns true if logging is currently enabled for log verbose level.

func (*Context) SetLogLabel ¶

func (l *Context) SetLogLabel(label string)

SetLogLabel sets the label prefix for all entries logged.

func (*Context) SetLogLabelf ¶

func (l *Context) SetLogLabelf(format string, args ...interface{})

SetLogLabelf is the formatted version of SetLogLabel

func (*Context) Warn ¶

func (l *Context) Warn(args ...interface{})

Warn logs to the WARNING and INFO logs. Arguments are handled like fmt.Print(); a newline is appended if missing.

Warnings are reserved for situations that indicate an inconsistency or an error that won't result in a departure of specifications, correctness, or expected behavior.

func (*Context) Warnf ¶

func (l *Context) Warnf(format string, args ...interface{})

Warnf logs to the WARNING and INFO logs. Arguments are handled like fmt.Printf(); a newline is appended if missing.

See comments above for Warn() for guidelines on errors vs warnings.