README
¶
Fillmore Labs Promise
The promise package provides interfaces and utilities for writing asynchronous code in Go.
Motivation
Promises and futures are constructs used for asynchronous and concurrent programming, allowing developers to work with values that may not be immediately available and can be evaluated in a different execution context.
Go is known for its built-in concurrency features like goroutines and channels. The select statement further allows for efficient multiplexing and synchronization of multiple channels, thereby enabling developers to coordinate and orchestrate asynchronous operations effectively. Additionally, the context package offers a standardized way to manage cancellation, deadlines, and timeouts within concurrent and asynchronous code.
On the other hand, Go's error handling mechanism, based on explicit error values returned from functions, provides a clear and concise way to handle errors.
The purpose of this package is to provide a library which simplifies the integration of concurrent code while providing a cohesive strategy for handling asynchronous errors. By adhering to Go's standard conventions for asynchronous and concurrent code, as well as error propagation, this package aims to enhance developer productivity and code reliability in scenarios requiring asynchronous operations.
Usage
Assuming you have a synchronous function func getMyIP(ctx context.Context) (string, error) returning your external IP
address (see GetMyIP for an example).
Now you can do
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
query := func() (string, error) {
return getMyIP(ctx)
}
future := promise.NewAsync(query)
and elsewhere in your program, even in a different goroutine
if ip, err := future.Await(ctx); err == nil {
slog.Info("Found IP", "ip", ip)
} else {
slog.Error("Failed to fetch IP", "error", err)
}
decoupling query construction from result processing.
GetMyIP
Sample code to retrieve your IP address:
const serverURL = "https://httpbin.org/ip"
func getMyIP(ctx context.Context) (string, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, serverURL, nil)
if err != nil {
return "", err
}
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer func() { _ = resp.Body.Close() }()
ipResponse := struct {
Origin string `json:"origin"`
}{}
err = json.NewDecoder(resp.Body).Decode(&ipResponse)
return ipResponse.Origin, err
}
Links
- Futures and Promises in the English Wikipedia
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoResult = errors.New("no result")
ErrNoResult is returned when a future completes but has no defined result value.
var ErrNotReady = errors.New("future not ready")
ErrNotReady is returned when a future is not complete.
Functions ¶
Types ¶
type Future ¶
Future represents an asynchronous operation that will complete sometime in the future.
It is a read-only channel that can be used with Future.Await to retrieve the final result of a Promise.
func NewAsync ¶
NewAsync runs fn asynchronously, immediately returning a Future that can be used to retrieve the eventual result. This allows separating evaluating the result from computation.
func (Future[R]) Await ¶
Await returns the final result of the associated Promise. It can only be called once and blocks until a result is received or the context is canceled. If you need to read multiple times from a Future wrap it with Future.Memoize.
func (Future[R]) Memoize ¶
Memoize returns a memoizer for the given future, consuming it in the process.
The Memoizer can be queried multiple times from multiple goroutines.
func (Future[R]) Try ¶
Try returns the result when ready, ErrNotReady otherwise.
type List ¶
List is a list of Future, representing results of asynchronous tasks.
func (List[R]) All ¶
All returns a function that yields the results of all futures. If the context is canceled, it returns an error for the remaining futures.
func (List[R]) AwaitAll ¶
AwaitAll waits for all futures to complete and returns the results. If the context is canceled, it returns early with errors for the remaining futures.
func (List[R]) AwaitAllValues ¶
AwaitAllValues returns the values of completed futures. If any future fails or the context is canceled, it returns early with an error.
type Memoizer ¶
type Memoizer[R any] struct { // contains filtered or unexported fields }
A Memoizer is created with Future.Memoize and contains a memoized result of a future.
func (*Memoizer[R]) Try ¶
Try returns the result of the future if it is ready, otherwise it returns ErrNoResult.
type Promise ¶
Promise is used to send the result of an asynchronous operation.
It is a write-only promise. Either Promise.Resolve or Promise.Reject should be called exactly once.
Source Files
Directories