async

README

async

Tiny futures library for Go. Supports eager and lazy evaluation, both synchronous and asynchronous.

Examples

• https://pkg.go.dev/github.com/CAFxX/async#example-Future

Documentation

Index

• type Future
  • func NewFuture[T any](fn func() (T, error)) *Future[T]
  • func (w *Future[T]) Done() <-chan struct{}
  • func (w *Future[T]) Eager()
  • func (w *Future[T]) NonBlocking() *Future[T]
  • func (w *Future[T]) Resolve() error
  • func (w *Future[T]) Result(ctx context.Context) (T, error)

Examples

• Future

Types

type Future

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

Future is a future for the specified type T.

It supports both lazy and eager evaluation, both synchronous and asynchronous. It is especially useful when the results of one or more asynchronous operations may need to be consumed by multiple dependant asynchronous operations that themselves may or may not be executed.

Example

ctx := context.Background()
foo := true
bar := true

f1 := NewFuture(func() (int, error) {
	return 42, nil
}).NonBlocking()

f2 := NewFuture(func() (string, error) {
	res, err := f1.Result(ctx)
	if err != nil {
		return "", err
	}
	return fmt.Sprintf("n=%d", res), nil
})

f3 := NewFuture(func() (string, error) {
	return "hello", nil
}).NonBlocking()

f4 := NewFuture(func() ([]string, error) {
	if foo && bar {
		f2.Eager()
	}

	var s []string
	if foo {
		r, err := f3.Result(ctx)
		if err != nil {
			return nil, err
		}
		s = append(s, r)
	}
	if bar {
		r, err := f2.Result(ctx)
		if err != nil {
			return nil, err
		}
		s = append(s, r)
	}
	return s, nil
})

f4.Result(ctx)

func NewFuture

func NewFuture[T any](fn func() (T, error)) *Future[T]

NewFuture wraps the provided function into a Future handle that can be used to asynchronously execute the function and obtain its results.

The wrapped function is not invoked immediately by NewFuture. It is invoked at most once when Result, Eager or Done are invoked (regardless of the number of invocations to these functions).

If the provided function panics, the panic is caught and forwarded to all callers of Result.

func (*Future[T]) Done

func (w *Future[T]) Done() <-chan struct{}

Done returns a channel that is closed once the wrapped function has completed execution. Once this happens, calls to Result are guaranteed to not block. If the wrapped function has not been invoked yet by a previous call to Eager or Result, it is started.

If your code calls Done, it MUST eventually call Result as well: failure to do so will cause any panic deriving from the execution of the wrapped function to be delivered to the Go runtime, terminating the process.

func (*Future[T]) Eager

func (w *Future[T]) Eager()

Eager signals to the Future runtime that execution of the wrapped function should be started now (if it has not been started yet).

If your code calls Eager, it MUST eventually call Result as well: failure to do so will cause any panic deriving from the execution of the wrapped function to be delivered to the Go runtime, terminating the process.

func (*Future[T]) NonBlocking

func (w *Future[T]) NonBlocking() *Future[T]

NonBlocking can be used to signal that the function wrapped by the Future is expected to execute quickly (no more than a few µs) and to not block (e.g. waiting for I/O). This allows the Future runtime to avoid executing the function in a separate goroutine, and reduces the amount of synchorinzation needed - potentially yielding higher performance.

NonBlocking, if used, should be called before any call to Eager, Done, Result, or Resolve.

After a call to NonBlocking, calls to Eager and Done will also block until the wrapped function has completed execution.

If used inappropriately (e.g. for wrapped functions that block, or take longer than a few µs) this will slow down your code by inhibiting concurrent execution: in case of doubt avoid using it.

func (*Future[T]) Resolve

func (w *Future[T]) Resolve() error

Resolve synchronously invokes the wrapped function if it has not been invoked yet. It returns the error returned by the invocation.

This method is mostly useful as an argument to (*errgroup.Group).Go().

func (*Future[T]) Result

func (w *Future[T]) Result(ctx context.Context) (T, error)

Result returns the results returned by the wrapped function, once execution of the function has completed.

Multiple Result calls will always return the same result, and the wrapped function will be invoked at most once.

If the context is cancelled before the results become available, Result returns immediately (without waiting for the function to complete) with the error from the context.

If the wrapped function panicked, Result will propagate that panic to each function that calls Result.