fun

package module
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2023 License: Apache-2.0 Imports: 6 Imported by: 21

README

fun -- Go Generic Functions and Tools

Go Reference

fun is a simple, well tested, zero-dependency, collection of packages with generic function, tools, patterns, and the kind of thing you could write one-offs for but shouldn't.

Packages:

  • erc (error collecting)
  • itertool (iterator tools)
  • pubsub (message broker and queues)
  • set (generic ordered and unordered sets)
  • seq (generic linked lists.)
  • srv (service orchestration and management framework.)

For more information, see the documentation, but of general interest:

  • In itertools and with fun.Iterator, an iterator framework and tools for interacting with iterators and generators.
  • In pubsub, a channel-based message broker (for one-to-many channel patterns), with several backend patterns for dealing with load-shedding and message distribution patterns.
  • In erc, an error collector implementation for threadsafe error aggregation and introspection, particularly in worker-pool, applications.
  • In set, a Set type, with ordered and unordered implementations.
  • Queue and Deque implementations (in pubsub) that provide thread-safe linked-list based implementations and Wait methods to block until new items added.
  • In seq, general purpose linked list implementations, with a healthy feature set and flexible interface.
  • In srv, a service orchestration toolkit.

Contributions welcome, the general goals of the project:

  • superior API ergonomics.
  • great high-level abstractions.
  • obvious and clear implementations.
  • minimal dependencies.

Have fun!

Documentation

Overview

Package fun is a zero-dependency collection of tools and idoms that takes advantage of generics. Iterators, error handling, a native-feeling Set type, and a simple pub-sub framework for distributing messages in fan-out patterns.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvariantViolation = errors.New("invariant violation")

ErrInvariantViolation is the root error of the error object that is the content of all panics produced by the Invariant helper.

Functions

func Check added in v0.3.0 

func Check(fn func()) (err error)

Check, like safe and SafeCtx runs a function without arguments that does not produce an error, and, if the function panics, converts it into an error.

func Invariant added in v0.3.0 

func Invariant(cond bool, args ...any)

Invariant panics if the condition is false Invariant panics, passing an error that is rooted by ErrInvariantViolation.

func InvariantCheck added in v0.6.0 

func InvariantCheck(fn func() error, args ...any)

InvariantCheck calls the function and if it returns an error panics with an ErrInvariantViolation error, wrapped with the error of the function, and any annotation arguments.

func InvariantMust added in v0.6.0 

func InvariantMust(err error, args ...any)

InvariantMust raises an invariant error if the error is not nil. The content of the panic is both--via wrapping--an ErrInvariantViolation and the error itself.

func Is 

func Is[T any](in any) bool

Is a generic version of `errors.Is` that takes advantage of the Unwrap function, and is useful for checking if an object of an interface type is or wraps an implementation of the type parameter.

func IsInvariantViolation added in v0.3.0 

func IsInvariantViolation(r any) bool

IsInvariantViolation returns true if the argument is or resolves to ErrInvariantViolation.

func Must 

func Must[T any](arg T, err error) T

Must wraps a function that returns a value and an error, and converts the error to a panic.

func Observe added in v0.7.0 

func Observe[T any](ctx context.Context, iter Iterator[T], observe func(T))

Observe processes an iterator calling the observer function for every element in the iterator and retruning when the iterator is exhausted. Take care to ensure that the Observe function does not block.

Use itertool.Observe and itertool.ParallelObserve for more advanced execution patterns.

func Process added in v0.7.1 

func Process[T any](fn func(T), items ...T)

Process calls a function for every item passed to it. Process is a noop if no items are passed.

One potential use case is with erc.Collectors, as in: 

ec := &erc.Collector
fun.Process(ec.Add, err, err1, err2, err3, file.Close())

func ProcessAll added in v0.7.1 

func ProcessAll[T any](fn func(T), items []T)

ProcessAll is a non-varadic version of Process().

func ReadOne added in v0.7.0 

func ReadOne[T any](ctx context.Context, ch <-chan T) (T, error)

ReadOnce reads one item from the channel, and returns it. ReadOne returns early if the context is canceled (ctx.Err()) or the channel is closed (io.EOF).

func Safe 

func Safe[T any](fn func() T) (out T, err error)

Safe runs a function with a panic handler that converts the panic to an error.

func SafeCtx 

func SafeCtx[T any](ctx context.Context, fn func(context.Context) T) (out T, err error)

SafeCtx provides a variant of the Safe function that takes a context.

func Unwrap 

func Unwrap[T any](in T) T

Unwrap is a generic equivalent of the `errors.Unwrap()` function for any type that implements an `Unwrap() T` method. useful in combination with Is.

func Wait 

func Wait(ctx context.Context, wg *sync.WaitGroup)

Wait returns when the all waiting items are done, *or* the context is canceled. This operation will leak a go routine if the WaitGroup never returns and the context is canceled.

fun.Wait(wg) is equivalent to fun.WaitGroup(wg)(ctx)

func WaitAdd added in v0.6.3 

func WaitAdd(ctx context.Context, wg *sync.WaitGroup, fn WaitFunc)

WaitAdd starts a goroutine that waits for the WaitFunc to return, incrementing and decrementing the sync.WaitGroup as appropriate. This WaitFunc blocks on WaitAdd's context.

Types

type Iterator 

