Documentation
¶
Overview ¶
Package syncx provides concurrency primitives including TTL maps, RW maps, broadcasters, and balancers.
Index ¶
- type Broadcaster
- func (b *Broadcaster[T]) Broadcast(msg T)
- func (b *Broadcaster[T]) BroadcastTry(msg T, onDrop func(key string, num uint64))
- func (b *Broadcaster[T]) RegisterBufferedListener(key string, bufSize int) chan T
- func (b *Broadcaster[T]) RegisterListener(key string) chan T
- func (b *Broadcaster[T]) UnregisterListener(key string)
- type RWMap
- func (rm *RWMap[K, V]) Delete(key K)
- func (rm *RWMap[K, V]) DeleteAll()
- func (rm *RWMap[K, V]) Do(key K, fn func(value V)) bool
- func (rm *RWMap[K, V]) DoAndApply(key K, fn func(value V) V)
- func (rm *RWMap[K, V]) Keys() []K
- func (rm *RWMap[K, V]) Len() int
- func (rm *RWMap[K, V]) Load(key K) (value V, ok bool)
- func (rm *RWMap[K, V]) LoadAll() map[K]V
- func (rm *RWMap[K, V]) LoadAllAndErase() map[K]V
- func (rm *RWMap[K, V]) Range(f func(key K, value V) bool)
- func (rm *RWMap[K, V]) Replace(m map[K]V) map[K]V
- func (rm *RWMap[K, V]) Store(key K, value V)
- func (rm *RWMap[K, V]) Upsert(key K, fn func(value V) V, zeroValue V)
- type RWSlice
- type RoundRobinBalancer
- type TTLMap
- func (m *TTLMap[K, V]) Close()
- func (m *TTLMap[K, V]) Delete(k K)
- func (m *TTLMap[K, V]) Do(k K, fn func(v V)) bool
- func (m *TTLMap[K, V]) DoAndApply(k K, fn func(v V) V) bool
- func (m *TTLMap[K, V]) Get(k K) (val V, ok bool)
- func (m *TTLMap[K, V]) GetAndRefresh(k K) (val V, ok bool)
- func (m *TTLMap[K, V]) Len() int
- func (m *TTLMap[K, V]) LoadAll() map[K]V
- func (m *TTLMap[K, V]) Put(k K, v V)
- func (m *TTLMap[K, V]) Upsert(key K, fn func(value V) V, zeroValue V)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Broadcaster ¶
type Broadcaster[T any] struct { // contains filtered or unexported fields }
Broadcaster fans out messages of type T to named listeners.
func NewBroadcaster ¶
func NewBroadcaster[T any]() *Broadcaster[T]
NewBroadcaster creates a new broadcaster for messages of type T.
func (*Broadcaster[T]) Broadcast ¶
func (b *Broadcaster[T]) Broadcast(msg T)
Broadcast sends a message to all registered listeners.
func (*Broadcaster[T]) BroadcastTry ¶ added in v0.1.4
func (b *Broadcaster[T]) BroadcastTry(msg T, onDrop func(key string, num uint64))
BroadcastTry is non-blocking; on a full buffer it drops msg. onDrop runs after b.mu is released, once per listener with a drop count.
func (*Broadcaster[T]) RegisterBufferedListener ¶ added in v0.1.4
func (b *Broadcaster[T]) RegisterBufferedListener(key string, bufSize int) chan T
RegisterBufferedListener registers a listener with a bounded channel.
func (*Broadcaster[T]) RegisterListener ¶
func (b *Broadcaster[T]) RegisterListener(key string) chan T
RegisterListener registers an unbuffered listener. Call UnregisterListener when done to avoid leaks and blocking Broadcast.
func (*Broadcaster[T]) UnregisterListener ¶
func (b *Broadcaster[T]) UnregisterListener(key string)
UnregisterListener removes a listener and closes its channel.
type RWMap ¶
type RWMap[K comparable, V any] struct { // contains filtered or unexported fields }
RWMap provides a thread-safe map implementation using read-write locks
func NewRWMap ¶
func NewRWMap[K comparable, V any]() *RWMap[K, V]
NewRWMap creates a new empty thread-safe map
func NewRWMapFromStdMap ¶
func NewRWMapFromStdMap[K comparable, V any](m map[K]V) *RWMap[K, V]
NewRWMapFromStdMap creates a new thread-safe map from an existing standard map
func (*RWMap[K, V]) Delete ¶
func (rm *RWMap[K, V]) Delete(key K)
Delete removes a key-value pair from the map
func (*RWMap[K, V]) DeleteAll ¶
func (rm *RWMap[K, V]) DeleteAll()
DeleteAll removes all key-value pairs from the map
func (*RWMap[K, V]) Do ¶
Do executes a function on a value under read lock. Returns false if the key is not found
func (*RWMap[K, V]) DoAndApply ¶
func (rm *RWMap[K, V]) DoAndApply(key K, fn func(value V) V)
DoAndApply executes a function on a value under write lock and stores the result back
func (*RWMap[K, V]) Keys ¶
func (rm *RWMap[K, V]) Keys() []K
Keys returns a slice of all keys in the map
func (*RWMap[K, V]) LoadAll ¶
func (rm *RWMap[K, V]) LoadAll() map[K]V
LoadAll returns a copy of the entire map
func (*RWMap[K, V]) LoadAllAndErase ¶
func (rm *RWMap[K, V]) LoadAllAndErase() map[K]V
LoadAllAndErase returns a copy of the entire map and clears the stored entries
func (*RWMap[K, V]) Range ¶
Range calls the provided function for each key/value pair in the map If the function returns false, iteration stops
func (*RWMap[K, V]) Replace ¶
func (rm *RWMap[K, V]) Replace(m map[K]V) map[K]V
Replace swaps the internal map with the provided one and returns the previous map
type RWSlice ¶
type RWSlice[V any] struct { // contains filtered or unexported fields }
RWSlice provides a thread-safe slice implementation using read-write locks
func (*RWSlice[V]) AddBulk ¶
func (rw *RWSlice[V]) AddBulk(values []V)
AddBulk appends a list of values to the slice
func (*RWSlice[V]) LoadAll ¶
func (rw *RWSlice[V]) LoadAll() []V
LoadAll returns the current slice contents
func (*RWSlice[V]) LoadAndErase ¶
func (rw *RWSlice[V]) LoadAndErase() []V
LoadAndErase returns the current slice contents and clears the slice
type RoundRobinBalancer ¶
type RoundRobinBalancer[T any] struct { // contains filtered or unexported fields }
RoundRobinBalancer provides thread-safe round-robin selection from a slice of values.
func NewRoundRobinBalancer ¶
func NewRoundRobinBalancer[T any](values []T) *RoundRobinBalancer[T]
NewRoundRobinBalancer creates a new round-robin balancer with the given values. The balancer cycles through values in order, returning to the start after the last value.
func (*RoundRobinBalancer[T]) Next ¶
func (wb *RoundRobinBalancer[T]) Next() T
Next returns the next value in round-robin order. Thread-safe: uses atomic operations for concurrent access.
func (*RoundRobinBalancer[T]) Values ¶
func (wb *RoundRobinBalancer[T]) Values() []T
Values returns a copy of all values managed by this balancer.
type TTLMap ¶
type TTLMap[K comparable, V any] struct { // contains filtered or unexported fields }
TTLMap stores values with a time-to-live. Expired items are removed during cleanup or upon access.
Performance characteristics vs a single-mutex map:
- 32 independent shards → up to 32× lower lock contention on concurrent reads/writes
- Value-typed items (no pointer per entry) → lower GC overhead and better locality
- int64 nanosecond expiry → cheaper comparison, 8 bytes instead of 24
- Get uses RLock on the hot (non-expired) path → concurrent reads scale with cores
func NewTTLMap ¶
func NewTTLMap[K comparable, V any](maxTTL, cleanupInterval time.Duration) *TTLMap[K, V]
NewTTLMap creates a TTL map with a background cleanup goroutine. Call Close() when done to stop the goroutine.
func NewTTLMapWithContext ¶
func NewTTLMapWithContext[K comparable, V any](ctx context.Context, maxTTL, cleanupInterval time.Duration) *TTLMap[K, V]
NewTTLMapWithContext ties the cleanup goroutine to ctx and also supports Close().
func (*TTLMap[K, V]) Close ¶
func (m *TTLMap[K, V]) Close()
Close stops the background cleanup goroutine and waits for it to exit, safe to call multiple times.
func (*TTLMap[K, V]) Delete ¶
func (m *TTLMap[K, V]) Delete(k K)
Delete removes the value associated with the given key.
func (*TTLMap[K, V]) Do ¶
Do executes fn with the value associated with key. The map lock is released before fn is called, so fn may safely access the map. If the key is missing or expired, fn is not called and false is returned.
func (*TTLMap[K, V]) DoAndApply ¶
DoAndApply modifies the value associated with key using fn. The expiry time is not changed. Returns false if the key is missing or expired.
func (*TTLMap[K, V]) Get ¶
Get returns the value associated with key. Uses RLock on the hot (live) path for concurrent read scalability; upgrades to a write lock only when an expired entry must be deleted.
func (*TTLMap[K, V]) GetAndRefresh ¶
GetAndRefresh returns the value associated with key and resets its TTL. If the key is missing or expired, the zero value and false are returned.
func (*TTLMap[K, V]) Len ¶
Len returns the total number of entries across all shards (including not-yet-evicted expired ones). Thread-safe.
func (*TTLMap[K, V]) LoadAll ¶
func (m *TTLMap[K, V]) LoadAll() map[K]V
LoadAll returns a snapshot of all live (non-expired) entries.
Source Files