syncf

Documentation

Overview

Package syncf contains common utilities for synchronization.

Index

• Variables
• func AwaitSignal(ctx context.Context, signals ...os.Signal)
• func Failure[V any](ctx context.Context, p Promise[V], err error) error
• func Go(ctx context.Context, fun func(ctx context.Context)) (context.CancelFunc, error)
• func GoSync(ctx context.Context, fun func(ctx context.Context)) context.CancelFunc
• func GoWith(ctx context.Context, contextFunc ContextFunc, fun func(ctx context.Context)) (context.CancelFunc, error)
• func GoroutineID(ctx context.Context) (string, bool)
• func IsContextRelated(err error) bool
• func Success[V any](ctx context.Context, p Promise[V], value V) error
• type Clock
• type ClockFunc
  • func (fun ClockFunc) Now() time.Time
• type ContextFunc
  • func Deadline(deadline time.Time) ContextFunc
  • func Timeout(timeout time.Duration) ContextFunc
  • func (f ContextFunc) Stack(another ContextFunc) ContextFunc
• type Locker
  • func Semaphore(clock Clock, size int, interval time.Duration) Locker
• type Promise
• type RWLocker
• type RWMutex
  • func (m *RWMutex) Lock(ctx context.Context) (context.Context, context.CancelFunc)
  • func (m *RWMutex) RLock(ctx context.Context) (context.Context, context.CancelFunc)
• type Ref
  • func Async[V any](ctx context.Context, body Resolve[V]) Ref[V]
  • func AsyncWith[V any](ctx context.Context, contextFunc ContextFunc, body Resolve[V]) Ref[V]
  • func Lazy[V any](body Resolve[V]) Ref[V]
• type Resolve
  • func (f Resolve[V]) Get(ctx context.Context) (V, error)
• type Val
  • func (v Val[V]) Get(ctx context.Context) (V, error)
• type Var
  • func (v *Var[V]) Complete(ctx context.Context, value V, err error) error
  • func (v *Var[V]) Get(ctx context.Context) (value V, err error)
• type WaitGroup
  • func (wg *WaitGroup) Spawn(ctx context.Context) (context.Context, context.CancelFunc)

Variables

var DefaultSignals = []os.Signal{syscall.SIGINT, syscall.SIGABRT, syscall.SIGKILL, syscall.SIGTERM}

Functions

func AwaitSignal

func AwaitSignal(ctx context.Context, signals ...os.Signal)

AwaitSignal blocks until a signal is received. By default, listens to DefaultSignals.

func Failure

func Failure[V any](ctx context.Context, p Promise[V], err error) error

Failure is used to fail Promise.

func Go

func Go(ctx context.Context, fun func(ctx context.Context)) (context.CancelFunc, error)

Go starts a goroutine.

func GoSync

func GoSync(ctx context.Context, fun func(ctx context.Context)) context.CancelFunc

GoSync acts like Go, but CancelFunc call will wait for goroutine to complete.

func GoWith

func GoWith(ctx context.Context, contextFunc ContextFunc, fun func(ctx context.Context)) (context.CancelFunc, error)

GoWith starts a goroutine. It uses ContextFunc to spawn a new context.Context and then adds a goroutine ID values to that context. CancelFunc should be used for goroutine interruption via context. Error may be returned in case context spawning failed.

func GoroutineID

func GoroutineID(ctx context.Context) (string, bool)

GoroutineID extracts goroutine ID (which is set by GoWith) from context.Context.

func IsContextRelated

func IsContextRelated(err error) bool

IsContextRelated checks if this is a "context" package error.

func Success

func Success[V any](ctx context.Context, p Promise[V], value V) error

Success is used to set a Promise.

Types

type Clock

type Clock interface {

	// Now returns the current time according to this Clock.
	Now() time.Time
}

Clock is an interface for clocks returning current time.

var DefaultClock Clock = ClockFunc(time.Now)

DefaultClock uses time.Now to provide current time.

type ClockFunc

type ClockFunc func() time.Time

ClockFunc is a functional adapter.

func (ClockFunc) Now

func (fun ClockFunc) Now() time.Time

type ContextFunc