type Iterator[T any] interface {
	Next(context.Context) bool
	Close() error
	Value() T
}

Iterator provides a safe, context-respecting iterator paradigm for iterable objects, along with a set of consumer functions and basic implementations.

The itertool package provides a number of tools and paradigms for creating and processing Iterator objects, including Generators, Map and Reduce, Filter as well as Split and Merge to combine or divide iterators.

In general, Iterators cannot be safe for access from multiple concurrent goroutines, because it is impossible to synchronize calls to Next() and Value(); however, itertool.Range() and itertool.Split() provide support for these workloads.

type WaitFunc added in v0.6.3 

type WaitFunc func(context.Context)

WaitFunc is a type of function object that will block until an operation returns or the context is canceled.

func WaitBlocking added in v0.6.5 

func WaitBlocking(fn func()) WaitFunc

WaitBlocking is a convenience function to use simple blocking functions into WaitFunc objects. Because these WaitFunc functions do not resepct the WaitFunc context, use with care and caution.

func WaitBlockingObserve added in v0.6.5 

func WaitBlockingObserve[T any](observe func(T), wait func() T) WaitFunc

WaitBlockingObserve is a convenience function that creates a WaitFunc that wraps a simple function that returns a single value, and observes that output with the observer function.

Because these WaitFunc functions do not resepct the WaitFunc context, use with care and caution.

func WaitChannel added in v0.6.3 

func WaitChannel[T any](ch <-chan T) WaitFunc

WaitChannel converts a channel (typically, a `chan struct{}`) to a WaitFunc. The WaitFunc blocks till it's context is canceled or the channel is either closed or returns one item.

func WaitContext added in v0.6.3 

func WaitContext(ctx context.Context) WaitFunc

WaitContext wait's for the context to be canceled before returning. The WaitFunc that's return also respects it's own context. Use this WaitFunc and it's own context to wait for a context to be cacneled with a timeout, for instance.

func WaitGroup added in v0.6.3 

func WaitGroup(wg *sync.WaitGroup) WaitFunc

WaitGroup converts a WaitGroup into a fun.WaitFunc.

This operation will leak a go routine if the WaitGroup never returns and the context is canceled.

func WaitMerge added in v0.6.3 

func WaitMerge(ctx context.Context, iter Iterator[WaitFunc]) WaitFunc

WaitMerge starts a goroutine that blocks on each WaitFunc provided and returns a WaitFunc that waits for all of these goroutines to return. The constituent WaitFunc are passed WaitMerge's context, while the returned WaitFunc respects its own context.

Use itertool.Variadic, itertool.Slice, or itertool.Channel to convert common container types/calling patterns to an iterator.

In combination with erc.CheckWait, you can use WaitMerge to create and pubsub.Queue or pubsub.Deque blocking iterators to create worker pools.

func WaitObserve added in v0.6.3 

func WaitObserve[T any](observe func(T), ch <-chan T) WaitFunc

WaitObserve passes the output of the channel into the observer function and then returns. If the context is canceled the output of the channel is not observed.

WaitObserve consumes and observes, at most, one item from the channel. Callers must call the WaitFunc.

func WaitObserveAll added in v0.6.3 

func WaitObserveAll[T any](observe func(T), ch <-chan T) WaitFunc

WaitObserveAll passes the output of the channel into the observer function, waiting for the input channel to be closed or the WaitFunc's context to be canceled. WaitObserveAll does not begin processing the channel until the WaitFunc is called.

func (WaitFunc) Block added in v0.6.3 

func (wf WaitFunc) Block()

Block executes the wait function with a context that will never expire. Use with extreme caution.

func (WaitFunc) WithTimeout added in v0.6.6 

func (wf WaitFunc) WithTimeout(timeout time.Duration)

WithTimeout runs the wait function with an explicit timeout.

Source Files

View all Source files

Directories

Path Synopsis
Package assert provides an incredibly simple assertion framework, that relies on generics and simplicity.
 Package assert provides an incredibly simple assertion framework, that relies on generics and simplicity.
check
GENERATED FILE FROM ASSERTION PACKAGE
 GENERATED FILE FROM ASSERTION PACKAGE
Package erc provides a simple/fast error aggregation tool for collecting and aggregating errors.
 Package erc provides a simple/fast error aggregation tool for collecting and aggregating errors.
Package itertool provides a set of functional helpers for managinging and using fun.Iterator implementations, including a parallel Map/Reduce, Merge, and other convenient tools.
 Package itertool provides a set of functional helpers for managinging and using fun.Iterator implementations, including a parallel Map/Reduce, Merge, and other convenient tools.
Package pubsub provides a message broker for one-to-many or many-to-many message distribution.
 Package pubsub provides a message broker for one-to-many or many-to-many message distribution.
Package seq provides single and double linked-list implementations and tools (e.g.
 Package seq provides single and double linked-list implementations and tools (e.g.
Package Set provides ordered and unordered set implementations for arbitrary comparable types.
 Package Set provides ordered and unordered set implementations for arbitrary comparable types.
Package srv provides a framework and toolkit for service orchestration.
 Package srv provides a framework and toolkit for service orchestration.
Package testt (for test tools), provides a couple of useful helpers for common test patterns.
 Package testt (for test tools), provides a couple of useful helpers for common test patterns.

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.