core

package module
v0.15.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2024 License: MIT Imports: 19 Imported by: 67

README

Core of helpers for darvaza.org projects

Go Reference Go Report Card

This package contains simple mechanisms used by other darvaza-proxy projects. It's not allowed to have dependencies outside of Go' Standard Library, and if something should be on a subdirectory, it shouldn't be here.

Network

  • GetInterfacesNames
  • ParseAddr/ParseNetIP
  • SplitHostPort/SplitAddrPort
  • JoinHostPort/MakeHostPort
  • AddrPort
  • AddrFromNetIP
  • GetIPAddresses/GetNetIPAddresses/GetStringIPAddresses

Generics

  • Zero/IsZero
  • Coalesce/IIf
  • As/AsFn
  • SliceAs/SliceAsFn
  • SliceContains/SliceContainsFn
  • SliceEqual/SliceEqualFn
  • SliceMinus/SliceMinusFn
  • SliceUnique/SliceUniqueFn
  • SliceUniquify/SliceUniquifyFn
  • SliceReplaceFn/SliceCopy/SliceCopyFn/SliceMap
  • SliceRandom
  • SliceSort/SliceSortFn/SliceSortOrdered
  • SliceReverse/SliceReversed/SliceReversedFn
  • ListContains/ListContainsFn
  • ListForEach/ListForEachElement
  • ListForEachBackward/ListForEachBackwardElement
  • ListCopy/ListCopyFn
  • MapContains
  • MapListContains/MapListContainsFn
  • MapListForEach/MapListForEachElement
  • MapListInsert/MapListAppend
  • MapListInsertUnique/MapListInsertUniqueFn
  • MapListAppendUnique/MapListAppendUniqueFn
  • MapListCopy/MapListCopyFn
  • MapAllListContains/MapAllListContainsFn
  • MapAllListForEach/MapAllListForEachElement
  • MapValue
  • Keys()/SortedKeys()
  • NewContextKey

Errors

Wrappers

The Unwrappable type represents the classic Unwrap() error interface implemented by WrappedError, while the Errors interface represents Errors() []error.

There are three factories for Unwrappable, the standard "note: error description", one for formatted notes, and a quiet one, not including the text of the original error unless unwrapped first.

  • Wrap(err, note) with a simple string,
  • Wrapf(err, format, args...) when using a formatted note,
  • and QuietWrapf(err, format, args...) for formatted errors not including the wrapped message in the text.

The Unwrap(err error) []error helper returns a slice of non-nil sub-errors built from the following interfaces:

  • Unwrap() []error
  • Errors() []error
  • Unwrap() error

For agreggating multiple errors and the Unwrap() []error or Errors() []error interfaces we have the CompoundError.

Panic and Recover

A PanicError is a special wrapper that includes a StackTrace and can wrap anything and it's especially useful when used combined the standard recover() as shown below:

defer func() {
  if err := core.AsRecovered(recover()); err != nil {
    // ...
  }
}()

This construct will return nil if there was a panic, pass-through the error if it implements the Recovered interface, or wrap anything else in a PanicError.

Catch() is a companion of PanicError which will allows you to call a function and either receive its organic error or a PanicError if it panicked, using a Catcher instance internally.

To panic() automatically wrapping the reason in PanicError{} the following helpers can be used:

  • Panic(),
  • Panicf(),
  • and PanicWrap.

  • CoalesceError

  • AsError/AsErrors

  • IsError/IsErrorFn/IsErrorFn2

  • IsTemporary/CheckIsTemporary

  • IsTimeout/CheckIsTimeout

  • TemporaryError/NewTemporaryError/NewTimeoutError

  • WaitGroup/ErrGroup

  • Frame/Stack

  • Here/StackFrame/StackTrace

  • CallStacker

  • ErrNotImplemented/ErrTODO

  • ErrExists/ErrNotExists

  • ErrInvalid/ErrUnknown

  • ErrNilReceiver

Synchronization
  • SpinLock

See also

Documentation

Overview

Package core provides fundamental helpers for darvaza.org projects

Index

Constants

View Source 
const (
	// MaxDepth is the maximum depth we will go in the stack.
	MaxDepth = 32
)

Variables