type ContextFunc func(parent context.Context) (context.Context, context.CancelFunc)

ContextFunc creates a child context.Context from a given one.

func Deadline

func Deadline(deadline time.Time) ContextFunc

Deadline returns ContextFunc which uses context.WithDeadline.

func Timeout

func Timeout(timeout time.Duration) ContextFunc

Timeout returns ContextFunc which uses context.WithTimeout.

func (ContextFunc) Stack

func (f ContextFunc) Stack(another ContextFunc) ContextFunc

Stack stacks this ContextFunc with another ContextFunc. The resulting ContextFunc will first call the second one, and then the first one.

type Locker

type Locker interface {
	// Lock locks something.
	// It returns a context which should be for errors (via context.Context.Err()) and used for further
	// execution under the lock. CancelFunc must be called to release the lock (usually inside defer).
	Lock(ctx context.Context) (context.Context, context.CancelFunc)
}

Locker may be locked (interruptibly).

var Unlock Locker = unlock{}

Unlock does nothing.

func Semaphore

func Semaphore(clock Clock, size int, interval time.Duration) Locker

Semaphore allows at most `size` events at given time interval. This becomes a classic semaphore when interval = 0, and a simple mutex when size = 1. This is a reentrant Locker.

type Promise

type Promise[V any] interface {

	// Complete is used to complete this Promise.
	// It should generally not be called more than once.
	Complete(ctx context.Context, value V, err error) error
}

Promise may be completed. This is synonymous to Promise in Scala.

type RWLocker

type RWLocker interface {
	Locker

	// RLock acts the same way as Lock does, but it allows for multiple readers to hold the lock (or a single writer).
	RLock(ctx context.Context) (context.Context, context.CancelFunc)
}

RWLocker supports read-write locks.

type RWMutex

type RWMutex struct {
	// contains filtered or unexported fields
}

RWMutex is an interruptible reentrant sync.RWMutex implementation.

func (*RWMutex) Lock

func (m *RWMutex) Lock(ctx context.Context) (context.Context, context.CancelFunc)

func (*RWMutex) RLock

func (m *RWMutex) RLock(ctx context.Context) (context.Context, context.CancelFunc)

type Ref

type Ref[V any] interface {

	// Get is used to get the actual value.
	// It should block until the value is available.
	Get(ctx context.Context) (V, error)
}

Ref is a value which may not be available yet. This is synonymous to Future in Scala.

func Async

func Async[V any](ctx context.Context, body Resolve[V]) Ref[V]

Async starts an asynchronous calculation and returns a Ref to the result.

func AsyncWith

func AsyncWith[V any](ctx context.Context, contextFunc ContextFunc, body Resolve[V]) Ref[V]

AsyncWith starts an asynchronous calculation and returns a Ref to the result. ContextFunc is used to spawn a new context for calculation.

func Lazy

func Lazy[V any](body Resolve[V]) Ref[V]

Lazy runs the calculation on demand and stores the result.

type Resolve

type Resolve[V any] func(ctx context.Context) (V, error)

Resolve is a function adapter for Ref.

func (Resolve[V]) Get

func (f Resolve[V]) Get(ctx context.Context) (V, error)

type Val

type Val[V any] struct {
	V V
	E error
}

Val is a read-only value. Implements Ref interface.

func (Val[V]) Get

func (v Val[V]) Get(ctx context.Context) (V, error)

type Var

type Var[V any] struct {
	// Direct makes the Complete pass the result directly to Get without buffering.
	Direct bool
	// contains filtered or unexported fields
}

Var is a Ref and Promise implementation.

func (*Var[V]) Complete

func (v *Var[V]) Complete(ctx context.Context, value V, err error) error

func (*Var[V]) Get

func (v *Var[V]) Get(ctx context.Context) (value V, err error)

type WaitGroup

type WaitGroup struct {
	sync.WaitGroup
}

WaitGroup is a wrapper for sync.WaitGroup.

func (*WaitGroup) Spawn

func (wg *WaitGroup) Spawn(ctx context.Context) (context.Context, context.CancelFunc)

Spawn creates increments wait group counter by 1 and returns a new context with a CancelFunc. CancelFunc decrements wait group counter by 1.