README
¶
Each primitive can be waited for with a context.Context, and Signal, Latch
and Future can also be used in a select statement.
| Type | Purpose |
|---|---|
Signal |
Notifies a waiting goroutine; repeated notifications coalesce. |
Latch |
A one-way flag that unblocks all waiters when set. |
Future[T] |
A value that is stored at most once, and may not be available yet. |
Observable[T] |
An atomic value that readers can observe for changes. |
Once |
A variant of sync.Once that can fail, and can stop waiting for its turn. |
Mutex |
A variant of sync.Mutex that can stop waiting for its turn. |
Signal, Latch, Future and Observable also have read-only and write-only
views, such as LatchR and LatchW, for handing out just one side of a value.
Documentation
¶
Overview ¶
Package cosyne provides context-aware synchronization primitives.
Every primitive is ready to use as its zero value and must not be copied after first use. Signal, Latch and Future can be waited for with or without a context.Context, or used in a select statement via their Chan method.
If a method waits with a context and the awaited state has already been reached, it succeeds even if the context is done. Otherwise, a context that is already done fails the call before anything is consumed or run. Signal and Mutex are the exceptions: receiving consumes a notification, and locking acquires the mutex, so a done context always wins. Any pending notification is left in place, and the mutex isn't acquired.
Where a method reports success as a bool, true means that the call took effect and false means that the state was already as requested. The exception is Mutex.TryLock, which returns false if the mutex is already locked, so the caller doesn't hold it.
Interfaces whose names end in R or W, such as LatchR and LatchW, are the read-only and write-only views of a type. They can only be implemented by the types in this package.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Future ¶ added in v0.3.0
type Future[T any] struct { // contains filtered or unexported fields }
Future holds a value that is stored at most once, and may not be available yet.
func (*Future[T]) Chan ¶ added in v0.3.0
func (f *Future[T]) Chan() <-chan struct{}
Chan returns a channel that is closed when the value becomes available.
func (*Future[T]) Load ¶ added in v0.3.0
Load returns the value of the future, and true, if it is available.
Otherwise, it returns the zero value and false.
func (*Future[T]) Store ¶ added in v0.3.0
Store sets the value of the future.
It returns true if the value was set by this call, or false if it was already set, in which case the existing value is unchanged.
type FutureR ¶ added in v0.3.0
type FutureR[T any] interface { Load() (T, bool) Wait() T WaitContext(ctx context.Context) (T, error) Chan() <-chan struct{} // contains filtered or unexported methods }
FutureR is the read-only view of a Future. It cannot store a value.
type FutureW ¶ added in v0.3.0
FutureW is the write-only view of a Future. It cannot observe the value.
type Latch ¶ added in v0.3.0
type Latch struct {
// contains filtered or unexported fields
}
Latch is a one-way flag that unblocks any goroutines waiting on it when it is set. A latch cannot be reset.
func (*Latch) Chan ¶ added in v0.3.0
func (l *Latch) Chan() <-chan struct{}
Chan returns a channel that is closed when the latch is set.
type LatchR ¶ added in v0.3.0
type LatchR interface {
IsSet() bool
Wait()
WaitContext(ctx context.Context) error
Chan() <-chan struct{}
// contains filtered or unexported methods
}
LatchR is the read-only view of a Latch. It cannot set the latch.
type LatchW ¶ added in v0.3.0
type LatchW interface {
Set() bool
// contains filtered or unexported methods
}
LatchW is the write-only view of a Latch. It cannot observe the latch.
type Mutex ¶
type Mutex struct {
// contains filtered or unexported fields
}
Mutex is a mutual exclusion lock that can be acquired with a context.
Unlike sync.Mutex, a call to Mutex.Lock stops waiting when its context is done.
func (*Mutex) Lock ¶
Lock acquires the mutex, blocking until it's available or ctx is done.
It returns nil if it acquired the mutex, or ctx's error otherwise. If ctx is already done, it returns its error without acquiring the mutex.
type Observable ¶ added in v0.3.0
type Observable[T any] struct { // contains filtered or unexported fields }
Observable is an atomic value that can be observed for changes.
Its initial value is the zero value of T.
func (*Observable[T]) Load ¶ added in v0.3.0
func (o *Observable[T]) Load() (T, <-chan struct{})
Load returns the current value, and a channel that is closed when that value is replaced by a subsequent call to Observable.Store.
func (*Observable[T]) Store ¶ added in v0.3.0
func (o *Observable[T]) Store(v T)
Store replaces the current value.
type ObservableR ¶ added in v0.3.0
type ObservableR[T any] interface { Load() (T, <-chan struct{}) // contains filtered or unexported methods }
ObservableR is the read-only view of an Observable. It cannot store a value.
type ObservableW ¶ added in v0.3.0
type ObservableW[T any] interface { Store(v T) // contains filtered or unexported methods }
ObservableW is the write-only view of an Observable. It cannot observe the value.
type Once ¶ added in v0.2.0
type Once struct {
// contains filtered or unexported fields
}
Once is a context-aware variant of sync.Once that allows the operation to fail. The operation is repeated until it succeeds.
func (*Once) Do ¶ added in v0.2.0
Do calls fn if and only if it has not already been called successfully.
A call is successful if fn returns a nil error and does not panic. If it fails, a later call to Do calls fn again.
fn is called with ctx, and at most one call to fn is in progress at a time. Do blocks while another call is in progress, until that call completes or ctx is done.
It returns nil if fn has succeeded, otherwise the error returned by fn, or ctx's error.
type Signal ¶ added in v0.3.0
type Signal struct {
// contains filtered or unexported fields
}
Signal lets one goroutine notify another that something has happened.
A signal can be notified repeatedly. Each notification unblocks at most one waiting goroutine and is consumed by it. A notification that arrives while another is already pending is coalesced into it.
func (*Signal) Chan ¶ added in v0.3.0
func (s *Signal) Chan() <-chan struct{}
Chan returns a channel that unblocks when the signal is notified.
Receiving from the channel consumes the notification, as Signal.Wait does.
func (*Signal) Notify ¶ added in v0.3.0
Notify unblocks one waiting goroutine.
If no goroutine is waiting, the notification remains pending and the next goroutine to wait unblocks immediately.
It returns true if the notification was recorded, or false if one was already pending.
func (*Signal) Wait ¶ added in v0.3.0
func (s *Signal) Wait()
Wait blocks until the signal is notified, consuming the notification.
func (*Signal) WaitContext ¶ added in v0.3.0
WaitContext blocks until the signal is notified or ctx is done.
It returns nil if it consumed a notification, or ctx's error otherwise. If ctx is already done, it returns its error without consuming a pending notification.
type SignalR ¶ added in v0.3.0
type SignalR interface {
Wait()
WaitContext(ctx context.Context) error
Chan() <-chan struct{}
// contains filtered or unexported methods
}
SignalR is the read-only view of a Signal. It cannot notify the signal.
If several goroutines wait on the same SignalR, each notification unblocks only one of them.
Source Files