View Source 
var (
	// ErrNotImplemented indicates something hasn't been implemented yet
	ErrNotImplemented = errors.New("not implemented")
	// ErrTODO is like ErrNotImplemented but used especially to
	// indicate something needs to be implemented
	ErrTODO = Wrap(ErrNotImplemented, "TODO")
	// ErrExists indicates something already exists
	ErrExists = errors.New("already exists")
	// ErrNotExists indicates something doesn't exist
	ErrNotExists = errors.New("does not exist")
	// ErrInvalid indicates an argument isn't valid
	ErrInvalid = errors.New("invalid argument")
	// ErrUnknown indicates something isn't recognized
	ErrUnknown = errors.New("unknown")
	// ErrNilReceiver indicates a method was called over a nil instance
	ErrNilReceiver = errors.New("nil receiver")
)

Functions

func AddrFromNetIP 

func AddrFromNetIP(addr net.Addr) (netip.Addr, bool)

AddrFromNetIP attempts to convert a net.Addr into a netip.Addr

func AddrPort 

func AddrPort(v any) (netip.AddrPort, bool)

AddrPort attempts to extract a netip.AddrPort from an object

func As added in v0.14.8 

func As[T, V any](v T) (V, bool)

As returns a value cast to a different type

func AsError added in v0.14.8 

func AsError[T any](v T) error

AsError attempts to convert a value to an error, checking different interfaces.

* AsError() error * Error() string * OK() bool * IsZero() bool

func AsErrors added in v0.14.8 

func AsErrors[T any](vv []T) []error

AsErrors uses AsError to return the subset of the elements that are errors.

func AsFn added in v0.14.8 

func AsFn[T, V any](fn func(T) (V, bool), v T) (V, bool)

AsFn returns a value cast to a different type using a helper function

func Catch added in v0.14.10 

func Catch(fn func() error) error

Catch uses a Catcher to safely call a function and return the organic error or the Recovered PanicError.

func CheckIsTemporary added in v0.13.2 

func CheckIsTemporary(err error) (is, known bool)

CheckIsTemporary tests an error for Temporary(), IsTemporary(), Timeout() and IsTimeout() without unwrapping.

func CheckIsTimeout added in v0.13.2 

func CheckIsTimeout(err error) (is, known bool)

CheckIsTimeout tests an error for Timeout() and IsTimeout() without unwrapping.

func Coalesce 

func Coalesce[T any](opts ...T) T

Coalesce returns the first non-zero argument

func CoalesceError added in v0.9.5 

func CoalesceError(errs ...error) error

CoalesceError returns the first non-nil error argument. error isn't compatible with Coalesce's comparable generic type.

func GetIPAddresses 

func GetIPAddresses(ifaces ...string) ([]netip.Addr, error)

GetIPAddresses returns a list of netip.Addr bound to the given interfaces or all if none are given

func GetInterfacesNames 

func GetInterfacesNames(except ...string) ([]string, error)

GetInterfacesNames returns the list of interfaces, considering an optional exclusion list

func GetNetIPAddresses 

func GetNetIPAddresses(ifaces ...string) ([]net.IP, error)

GetNetIPAddresses returns a list of net.IP addresses bound to the given interfaces or all if none are given

func GetStringIPAddresses 

func GetStringIPAddresses(ifaces ...string) ([]string, error)

GetStringIPAddresses returns a list of text IP addresses bound to the given interfaces or all if none are given

func IIf 

func IIf[T any](cond bool, yes, no T) T

IIf returns one value or the other depending on a condition.

func IsError added in v0.13.0 

func IsError(err error, errs ...error) bool

IsError recursively check if the given error is in in the given list, or just non-nil if no options to check are given.

func IsErrorFn added in v0.13.0 

func IsErrorFn(check func(error) bool, errs ...error) bool

IsErrorFn recursively checks if any of the given errors satisfies the specified check function.

revive:disable:cognitive-complexity

func IsErrorFn2 added in v0.13.0 

func IsErrorFn2(check func(error) (bool, bool), errs ...error) (is bool, known bool)

IsErrorFn2 recursively checks if any of the given errors gets a certain answer from the check function. As opposed to IsErrorFn, IsErrorFn2 will stop when it has certainty of a false result.

