sync

type Chan ¶

type Chan[T any] struct {
	// contains filtered or unexported fields
}

A Chan is a channel of type T, synchronized with lock-free atomic operations.

The initial value is nil, requiring a call to a method that initializes a channel, such as Chan.New or Chan.Reset. If lazy initialization is needed, LazyChan can be used.

Since Chan uses atomic.Pointer to store the underlying channel, it inherits the same restrictions disallowing copying and spurious type conversion.

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var ch sync.Chan[string]
	c := ch.New(0)

	go func() {
		defer ch.Close()
		for range 5 {
			c <- "done"
		}
	}()

	for v := range c {
		fmt.Println(v)
	}
}

Output:

done
done
done
done
done

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var ch sync.Chan[int]
	ch.New(1) <- 10  // initialize and write to buffered channel
	v := <-ch.Load() // atomically load new channel and read
	fmt.Println(v)
}

Output:

10

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	ch := sync.NewChan[int](0).Load()

	go func() {
		defer close(ch)
		ch <- 10
		ch <- 20
		ch <- 30
	}()

	for v := range ch {
		fmt.Println(v)
	}
}

Output:

10
20
30

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	ch := sync.NewChan[int](10)
	ch.Load() <- 10
	ch.Reset() <- 20 // reset without reading, and send new value
	v := <-ch.Recv()
	fmt.Println(v)
}

Output:

20

package main

import (
	"fmt"
	"time"

	"go.chrisrx.dev/x/sync"
)

func main() {
	ch := sync.NewChan[int](0)

	sent := ch.TrySend(10) // will timeout
	time.Sleep(200 * time.Millisecond)
	fmt.Println(sent)

	go func() {
		defer ch.Close()

		ch.Send(20, 30)
	}()

	for v := range ch.Recv() {
		fmt.Println(v)
	}
}

Output:

false
20
30

func NewChan[T any](capacity int) *Chan[T]

func (ch *Chan[T]) Cap() int

func (ch *Chan[T]) Close()

func (ch *Chan[T]) CloseAndRecv() <-chan T

func (ch *Chan[T]) Closed() bool

func (ch *Chan[T]) Load() chan T

func (ch *Chan[T]) LoadOrNew() (_ chan T, isNew bool)

func (ch *Chan[T]) New(capacity int) chan T

func (ch *Chan[T]) Recv() <-chan T

func (ch *Chan[T]) Reset() chan T

func (ch *Chan[T]) Send(messages ...T)

func (ch *Chan[T]) TrySend(messages ...T) (sent bool)

type Cond ¶

type Cond = sync.Cond

Cond implements a condition variable, a rendezvous point for goroutines waiting for or announcing the occurrence of an event.

Each Cond has an associated Locker L (often a *Mutex or *RWMutex), which must be held when changing the condition and when calling the [Cond.Wait] method.

A Cond must not be copied after first use.

In the terminology of the Go memory model, Cond arranges that a call to [Cond.Broadcast] or [Cond.Signal] “synchronizes before” any Wait call that it unblocks.

For many simple use cases, users will be better off using channels than a Cond (Broadcast corresponds to closing a channel, and Signal corresponds to sending on a channel).

For more on replacements for sync.Cond, see Roberto Clapis's series on advanced concurrency patterns, as well as Bryan Mills's talk on concurrency patterns.

This is an alias of https://pkg.go.dev/sync#Cond.

func NewCond(l Locker) *Cond

type LazyChan ¶

type LazyChan[T any] struct {
	Chan[T]
	// contains filtered or unexported fields
}

LazyChan wraps a Chan, initializing lazily upon initial access.

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var ch sync.LazyChan[string]

	go func() {
		defer ch.Close()
		for range 5 {
			ch.Load() <- "done"
		}
	}()

	for v := range ch.Load() {
		fmt.Println(v)
	}
}

Output:

done
done
done
done
done

func (l *LazyChan[T]) Close()

func (l *LazyChan[T]) Load() chan T

