promise

README

PROMISE

Introduction

promise allows you to write async code in sync fashion

• First class context.Context support
• Automatic panic recovery
• Generics support
• Goroutine pool support
  • sourcegraph/conc
  • panjf2000/ants
  • alitto/pond
  • [Your own!]

Install

$ go get github.com/arielsrv/promise

Quickstart

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/arielsrv/promise"
)

func main() {
	p1 := promise.New(func(resolve func(int), reject func(error)) {
		factorial := findFactorial(20)
		resolve(factorial)
	})
	p2 := promise.New(func(resolve func(string), reject func(error)) {
		ip, err := fetchIP()
		if err != nil {
			reject(err)
		} else {
			resolve(ip)
		}
	})

	factorial, _ := p1.Await(context.Background())
	fmt.Println(*factorial)

	IP, _ := p2.Await(context.Background())
	fmt.Println(*IP)
}

func findFactorial(n int) int {
	if n == 1 {
		return 1
	}
	return n * findFactorial(n-1)
}

func fetchIP() (string, error) {
	resp, err := http.Get("https://httpbin.org/ip")
	if err != nil {
		return "", err
	}

	defer resp.Body.Close()

	type Response struct {
		Origin string `json:"origin"`
	}
	var response Response

	err = json.NewDecoder(resp.Body).Decode(&response)
	return response.Origin, err
}

Pool

• Promise execution can be dispatched to distinct pools, providing granular control over task distribution and concurrency.

• Better performance can be achieved by allowing different stages of a Promise chain to be executed on different goroutine pools, optimizing for the specific requirements of each task.

package main

import (
	"context"

	"github.com/arielsrv/promise"
)

func main() {
	ctx := context.Background()

	// fetches data from API, runs on ioOptimizedPool
	dataPromise := promise.NewWithPool(func(resolve func(string), reject func(error)) {
		data, err := fetchDataFromAPI()
		if err != nil {
			reject(err)
		} else {
			resolve(data)
		}
	}, ioOptimizedPool)

	// computes result based on the fetched data, runs on cpuOptimizedPool
	resultPromise := promise.ThenWithPool(dataPromise, ctx, func(data string) (string, error) {
		result, err := computeResult(data)
		return result, err
	}, cpuOptimizedPool)
}

Documentation

Index

• type Pool
  • func FromAlittoPool(p *pond.WorkerPool) Pool
  • func FromAntsPool(p *ants.Pool) Pool
  • func FromConcPool(p *conc.Pool) Pool
• type Promise
  • func All[T any](ctx context.Context, promises ...*Promise[T]) *Promise[[]T]
  • func AllWithPool[T any](ctx context.Context, pool Pool, promises ...*Promise[T]) *Promise[[]T]
  • func Catch[T any](ctx context.Context, p *Promise[T], reject func(err error) error) *Promise[T]
  • func CatchWithPool[T any](ctx context.Context, p *Promise[T], reject func(err error) error, pool Pool) *Promise[T]
  • func New[T any](executor func(resolve func(T), reject func(error))) *Promise[T]
  • func NewWithPool[T any](executor func(resolve func(T), reject func(error)), pool Pool) *Promise[T]
  • func Race[T any](ctx context.Context, promises ...*Promise[T]) *Promise[T]
  • func RaceWithPool[T any](ctx context.Context, pool Pool, promises ...*Promise[T]) *Promise[T]
  • func Then[A, B any](ctx context.Context, p *Promise[A], resolve func(A) (B, error)) *Promise[B]
  • func ThenWithPool[A, B any](ctx context.Context, p *Promise[A], resolve func(A) (B, error), pool Pool) *Promise[B]
  • func (p *Promise[T]) Await(ctx context.Context) (*T, error)

Types

type Pool

type Pool interface {
	Go(f func())
}

func FromAlittoPool

func FromAlittoPool(p *pond.WorkerPool) Pool

func FromAntsPool

func FromAntsPool(p *ants.Pool) Pool

func FromConcPool

func FromConcPool(p *conc.Pool) Pool

type Promise

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

Promise represents the eventual completion (or failure) of an asynchronous operation and its resulting value.

func All

func All[T any](
	ctx context.Context,
	promises ...*Promise[T],
) *Promise[[]T]

All resolves when all promises have resolved, or rejects immediately upon any of the promises rejecting.

func AllWithPool

func AllWithPool[T any](
	ctx context.Context,
	pool Pool,
	promises ...*Promise[T],
) *Promise[[]T]

func Catch

func Catch[T any](
	ctx context.Context,
	p *Promise[T],
	reject func(err error) error,
) *Promise[T]

func CatchWithPool

func CatchWithPool[T any](
	ctx context.Context,
	p *Promise[T],
	reject func(err error) error,
	pool Pool,
) *Promise[T]

func New

func New[T any](
	executor func(resolve func(T), reject func(error)),
) *Promise[T]

func NewWithPool

func NewWithPool[T any](
	executor func(resolve func(T), reject func(error)),
	pool Pool,
) *Promise[T]

func Race

func Race[T any](
	ctx context.Context,
	promises ...*Promise[T],
) *Promise[T]

Race resolves or rejects as soon as any one of the promises resolves or rejects.

func RaceWithPool

func RaceWithPool[T any](
	ctx context.Context,
	pool Pool,
	promises ...*Promise[T],
) *Promise[T]

func Then

func Then[A, B any](
	ctx context.Context,
	p *Promise[A],
	resolve func(A) (B, error),
) *Promise[B]

func ThenWithPool

func ThenWithPool[A, B any](
	ctx context.Context,
	p *Promise[A],
	resolve func(A) (B, error),
	pool Pool,
) *Promise[B]

func (*Promise[T]) Await

func (p *Promise[T]) Await(ctx context.Context) (*T, error)