Documentation
¶
Index ¶
- func WatchBroadcast[T comparable](ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error) error
- func WatchBroadcastVT[T proto.EqualVT[T]](ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error) error
- func WatchBroadcastWithEqual[T comparable](ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error, ...) error
- type Broadcast
- func (c *Broadcast) HoldLock(cb func(broadcast func(), getWaitCh func() <-chan struct{}))
- func (c *Broadcast) HoldLockMaybeAsync(cb func(broadcast func(), getWaitCh func() <-chan struct{}))
- func (c *Broadcast) Lock() Locked
- func (c *Broadcast) TryHoldLock(cb func(broadcast func(), getWaitCh func() <-chan struct{})) bool
- func (c *Broadcast) TryLock() (Locked, bool)
- func (c *Broadcast) Wait(ctx context.Context, ...) error
- type Locked
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WatchBroadcast ¶ added in v1.33.0
func WatchBroadcast[T comparable]( ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error, ) error
WatchBroadcast watches a broadcast for changes and sends snapshots.
snapshot is called under the broadcast lock to get the current value. send is called outside the lock to transmit the value. Skips sending when the value is equal to the previous via ==. Returns when ctx is canceled or send returns an error.
func WatchBroadcastVT ¶ added in v1.33.0
func WatchBroadcastVT[T proto.EqualVT[T]]( ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error, ) error
WatchBroadcastVT watches a broadcast for changes and sends snapshots.
Uses EqualVT for deduplication. Same as WatchBroadcast but for VTProtobuf messages.
func WatchBroadcastWithEqual ¶ added in v1.33.0
func WatchBroadcastWithEqual[T comparable]( ctx context.Context, bcast *Broadcast, snapshot func() T, send func(T) error, equal func(a, b T) bool, ) error
WatchBroadcastWithEqual watches a broadcast for changes and sends snapshots.
snapshot is called under the broadcast lock to get the current value. send is called outside the lock to transmit the value. equal is an optional comparator; if nil, uses == for dedup. Returns when ctx is canceled or send returns an error.
Types ¶
type Broadcast ¶
type Broadcast struct {
// contains filtered or unexported fields
}
Broadcast implements notifying waiters via a channel.
The zero-value of this struct is valid.
Example ¶
// b guards currValue
var b Broadcast
var currValue int
go func() {
// 0 to 9 inclusive
for i := range 10 {
<-time.After(time.Millisecond * 20)
locked := b.Lock()
currValue = i
locked.Broadcast()
locked.Unlock()
}
}()
var waitCh <-chan struct{}
var gotValue int
for {
locked := b.Lock()
gotValue = currValue
if gotValue != 9 {
waitCh = locked.WaitCh()
}
locked.Unlock()
// last value
if gotValue == 9 {
// success
break
}
// otherwise keep waiting
<-waitCh
}
fmt.Printf("waited for value to increment: %v\n", gotValue)
Output: waited for value to increment: 9
func (*Broadcast) HoldLock ¶ added in v1.6.0
func (c *Broadcast) HoldLock(cb func(broadcast func(), getWaitCh func() <-chan struct{}))
HoldLock locks the mutex and calls the callback.
broadcast closes the wait channel, if any. getWaitCh returns a channel that will be closed when broadcast is called. Prefer Lock in allocation-sensitive paths because it exposes the same operations as methods on a guard and avoids constructing callback operation closures.
func (*Broadcast) HoldLockMaybeAsync ¶ added in v1.11.1
func (c *Broadcast) HoldLockMaybeAsync(cb func(broadcast func(), getWaitCh func() <-chan struct{}))
HoldLockMaybeAsync locks the mutex and calls the callback if possible.
If the mutex cannot be locked right now, it starts a new goroutine to wait for it. This is a compatibility helper for callback-shaped callers; direct hot paths should use Lock or TryLock.
func (*Broadcast) Lock ¶ added in v1.34.5
Lock locks the broadcast and returns a held lock guard.
Use this API in hot paths that already have clear lock scope. It exists so callers can inspect guarded state, call WaitCh only when they must block, and call Broadcast without allocating callback operation closures.
func (*Broadcast) TryHoldLock ¶ added in v1.25.7
TryHoldLock attempts to lock the mutex and call the callback.
It returns true if the lock was acquired and the callback was called. Prefer TryLock in allocation-sensitive paths.
func (*Broadcast) TryLock ¶ added in v1.34.5
TryLock attempts to lock the broadcast and returns whether it succeeded.
func (*Broadcast) Wait ¶ added in v1.25.5
func (c *Broadcast) Wait(ctx context.Context, cb func(broadcast func(), getWaitCh func() <-chan struct{}) (bool, error)) error
Wait waits for the callback to return true or an error before returning.
When the broadcast channel is broadcasted, Wait calls cb again under the broadcast lock to re-check the guarded value. It returns context.Canceled if ctx is canceled.
Example ¶
// b guards currValue
var b Broadcast
var currValue int
go func() {
// 0 to 9 inclusive
for i := range 10 {
<-time.After(time.Millisecond * 20)
b.HoldLock(func(broadcast func(), getWaitCh func() <-chan struct{}) {
currValue = i
broadcast()
})
}
}()
ctx := context.Background()
var gotValue int
err := b.Wait(ctx, func(broadcast func(), getWaitCh func() <-chan struct{}) (bool, error) {
gotValue = currValue
return gotValue == 9, nil
})
if err != nil {
fmt.Printf("failed to wait for value: %v", err.Error())
return
}
fmt.Printf("waited for value to increment: %v\n", gotValue)
Output: waited for value to increment: 9
type Locked ¶ added in v1.34.5
type Locked struct {
// contains filtered or unexported fields
}
Locked is a held Broadcast lock for allocation-sensitive callers.
Broadcast also has callback helpers, but those helpers pass broadcast and wait-channel operations as function values. Hot callers can use Locked to do the same work with direct method calls, which avoids per-lock callback closures and keeps the state check next to the optional wait subscription. Call Unlock exactly once, and do not copy a Locked value after use.
func (*Locked) Broadcast ¶ added in v1.34.5
func (l *Locked) Broadcast()
Broadcast closes the current wait channel and starts a new wait epoch.
Call Broadcast while holding the Locked guard after mutating the guarded state. Waiters that already called WaitCh wake from the closed channel, and a later WaitCh call allocates the next epoch.
func (*Locked) Unlock ¶ added in v1.34.5
func (l *Locked) Unlock()
Unlock releases the held broadcast lock.
func (*Locked) WaitCh ¶ added in v1.34.5
func (l *Locked) WaitCh() <-chan struct{}
WaitCh returns a channel that closes on the next Broadcast call.
WaitCh allocates the wait epoch lazily, so callers should call it only after they have checked the guarded state and determined they really need to block.
Source Files