func (l *LazyChan[T]) Recv() <-chan T

func (l *LazyChan[T]) Send(messages ...T)

func (l *LazyChan[T]) TrySend(messages ...T) (sent bool)

type Locker ¶

type Locker = sync.Locker

A Locker represents an object that can be locked and unlocked.

This is an alias of https://pkg.go.dev/sync#Locker.

type Map ¶

type Map = sync.Map

Map is like a Go map[any]any but is safe for concurrent use by multiple goroutines without additional locking or coordination. Loads, stores, and deletes run in amortized constant time.

The Map type is specialized. Most code should use a plain Go map instead, with separate locking or coordination, for better type safety and to make it easier to maintain other invariants along with the map content.

The Map type is optimized for two common use cases: (1) when the entry for a given key is only ever written once but read many times, as in caches that only grow, or (2) when multiple goroutines read, write, and overwrite entries for disjoint sets of keys. In these two cases, use of a Map may significantly reduce lock contention compared to a Go map paired with a separate Mutex or RWMutex.

The zero Map is empty and ready for use. A Map must not be copied after first use.

In the terminology of the Go memory model, Map arranges that a write operation “synchronizes before” any read operation that observes the effect of the write, where read and write operations are defined as follows. [Map.Load], [Map.LoadAndDelete], [Map.LoadOrStore], [Map.Swap], [Map.CompareAndSwap], and [Map.CompareAndDelete] are read operations; [Map.Delete], [Map.LoadAndDelete], [Map.Store], and [Map.Swap] are write operations; [Map.LoadOrStore] is a write operation when it returns loaded set to false; [Map.CompareAndSwap] is a write operation when it returns swapped set to true; and [Map.CompareAndDelete] is a write operation when it returns deleted set to true.

This is an alias of https://pkg.go.dev/sync#Map.

type Mutex ¶

type Mutex = sync.Mutex

A Mutex is a mutual exclusion lock. The zero value for a Mutex is an unlocked mutex.

A Mutex must not be copied after first use.

In the terminology of the Go memory model, the n'th call to [Mutex.Unlock] “synchronizes before” the m'th call to [Mutex.Lock] for any n < m. A successful call to [Mutex.TryLock] is equivalent to a call to Lock. A failed call to TryLock does not establish any “synchronizes before” relation at all.

This is an alias of https://pkg.go.dev/sync#Mutex.

type Once ¶

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

Once is a resettable version of sync.Once.

func (o *Once) Do(f func())

func (o *Once) Reset()

type Pool ¶

type Pool = sync.Pool

A Pool is a set of temporary objects that may be individually saved and retrieved.

Any item stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.

A Pool is safe for use by multiple goroutines simultaneously.

Pool's purpose is to cache allocated but unused items for later reuse, relieving pressure on the garbage collector. That is, it makes it easy to build efficient, thread-safe free lists. However, it is not suitable for all free lists.

An appropriate use of a Pool is to manage a group of temporary items silently shared among and potentially reused by concurrent independent clients of a package. Pool provides a way to amortize allocation overhead across many clients.

An example of good use of a Pool is in the fmt package, which maintains a dynamically-sized store of temporary output buffers. The store scales under load (when many goroutines are actively printing) and shrinks when quiescent.

On the other hand, a free list maintained as part of a short-lived object is not a suitable use for a Pool, since the overhead does not amortize well in that scenario. It is more efficient to have such objects implement their own free list.

A Pool must not be copied after first use.

In the terminology of the Go memory model, a call to Put(x) “synchronizes before” a call to [Pool.Get] returning that same value x. Similarly, a call to New returning x “synchronizes before” a call to Get returning that same value x.

This is an alias of https://pkg.go.dev/sync#Pool.

type RWMutex ¶

type RWMutex = sync.RWMutex

A RWMutex is a reader/writer mutual exclusion lock. The lock can be held by an arbitrary number of readers or a single writer. The zero value for a RWMutex is an unlocked mutex.