revive:disable:cognitive-complexity

func IsTemporary added in v0.13.2 

func IsTemporary(err error) bool

IsTemporary tests an error for Temporary(), IsTemporary(), Timeout() and IsTimeout() recursively.

func IsTimeout added in v0.13.2 

func IsTimeout(err error) bool

IsTimeout tests an error for Timeout() and IsTimeout() recursively.

func IsZero added in v0.9.8 

func IsZero(vi any) bool

IsZero checks if a non-zero value has been set either by using the `IsZero() bool“ interface or reflection. nil and (*T)(nil) are considered to be zero.

func JoinHostPort added in v0.14.3 

func JoinHostPort(host, port string) (string, error)

JoinHostPort is like the standard net.JoinHostPort, but it validates the host name and port, and returns it portless if the port argument is empty.

func Keys added in v0.13.5 

func Keys[K comparable, T any](m map[K]T) []K

Keys returns the list of keys of a map

func ListContains 

func ListContains[T comparable](l *list.List, val T) bool

ListContains checks if a container/list contains an element

func ListContainsFn 

func ListContainsFn[T any](l *list.List, val T, eq func(T, T) bool) bool

ListContainsFn checks if a container/list contains an element that satisfies a given function

func ListCopy added in v0.14.9 

func ListCopy[T any](src *list.List) *list.List

ListCopy makes a shallow copy of a list

func ListCopyFn added in v0.14.9 

func ListCopyFn[T any](src *list.List, fn func(v T) (T, bool)) *list.List

ListCopyFn makes a copy of a list using the given helper

func ListForEach 

func ListForEach[T any](l *list.List, fn func(v T) bool)

ListForEach calls a function for each value until told to stop

func ListForEachBackward 

func ListForEachBackward[T any](l *list.List, fn func(v T) bool)

ListForEachBackward calls a function for each value until told to stop

func ListForEachBackwardElement 

func ListForEachBackwardElement(l *list.List, fn func(*list.Element) bool)

ListForEachBackwardElement calls a function for each element until told to stop

func ListForEachElement 

func ListForEachElement(l *list.List, fn func(*list.Element) bool)

ListForEachElement calls a function for each element until told to stop

func MakeHostPort added in v0.14.3 

func MakeHostPort(hostPort string, defaultPort uint16) (string, error)

MakeHostPort produces a validated host:port from an input string optionally using the given default port when the string doesn't specify one. port 0 on the string input isn't considered valid.

func MapAllListContains 

func MapAllListContains[K comparable, T comparable](m map[K]*list.List, v T) bool

MapAllListContains check if a value exists on any entry of the map

func MapAllListContainsFn 

func MapAllListContainsFn[K comparable, T any](m map[K]*list.List, match func(v T) bool) bool

MapAllListContainsFn check if a value exists on any entry of the map using a match function

func MapAllListForEach 

func MapAllListForEach[K comparable, T any](m map[K]*list.List, fn func(v T) bool)

MapAllListForEach calls a function for each value on all map entries until told to stop

func MapAllListForEachElement 

func MapAllListForEachElement[K comparable](m map[K]*list.List, fn func(*list.Element) bool)

MapAllListForEachElement calls a function for each element on all map entries until told to stop

func MapContains 

func MapContains[K comparable](m map[K]any, key K) bool

MapContains tells if a given map contains a key. this helper is intended for switch/case conditions

func MapListAppend 

func MapListAppend[K comparable, T any](m map[K]*list.List, key K, v T)

MapListAppend adds a value at the end of the list of a map entry

func MapListAppendUnique 

func MapListAppendUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)

MapListAppendUnique adds a value at the end of the list of a map entry if it's not already there

func MapListAppendUniqueFn 

func MapListAppendUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T,
	eq func(T, T) bool)

MapListAppendUniqueFn adds a value at the end of the list of a map entry if it's not already there using a function to compare values

func MapListContains 

func MapListContains[K comparable, T comparable](m map[K]*list.List, key K, v T) bool

MapListContains checks if the list.List on a map contains an element

func MapListContainsFn 

func MapListContainsFn[K comparable, T any](m map[K]*list.List, key K, v T,
	eq func(T, T) bool) bool

MapListContainsFn checks if the list.List on a map contains an element using a match functions

func MapListCopy added in v0.14.9 

func MapListCopy[T comparable](src map[T]*list.List) map[T]*list.List

MapListCopy duplicates a map containing a list.List

func MapListCopyFn added in v0.14.9 

func MapListCopyFn[K comparable, V any](src map[K]*list.List,
	fn func(v V) (V, bool)) map[K]*list.List

MapListCopyFn duplicates a map containing a list.List but allows the element's values to be cloned by a helper function

func MapListForEach 

func MapListForEach[K comparable, T any](m map[K]*list.List, key K,
	fn func(v T) bool)

MapListForEach calls a function for each value on a map entry until told to stop

func MapListForEachElement 

func MapListForEachElement[K comparable](m map[K]*list.List, key K,
	fn func(el *list.Element) bool)

MapListForEachElement calls a function for each element on a map entry until told to stop

func MapListInsert 

func MapListInsert[K comparable, T any](m map[K]*list.List, key K, v T)

MapListInsert adds a value at the front of the list of a map entry

func MapListInsertUnique 

func MapListInsertUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)

MapListInsertUnique adds a value at the front of the list of a map entry if it's not already there

func MapListInsertUniqueFn 

func MapListInsertUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T,
	eq func(va, vb T) bool)

MapListInsertUniqueFn adds a value at the front of the list of a map entry if it's not already there using a function to compare values

func MapValue added in v0.14.9 

func MapValue[K comparable, V any](m map[K]V, key K, def V) (V, bool)

MapValue returns a value of an entry or a default if not found

func NewTemporaryError added in v0.13.2 

func NewTemporaryError(err error) error

NewTemporaryError returns an error that returns false to IsTimeout() and true to IsTemporary()

func NewTimeoutError added in v0.13.2 

func NewTimeoutError(err error) error

NewTimeoutError returns an error that returns true to IsTimeout() and IsTemporary()

func Panic 

func Panic(payload any)

Panic emits a PanicError with the given payload

func PanicWrap 

func PanicWrap(err error, note string)

PanicWrap emits a PanicError wrapping an annotated error.

func PanicWrapf 

func PanicWrapf(err error, format string, args ...any)

PanicWrapf emits a PanicError wrapping an annotated error using a formatting string.

func Panicf 

func Panicf(format string, args ...any)

Panicf emits a PanicError with a formatted string as payload

func ParseAddr 

func ParseAddr(s string) (addr netip.Addr, err error)

ParseAddr turns a string into netip.Addr

func ParseNetIP 

func ParseNetIP(s string) (ip net.IP, err error)

ParseNetIP turns a string into a net.IP

func QuietWrap added in v0.13.3 

func QuietWrap(err error, format string, args ...any) error

QuietWrap replaces the text of the error it's wrapping.

func SliceAs added in v0.14.8 

func SliceAs[T, V any](vv []T) []V

SliceAs returns a subset of a slice that could be cast into a different type

func SliceAsFn added in v0.14.8 

func SliceAsFn[T, V any](fn func(T) (V, bool), vv []T) []V

SliceAsFn returns a subset of a slice that could be cast into a different type, using a helper function.

func SliceContains 

func SliceContains[T comparable](a []T, v T) bool

SliceContains tells if a slice contains a given element

func SliceContainsFn 

func SliceContainsFn[T any](a []T, v T, eq func(T, T) bool) bool

SliceContainsFn tells if a slice contains a given element according to the callback eq

func SliceCopy added in v0.14.0 

func SliceCopy[T any](s []T) []T

SliceCopy makes a shallow copy of a given slice

func SliceCopyFn 

func SliceCopyFn[T any](s []T,
	fn func(partial []T, before T) (after T, include bool),
) []T

SliceCopyFn makes a copy of a slice, optionally modifying in-flight the items using a function. If no function is provided, the destination will be a shallow copy of the source slice.

func SliceEqual added in v0.13.5 

func SliceEqual[T comparable](a, b []T) bool

SliceEqual tells if two slices are equal.

func SliceEqualFn added in v0.13.5 

func SliceEqualFn[T any](a, b []T, eq func(va, vb T) bool) bool

SliceEqualFn tells if two slices are equal using a comparing helper.

func SliceMap added in v0.14.1 

func SliceMap[T1 any, T2 any](a []T1,
	fn func(partial []T2, v T1) (newEntries []T2)) []T2

SliceMap takes a []T1 and uses a function to produce a []T2 by processing each item on the source slice.

func SliceMinus 

func SliceMinus[T comparable](a []T, b []T) []T

SliceMinus returns a new slice containing only the elements of one slice not present on the second

func SliceMinusFn 

func SliceMinusFn[T any](a, b []T, eq func(T, T) bool) []T

SliceMinusFn returns a new slice containing only elements of slice A that aren't on slice B according to the callback eq

func SliceRandom added in v0.9.2 

func SliceRandom[T any](a []T) (T, bool)

SliceRandom returns a random element from a slice if the slice is empty it will return the zero value of the slice type and false

func SliceReplaceFn 

func SliceReplaceFn[T any](s []T,
	fn func(partial []T, before T) (after T, replace bool),
) []T

SliceReplaceFn replaces or skips entries in a slice

func SliceReverse added in v0.14.7 

func SliceReverse[T any](x []T)

SliceReverse modifies a slice reversing the order of its elements.

func SliceReversed added in v0.14.7 

func SliceReversed[T any](a []T) []T

SliceReversed returns a copy of the slice, in reverse order.

func SliceReversedFn added in v0.14.7 

func SliceReversedFn[T any](a []T,
	fn func(partial []T, before T) (after T, include bool)) []T

SliceReversedFn returns a modified copy of the slice, in reverse order.

func SliceSort added in v0.13.5 

func SliceSort[T any](x []T, cmp func(a, b T) int)

SliceSort sorts the slice x in ascending order as determined by the cmp function. This sort is not guaranteed to be stable. cmp(a, b) should return a negative number when a < b, a positive number when a > b and zero when a == b.

func SliceSortFn added in v0.14.2 

func SliceSortFn[T any](x []T, less func(a, b T) bool)

SliceSortFn sorts the slice x in ascending order as a less function. This sort is not guaranteed to be stable. less(a, b) should true when a < b

func SliceSortOrdered added in v0.14.2 

func SliceSortOrdered[T Ordered](x []T)

SliceSortOrdered sorts the slice x of an Ordered type in ascending order.

func SliceUnique 

func SliceUnique[T comparable](a []T) []T

SliceUnique returns a new slice containing only unique elements

func SliceUniqueFn 

func SliceUniqueFn[T any](a []T, eq func(T, T) bool) []T

SliceUniqueFn returns a new slice containing only unique elements according to the callback eq

func SliceUniquify 

func SliceUniquify[T comparable](ptr *[]T) []T

SliceUniquify returns the same slice, reduced to only contain unique elements

func SliceUniquifyFn 

func SliceUniquifyFn[T any](ptr *[]T, eq func(T, T) bool) []T

SliceUniquifyFn returns the same slice, reduced to only contain unique elements according to the callback eq

func SortedKeys added in v0.13.5 

func SortedKeys[K Ordered, T any](m map[K]T) []K

SortedKeys returns a sorted list of the keys of a map

func SplitAddrPort added in v0.10.1 

func SplitAddrPort(addrPort string) (addr netip.Addr, port uint16, err error)

SplitAddrPort splits a string containing an IP address and an optional port, and validates it.

func SplitHostPort 

func SplitHostPort(hostPort string) (host, port string, err error)

SplitHostPort is like net.SplitHostPort but doesn't fail if the port isn't part of the string and it validates it if present. SplitHostPort will also validate the host is a valid IP or name

func Unwrap added in v0.13.0 

func Unwrap(err error) []error

Unwrap unwraps one layer of a compound error, ensuring there are no nil entries.

func Wrap 

func Wrap(err error, msg string) error

Wrap annotates an error with a single string.

func Wrapf 

func Wrapf(err error, format string, args ...any) error

Wrapf annotates an error with a formatted string.

func Zero added in v0.9.8 

func Zero[T any](_ *T) T

Zero returns the zero value of a type for which we got a pointer.

Types

type Bool added in v0.14.0 

type Bool interface {
	~bool
}

Bool is any boolean type.

type CallStacker 

type CallStacker interface {
	CallStack() Stack
}

CallStacker represents an object with a method CallStack() returning a Stack

type Catcher 

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

Catcher is a runner that catches panics

func (*Catcher) Do 

func (p *Catcher) Do(fn func() error) error

Do calls a function, returning its organic error, or the caught panic

func (*Catcher) Recovered 

func (p *Catcher) Recovered() Recovered

Recovered returns the error corresponding to a panic when the Catcher was running a function

func (*Catcher) Try 

func (p *Catcher) Try(fn func() error) error

Try calls a function, returning its organic error, or storing the recovered error for later consumption

type Complex added in v0.14.0 

type Complex interface {
	~complex64 | ~complex128
}

Complex is any complex numeric type.

type CompoundError added in v0.9.1 

type CompoundError struct {
	Errs []error
}

A CompoundError can contain more that one error

func (*CompoundError) Append added in v0.14.5 

func (w *CompoundError) Append(err error, note string, args ...any)

Append adds an error to the collection optionally annotated by a formatted string. if err is nil a new error is created unless the note is empty.

func (*CompoundError) AppendError added in v0.9.1 

func (w *CompoundError) AppendError(errs ...error)

AppendError adds an error to the collection, unwrapping other implementers of the Errors interface when possible

func (*CompoundError) AsError added in v0.9.1 

func (w *CompoundError) AsError() error

AsError returns itself as an `error` when there are errors stored, and nil when there aren't

func (*CompoundError) Error added in v0.9.1 

func (w *CompoundError) Error() string

func (*CompoundError) Errors added in v0.9.1 

func (w *CompoundError) Errors() []error

Errors returns the contained slice of errors

func (*CompoundError) Ok added in v0.9.1 

func (w *CompoundError) Ok() bool

Ok tells when there are no errors stored

func (*CompoundError) Unwrap added in v0.13.0 

func (w *CompoundError) Unwrap() []error

Unwrap returns the contained slice of errors

type ContextKey 

type ContextKey[T any] struct {
	// contains filtered or unexported fields
}

ContextKey is a type-safe key for a context.Context value

func NewContextKey 

func NewContextKey[T any](name string) *ContextKey[T]

NewContextKey creates a new ContextKey bound to the specified type and friendly name

func (*ContextKey[T]) Get 

func (ck *ContextKey[T]) Get(ctx context.Context) (T, bool)

Get attempts to extract a value bound to this key in a context.Context For convenience this method will safely operate over a nil receiver.

func (*ContextKey[T]) GoString 

func (ck *ContextKey[T]) GoString() string

GoString renders this key in Go syntax for %v

func (*ContextKey[T]) String 

func (ck *ContextKey[T]) String() string

String returns the name

func (*ContextKey[T]) WithValue 

func (ck *ContextKey[T]) WithValue(ctx context.Context, v T) context.Context

WithValue safely attaches a value to a context.Context under this key.

type ErrGroup added in v0.11.0 

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

ErrGroup handles a group of workers where all are canceled once one fails. As it's based on WaitGroup it also catches panics.

func (*ErrGroup) Cancel added in v0.11.0 

func (eg *ErrGroup) Cancel(cause error) bool

Cancel initiates a shutdown of the group. The returned value indicates if it was the first time.

func (*ErrGroup) Cancelled added in v0.11.0 

func (eg *ErrGroup) Cancelled() <-chan struct{}

Cancelled returns a channel marker to know when the Group has been cancelled and the shutdown has been initiated.

Cancelled() doesn't indicate all workers have finished, for that call ErrGroup.Wait or ErrGroup.Done.

func (*ErrGroup) Context added in v0.11.0 

func (eg *ErrGroup) Context() context.Context

Context returns the cancellable context used with the workers

func (*ErrGroup) Done added in v0.11.1 

func (eg *ErrGroup) Done() <-chan struct{}

Done returns a channel that gets closed when all workers have finished.

func (*ErrGroup) Err added in v0.11.0 

func (eg *ErrGroup) Err() error

Err returns the error that initiated the group's shutdown.

func (*ErrGroup) Go added in v0.11.0 

func (eg *ErrGroup) Go(run func(context.Context) error, shutdown func() error)

Go spawns a worker and an optional shutdown routine to be invoked when the ErrGroup is cancelled, otherwise the provided context needs to be monitored and shutdown called.

func (*ErrGroup) GoCatch added in v0.11.0 

func (eg *ErrGroup) GoCatch(run func(context.Context) error,
	catch func(context.Context, error) error)

GoCatch runs a worker on the Group, with a custom error handler.

func (*ErrGroup) IsCancelled added in v0.11.0 

func (eg *ErrGroup) IsCancelled() bool

IsCancelled tells the ErrGroup has been cancelled

func (*ErrGroup) OnError added in v0.11.0 

func (eg *ErrGroup) OnError(fn func(error))

OnError sets a helper that will be called when a worker returns an error or panics

func (*ErrGroup) SetDefaults added in v0.11.0 

func (eg *ErrGroup) SetDefaults()

SetDefaults fills gaps in the config and initializes the internal structure.

func (*ErrGroup) Wait added in v0.11.0 

func (eg *ErrGroup) Wait() error

Wait waits until all workers in the group have finished.

type Errors added in v0.9.1 

type Errors interface {
	Error() string
	Errors() []error
}

Errors in an error that contains a slice of errors

type Float added in v0.14.0 

type Float interface {
	~float32 | ~float64
}

Float is any floating-point type.

type Frame 

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

Frame represents a function call on the call Stack. This implementation is heavily based on github.com/pkg/errors.Frame but all parts are resolved immediately for later consumption.

func Here 

func Here() *Frame

Here returns the Frame corresponding to where it was called, or nil if it wasn't possible

func StackFrame 

func StackFrame(skip int) *Frame

StackFrame returns the Frame skip levels above from where it was called, or nil if it wasn't possible

func (Frame) File 

func (f Frame) File() string

File returns the file name of the source code corresponding to this Frame

func (Frame) FileLine 

func (f Frame) FileLine() string

FileLine returns File name and Line separated by a colon, or only the filename if the Line isn't known

func (Frame) Format 

func (f Frame) Format(s fmt.State, verb rune)

Format formats the frame according to the fmt.Formatter interface. * * %s source file * %d source line * %n function name * %v equivalent to %s:%d * * Format accepts flags that alter the printing of some verbs, as follows: * * %+s function name and path of source file relative to the compile time * GOPATH separated by \n\t (<funcname>\n\t<path>) * %+n full package name followed by function name * %+v equivalent to %+s:%d

func (Frame) FuncName added in v0.9.10 

func (f Frame) FuncName() string

FuncName returns the name of the function, without the package name

func (Frame) Line 

func (f Frame) Line() int

Line returns the file number on the source code corresponding to this Frame, or zero if unknown.

func (Frame) Name 

func (f Frame) Name() string

Name returns the name of the function, including package name

func (Frame) PkgName added in v0.9.10 

func (f Frame) PkgName() string

PkgName returns the package name

func (Frame) SplitName added in v0.9.10 

func (f Frame) SplitName() (pkgName string, funcName string)

SplitName returns package name and function name

type Integer added in v0.14.0 

type Integer interface {
	Signed | Unsigned
}

Integer is any integer type, signed and unsigned.

type Ordered added in v0.14.0 

type Ordered interface {
	Signed | Unsigned | Float | String
}

Ordered is any type that supports order operators.

type PanicError 

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

PanicError is an error to be sent via panic, ideally to be caught using slog.Recover()

func NewPanicError 

func NewPanicError(skip int, payload any) *PanicError

NewPanicError creates a new PanicError with arbitrary payload

func NewPanicErrorf 

func NewPanicErrorf(skip int, format string, args ...any) *PanicError

NewPanicErrorf creates a new PanicError annotated with a string, optionally formatted. %w is expanded.

func NewPanicWrap 

func NewPanicWrap(skip int, err error, note string) *PanicError

NewPanicWrap creates a new PanicError wrapping a given error annotated with a single string.

func NewPanicWrapf 

func NewPanicWrapf(skip int, err error, format string, args ...any) *PanicError

NewPanicWrapf creates a new PanicError wrapping a given error annotated with a formatted string.

func (*PanicError) CallStack 

func (p *PanicError) CallStack() Stack

CallStack returns the call stack associated to this panic() event

func (*PanicError) Error 

func (p *PanicError) Error() string

Error returns the payload as a string

func (*PanicError) Recovered 

func (p *PanicError) Recovered() any

Recovered returns the payload of the panic

func (*PanicError) Unwrap 

func (p *PanicError) Unwrap() error

Unwrap returns the payload if it's and error

type Recovered 

type Recovered interface {
	Error() string
	Recovered() any
}

Recovered is an error caught from a panic call

func AsRecovered 

func AsRecovered(rvr any) Recovered

AsRecovered receives the value from recover() and wraps it as a Recovered error

type Signed added in v0.14.0 

type Signed interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}

Signed is any signed integer type.

type SpinLock added in v0.15.3 

type SpinLock uint32

SpinLock is a simple CompareAndSwap locking mechanism.

func (*SpinLock) Lock added in v0.15.3 

func (sl *SpinLock) Lock()

Lock blocks until it can acquire the lock

func (*SpinLock) TryLock added in v0.15.3 

func (sl *SpinLock) TryLock() bool

TryLock attempts to acquire the lock

func (*SpinLock) Unlock added in v0.15.3 

func (sl *SpinLock) Unlock()

Unlock releases the lock

type Stack 

type Stack []Frame

Stack is an snapshot of the call stack in the form of an array of Frames.

func StackTrace 

func StackTrace(skip int) Stack

StackTrace returns a snapshot of the call stack starting skip levels above from where it was called, on an empty array if it wasn't possible

func (Stack) Format 

func (st Stack) Format(s fmt.State, verb rune)

Format formats the stack of Frames following the rules explained in Frame.Format with the addition of the '#' flag.

when '#' is passed, like for example %#+v each row will be prefixed by i/n indicating the position in the stack followed by the %+v representation of the Frame

type String added in v0.14.0 

type String interface {
	~string
}

String is any string type.

type TemporaryError added in v0.13.2 

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

TemporaryError is an error wrapper that satisfies IsTimeout() and IsTemporary()

func (*TemporaryError) Error added in v0.13.2 

func (w *TemporaryError) Error() string

func (*TemporaryError) IsTemporary added in v0.13.2 

func (*TemporaryError) IsTemporary() bool

IsTemporary tells this error is temporary.

func (*TemporaryError) IsTimeout added in v0.13.2 

func (w *TemporaryError) IsTimeout() bool

IsTimeout tells if this error is a time-out or not.

func (*TemporaryError) Temporary added in v0.13.2 

func (*TemporaryError) Temporary() bool

Temporary tells this error is temporary.

func (*TemporaryError) Timeout added in v0.13.2 

func (w *TemporaryError) Timeout() bool

Timeout tells if this error is a time-out or not.

type Unsigned added in v0.14.0 

type Unsigned interface {
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

Unsigned is any unsigned integer type.

type Unwrappable 

type Unwrappable interface {
	Error() string
	Unwrap() error
}

Unwrappable represents an error that can be Unwrap() to get the cause

type WaitGroup 

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

WaitGroup is a safer way to run workers

func (*WaitGroup) Done added in v0.11.1 

func (wg *WaitGroup) Done() <-chan struct{}

Done returns a channel that gets closed when all workers have finished.

func (*WaitGroup) Err 

func (wg *WaitGroup) Err() error

Err returns the first error

func (*WaitGroup) Go 

func (wg *WaitGroup) Go(fn func() error)

Go spawns a supervised goroutine

func (*WaitGroup) GoCatch 

func (wg *WaitGroup) GoCatch(fn func() error, catch func(error) error)

GoCatch spawns a supervised goroutine, and uses a given function to intercept the returned error

func (*WaitGroup) OnError 

func (wg *WaitGroup) OnError(fn func(error) error)

OnError sets a helper that will be called when a worker returns an error or panics

func (*WaitGroup) Wait 

func (wg *WaitGroup) Wait() error

Wait waits until all workers have finished, and returns the first error

type WrappedError 

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

WrappedError is an annotated error that can be Unwrapped

func (*WrappedError) Error 

func (w *WrappedError) Error() string

func (*WrappedError) Unwrap 

func (w *WrappedError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.