Documentation
¶
Overview ¶
Package zsync provides thread-safe concurrent data structures for Go applications.
This package offers high-performance, generic implementations of common data structures with built-in synchronization, eliminating the need for external locking when accessing shared data across multiple goroutines.
Data Structures ¶
ZMap: A thread-safe generic map implementation using read-write locks for optimal performance. Supports all standard map operations with concurrent safety.
ZSet: A thread-safe generic set implementation built on top of ZMap, providing efficient operations for managing collections of unique values.
ZQueue: A thread-safe generic FIFO queue implementation with blocking operations for producer/consumer scenarios. Supports context cancellation and graceful shutdown.
Error Handling ¶
All operations follow consistent error handling patterns:
- ErrQueueClosed: Returned when attempting to operate on a closed queue
- ErrQueueEmpty: Returned when attempting to pop from an empty queue
- ErrCanceled: Returned when operations are canceled via context
- Boolean returns: Indicate success/failure for operations like Get, Delete, Remove
- No panics: All error conditions are handled gracefully
Performance Characteristics ¶
- Read operations use RLock for concurrent access - Write operations use exclusive Lock for data integrity - Memory efficient: ZSet uses struct{} values to minimize overhead - Pre-allocated slices in bulk operations to reduce allocations
Usage Examples ¶
Basic ZMap usage:
m := zsync.NewZMap[string, int]()
m.Set("key", 42)
value, ok := m.Get("key")
if !ok {
// key not found
}
existed := m.Delete("key")
Basic ZSet usage:
s := zsync.NewZSet[string]()
s.Add("value")
if s.Contains("value") {
s.Remove("value")
}
values := s.Values() // []string with all unique values
Basic ZQueue usage:
q := zsync.NewZQueue[string]()
q.Push("item1")
item, err := q.Pop() // blocks until item available
if err != nil {
// handle ErrQueueClosed
}
q.Close() // signal shutdown to waiting consumers
Thread Safety ¶
All data structures in this package are fully thread-safe and can be used concurrently from multiple goroutines without additional synchronization. The implementations use efficient read-write locks to maximize concurrent read performance while ensuring data consistency during writes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrQueueClosed = errors.New("queue closed") ErrQueueEmpty = errors.New("queue empty") ErrCanceled = errors.New("operation canceled") )
Package-level errors used across multiple data structures
Functions ¶
Types ¶
type ZMap ¶
type ZMap[K comparable, V any] struct { // contains filtered or unexported fields }
ZMap is a thread-safe generic map implementation. It provides concurrent access to a map with read-write locking for performance.
func NewZMap ¶
func NewZMap[K comparable, V any]() *ZMap[K, V]
NewZMap creates a new thread-safe map with the specified key and value types.
func (*ZMap[K, V]) Clear ¶
func (m *ZMap[K, V]) Clear()
Clear removes all key-value pairs from the map.
func (*ZMap[K, V]) Delete ¶
Delete removes a key-value pair from the map. Returns true if the key existed and was deleted, false otherwise.
func (*ZMap[K, V]) Get ¶
Get retrieves the value associated with the given key. Returns the value and true if found, or the zero value and false if not.
func (*ZMap[K, V]) Keys ¶
func (m *ZMap[K, V]) Keys() []K
Keys returns a slice containing all keys in the map. The order of keys is not guaranteed.
type ZQueue ¶
type ZQueue[T any] struct { // contains filtered or unexported fields }
ZQueue is a thread-safe generic FIFO queue implementation. It provides blocking operations for producer/consumer scenarios with context cancellation support.
func (*ZQueue[T]) Close ¶
Close closes the queue, waking up any blocked Pop operations. After closing, Push operations will return ErrQueueClosed.
func (*ZQueue[T]) Pop ¶
Pop removes and returns an item from the front of the queue. Returns ErrQueueClosed if the queue is empty and closed.
func (*ZQueue[T]) PopContext ¶
PopContext removes and returns an item from the front of the queue with context cancellation. Returns ErrQueueClosed if the queue is empty and closed, or ErrCanceled if the context is canceled.
type ZSet ¶
type ZSet[T comparable] struct { // contains filtered or unexported fields }
ZSet is a thread-safe generic set implementation. It provides concurrent access to a set of unique values built on top of ZMap.
func NewZSet ¶
func NewZSet[T comparable]() *ZSet[T]
NewZSet creates a new thread-safe set with the specified value type.
func (*ZSet[T]) Add ¶
func (s *ZSet[T]) Add(value T)
Add inserts a value into the set. If the value already exists, this operation has no effect.
func (*ZSet[T]) Contains ¶
Contains checks if a value exists in the set. Returns true if the value is present, false otherwise.
func (*ZSet[T]) Ordered ¶
Ordered returns a slice containing all values in the set sorted using the provided comparison function. Use the package-level Ordered for cmp.Ordered types.
Source Files