cog

README

Cog

Cog is a collection of utils for golang that I tend to use across many of my projects. Rather than building new cogs everywhere, I've just consolidated them all here. Cogs for everyone!

Modules

Cog consists of the following modules:

Module	Docs	Description
(root)		generic utils that didn't fit anywhere else
bytec		extra byte slice utils
cfs		filesystem utils
check		test assertions and isolated FS utils
cio		extra io utils
clog		a logging framework that looks a bit like python's logging
cnet		misc net utils and a socket implementation using channels
cort		extra sorting utilities
ctime		time utils
cync		some extra sync utils
encoding/capn		capnproto Marshaling and Unmarshaling
encoding/path		path Marshaling and Unmarshaling
node		get information about the local node
stack		runtime call stack utils
statc		application status and stats
stringc		extra strings utils
unsafec		making things more unsafe

Each module contains full documentation over on godoc, including tons of examples.

As you might have noticed, the modules have weirdly spelled names; this is so that you can, for example, import both "sync" and "cync" into the same file, since "cync" only supplements "sync".

Documentation

Overview

Package cog is a collection of utilities that I tend to use across many of my projects. Rather than reinventing the cog everywhere, I've just consolidated them all here.

Index

• func Assert(ok bool, msg string, args ...interface{})
• func BytesMust(b []byte, err error) []byte
• func Must(err error, msg string, args ...interface{})
• func Notify(ch chan<- struct{})
• type Errors
  • func (es *Errors) Add(err error)
  • func (es *Errors) Addf(err error, format string, args ...interface{})
  • func (es *Errors) Drain(ch <-chan error)
  • func (es *Errors) Empty() bool
  • func (es *Errors) Error() error
  • func (es *Errors) Prefix(prefix string) *Errors
  • func (es *Errors) Reset()
• type Exit
  • func NewExit() *Exit
  • func (e *Exit) Exit()
  • func (e *Exit) Signal()
• type Exiter
• type GExit
  • func (e *GExit) AddCb(cb func())
  • func (e *GExit) AddExiter(ex Exiter)

Examples

• Errors
• Exit

Functions

func Assert

func Assert(ok bool, msg string, args ...interface{})

Assert ensures ensures that the given bool is true, or panics.

func BytesMust

func BytesMust(b []byte, err error) []byte

BytesMust ensures that a function that returns a ([]byte, error) does not error.

func Must

func Must(err error, msg string, args ...interface{})

Must ensures that no error occurred, or panics.

func Notify

func Notify(ch chan<- struct{})

Notify sends a struct{} down the channel without waiting

Types

type Errors

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

Errors holds a list of errors that can be combined into a single, line- delimited error message

Example

es := Errors{}

// Nothing added
es.Add(nil)
es.Addf(nil, "something describing the error: %d", 123)
fmt.Println("no errors:", es.Error())

// Errors logged
es.Add(fmt.Errorf("some error"))
es.Addf(fmt.Errorf("another error"), "something describing the error: %d", 123)
fmt.Println("errors:", es.Error())

Output:

no errors: <nil>
errors: some error
something describing the error: 123: another error

func (*Errors) Add

func (es *Errors) Add(err error)

Add adds an error to the collector. It's safe to call this when err==nil.

func (*Errors) Addf

func (es *Errors) Addf(err error, format string, args ...interface{})

Addf is like Add, but prefixes the error with the given format and args. If err==nil, this does nothing.

func (*Errors) Drain

func (es *Errors) Drain(ch <-chan error)

Drain removes every error from the given channel until the channel closes

func (*Errors) Empty

func (es *Errors) Empty() bool

Empty checks to see if any errors have been added

func (*Errors) Error

func (es *Errors) Error() error

Error combines all previous errors into a single error, or returns nil if there were no errors.

func (*Errors) Prefix

func (es *Errors) Prefix(prefix string) *Errors

Prefix returns an Errors for which all errors are prefixed with `prefix`.

func (*Errors) Reset

func (es *Errors) Reset()

Reset clears the state of Errors for use again

type Exit

type Exit struct {
	*GExit
	// contains filtered or unexported fields
}

Exit is useful for terminating a group of goroutines that run in a for{select{}}. Be sure to `Exit.Add(n)` before starting goroutines, and `defer Exit.Done()` in the goroutine.

Example

e := NewExit()

run := func(i int) {
	e.Add(1)
	fmt.Println(i, "started")

	go func() {
		defer e.Done()
		defer fmt.Println("exited")

		for {
			select {
			case <-e.C:
				return
			}
		}
	}()
}

for i := 0; i < 10; i++ {
	run(i)
}

// Wait for all goroutines to exit
e.Exit()

Output:

0 started
1 started
2 started
3 started
4 started
5 started
6 started
7 started
8 started
9 started
exited
exited
exited
exited
exited
exited
exited
exited
exited
exited

func NewExit

func NewExit() *Exit

NewExit creates a new Exit, useful for ensuring termination of goroutines on exit.

func (*Exit) Exit

func (e *Exit) Exit()

Exit closes C and waits for all goroutines to exit.

func (*Exit) Signal

func (e *Exit) Signal()

Signal tells everything to exit, but it doesn't wait.

type Exiter

type Exiter interface {
	Exit()
}

Exiter is anything that can cleanup after itself at any arbitrary point in time.

type GExit

type GExit struct {
	sync.WaitGroup
	C <-chan struct{}
	// contains filtered or unexported fields
}

GExit (short for "goroutine exit") is what should be passed to things that need to know when to exit but that should not be able to trigger an exit.

func (*GExit) AddCb

func (e *GExit) AddCb(cb func())

AddCb adds a function to be called on exit. Callbacks are called in the reverse order that they were added.

func (*GExit) AddExiter

func (e *GExit) AddExiter(ex Exiter)

AddExiter adds an Exiter to the exit list that is called when Exit() is called. Exiters are called in the reverse order that they were added.