A RWMutex must not be copied after first use.

If any goroutine calls [RWMutex.Lock] while the lock is already held by one or more readers, concurrent calls to [RWMutex.RLock] will block until the writer has acquired (and released) the lock, to ensure that the lock eventually becomes available to the writer. Note that this prohibits recursive read-locking. A [RWMutex.RLock] cannot be upgraded into a [RWMutex.Lock], nor can a [RWMutex.Lock] be downgraded into a [RWMutex.RLock].

In the terminology of the Go memory model, the n'th call to [RWMutex.Unlock] “synchronizes before” the m'th call to Lock for any n < m, just as for Mutex. For any call to RLock, there exists an n such that the n'th call to Unlock “synchronizes before” that call to RLock, and the corresponding call to [RWMutex.RUnlock] “synchronizes before” the n+1'th call to Lock.

This is an alias of https://pkg.go.dev/sync#RWMutex.

type Semaphore ¶

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

Semaphore is a weighted semaphore implementation built around Chan.

package main

import (
	"fmt"
	"time"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var sem sync.Semaphore
	sem.SetLimit(2)

	go func() {
		defer sem.Release()
		time.Sleep(100 * time.Millisecond)
	}()

	sem.Acquire(3)
	fmt.Println("done")
}

Output:

done

func NewSemaphore(n int) *Semaphore

func (s *Semaphore) Acquire(n int)

func (s *Semaphore) Release()

func (s *Semaphore) ReleaseN(n int)

func (s *Semaphore) SetLimit(n int)

func (s *Semaphore) TryAcquire(n int) bool

type SeqChan ¶

type SeqChan[T any] struct {
	Chan[T]
}

SeqChan wraps a Chan, providing Send/Recv methods that operate on iterator sequences.

package main

import (
	"fmt"
	"slices"

	"go.chrisrx.dev/x/sync"
)

func main() {
	ch := sync.NewSeqChan[int](0)

	go func() {
		defer ch.Close()

		ch.Send(slices.Values([]int{10, 20, 30}))
	}()

	for v := range ch.Recv() {
		fmt.Println(v)
	}
}

Output:

10
20
30

func NewSeqChan[T any](capacity int) *SeqChan[T]

func (s *SeqChan[T]) Recv() iter.Seq[T]

func (s *SeqChan[T]) Send(seq iter.Seq[T])

func (s *SeqChan[T]) TrySend(seq iter.Seq[T]) (sent bool)

type WaitGroup ¶

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

A WaitGroup works like a sync.WaitGroup with a semaphore that limits concurrency.

package main

import (
	"fmt"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var wg sync.WaitGroup
	wg.SetLimit(2)

	for range 5 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			fmt.Println("done")
		}()
	}

	wg.Wait()
}

Output:

done
done
done
done
done

func (w *WaitGroup) Add(delta int)

func (w *WaitGroup) Done()

func (w *WaitGroup) SetLimit(n int)

func (w *WaitGroup) TryAdd(delta int) bool

func (w *WaitGroup) Wait()

type Waiter ¶

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

A Waiter uses a LazyChan to wait for an event to occur.

package main

import (
	"fmt"
	"time"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var ready sync.Waiter

	go func() {
		defer ready.Done()
		time.Sleep(100 * time.Millisecond)
	}()

	ready.Wait()
	fmt.Println("done")
}

Output:

done

package main

import (
	"fmt"
	"time"

	"go.chrisrx.dev/x/sync"
)

func main() {
	var ready sync.Waiter

	go func() {
		defer ready.Done()
		time.Sleep(100 * time.Millisecond)
	}()

	ready.Wait()
	fmt.Println("done")

	ready.Reset()

	go func() {
		defer ready.Done()
		time.Sleep(100 * time.Millisecond)
	}()

	ready.Wait()
	fmt.Println("done")
}

Output:

done
done

func (w *Waiter) C() <-chan empty

func (w *Waiter) Done()

func (w *Waiter) Reset()

func (w *Waiter) Wait()