README
¶
Fillmore Labs Async
The async package provides interfaces and utilities for writing asynchronous code in Go.
Motivation
...
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
package main
import (
"context"
"log/slog"
"time"
"fillmore-labs.com/async"
)
func main() {
const timeout = 2 * time.Second
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
future := async.NewAsync(func() (string, error) { return getMyIP(ctx) })
// other queries
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:
package main
import (
"context"
"encoding/json"
"net/http"
)
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 ErrNotReady = errors.New("future not ready")
ErrNotReady is returned when a future is not complete.
Functions ¶
This section is empty.
Types ¶
type Future ¶
Future represents a read-only view of the result of an asynchronous operation.
Construct a future either using NewAsync or from a Promise with Promise.Future.
func DoAsync ¶
DoAsync schedules an asynchronous operation on the Group and returns a Future to retrieve the eventual result.
func NewAsync ¶
NewAsync runs fn asynchronously, immediately returning a Future that can be used to retrieve the eventual result. This allows separating computation from evaluating the result.
func (*Future[R]) Await ¶
Await returns the cached result or blocks until a result is available or the context is canceled.
func (*Future[_]) Done ¶
func (f *Future[_]) Done() <-chan struct{}
Done returns a channel that is closed when the future is complete. It enables the use of future values in select statements.
func (*Future[R]) Try ¶
Try returns the cached result when ready, ErrNotReady otherwise.
type Group ¶
type Group interface {
Go(fn func() error)
}
A Group is a collection of asynchronous operations working on the same task.
type Promise ¶
type Promise[R any] struct { // contains filtered or unexported fields }
Promise defines the common operations for resolving a Future to its final value.
An empty value is valid and must not be copied after creation. One of the resolving operations may be called once from any goroutine, all subsequent calls will panic.
Source Files
Directories