syncutil

Documentation

Overview

Package syncutil provides utilities for better handling of Goroutines.

Index

• type Signal
• type SignalEmitter
  • func (e *SignalEmitter) Emit()
• type Signaler
  • func SignalerFromEmitters(emitters ...*SignalEmitter) Signaler

Types

type Signal

type Signal <-chan struct{}

Signal represents an event, but without containing data. Underneath it is a simple receiving channel that gets closes as the signal fires.

type SignalEmitter

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

SignalEmitter implements a sync mechanism for Goroutines. It can be used by one Goroutine to notify other Goroutines that something happenend. This can be useful to implement a control loop, that depends on data that is fetched asynchronously:

- With a single emitter it helps skipping bursts, because it does not acumulate Signals while nothing is waiting for them.

- With multiple emitters it helps by having a single blocking call.

func (*SignalEmitter) Emit

func (e *SignalEmitter) Emit()

Emit fires a new Signal to all Signalers that were created with NewSignaler.

type Signaler

type Signaler interface {
	// Wait blocks until a Signal fires or the timeout passed. It does not make
	// any distiction which of those two happened.
	Wait(ctx context.Context, timeout time.Duration)

	// C provides a channel that gets closed when a Signal fires or the timeout
	// passed. The channel processing should happen immediately:
	//
	//		<-signaler.C(time.Minute) // Identical to signaler.Wait(time.Minute)
	//
	// Using C over Wait is only useful when using select:
	//
	//		select {
	//		case <-signaler.C(time.Minute):
	//			// Signal emitted or timed out.
	//		case <-something.Done():
	//			// Notification from some generic channel.
	//		}
	C(ctx context.Context, timeout time.Duration) Signal
}

Signaler is provided by a SignalEmitter and used by Goroutines that are waiting for a Signal. A Signaler should not be shared between Goroutines and its function/channels must not be called in parallel.

func SignalerFromEmitters

func SignalerFromEmitters(emitters ...*SignalEmitter) Signaler

NewSignaler creates a new Signaler, that fires on Emit calls. The resulting Signaler should not be shared between multiple Goroutines, but it is possible to create multiple Signalers from the same Emitters.