async

Documentation

Overview

Package async provides asynchronous orchestration primitives for Go: promises, futures, and deferred actions.

Index

• type Future
  • func NewFuture[T any](result <-chan T) *Future[T]
  • func (f *Future[T]) Get() T
• type FutureAction
  • func NewFutureAction[T any](action func() T) *FutureAction[T]
  • func (f *FutureAction[T]) Get() T
• type FutureError
• type Promise
  • func NewPromise[T any]() Promise[T]
  • func (p *Promise[T]) GetFuture() *Future[T]
  • func (p *Promise[T]) Set(value T)
• type PromiseError

Types

type Future

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

Future represents a read-only view of a promised value. It provides a way to retrieve the value asynchronously, blocking if necessary.

func NewFuture

func NewFuture[T any](result <-chan T) *Future[T]

NewFuture creates a new Future from a given receive-only channel. This allows wrapping an existing channel as a Future.

func (*Future[T]) Get

func (f *Future[T]) Get() T

Get retrieves the value from the Future, blocking until it's available. If the channel is closed without a value (though not typical in this pattern), it returns the zero value.

type FutureAction

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

FutureAction is an abstraction over a channel that models a task and its result. It allows executing a computation asynchronously in a goroutine and retrieving the result later via a blocking call. This is similar to the Future pattern in other languages, providing a simple way to handle asynchronous results without manual channel management.

The channel is closed after the result is sent, ensuring proper resource cleanup.

Example usage:

func main() {
	callback := func() any {
		time.Sleep(time.Second)
		return "success"
	}

	future := NewFutureAction(callback)
	result := future.Get()
	fmt.Println(result) // Output: success
}

func NewFutureAction

func NewFutureAction[T any](action func() T) *FutureAction[T]

NewFutureAction creates and returns a new FutureAction. It starts the provided action function in a separate goroutine. The action's return value is sent to the internal channel. The channel is closed after sending the result to allow safe ranging or detection of completion.

func (*FutureAction[T]) Get

func (f *FutureAction[T]) Get() T

Get returns the result of the asynchronous task. This method blocks until the result is available from the channel. If the action function blocks indefinitely (e.g., due to an infinite loop or deadlock), Get will never return, potentially causing the caller to hang. It is the caller's responsibility to ensure the action completes.

type FutureError

type FutureError = Future[error]

PromiseError and FutureError are type aliases for Promise and Future specialized for error handling. This allows for easy propagation of errors in asynchronous operations.

type Promise

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

Promise represents a writable, single-assignment container for a future value. It allows setting a value exactly once. Attempting to set the value more than once is ignored. The internal channel is buffered to hold one value and is closed after setting. Synchronization is handled via atomic operations and a mutex for thread safety.

Example usage:

func main() {
	promise := NewPromise[string]()
	go func() {
		time.Sleep(time.Second)
		promise.Set("Cake")
	}()

    future := promise.GetFuture()
    value := future.Get()
    fmt.Println(value) // Output: Cake
}

func NewPromise

func NewPromise[T any]() Promise[T]

NewPromise creates and returns a new Promise. The internal channel is buffered with capacity 1 to hold the future value.

func (*Promise[T]) GetFuture

func (p *Promise[T]) GetFuture() *Future[T]

GetFuture returns a Future associated with this Promise. The Future can be used to retrieve the value once it's set.

func (*Promise[T]) Set

func (p *Promise[T]) Set(value T)

Set assigns the value to the Promise. This can be called only once; subsequent calls are ignored. After setting, the value is sent to the channel, and the channel is closed.

type PromiseError

type PromiseError = Promise[error]

PromiseError and FutureError are type aliases for Promise and Future specialized for error handling. This allows for easy propagation of errors in asynchronous operations.