event

Documentation

Index

• Constants
• type BufferStrategy
• type Event
  • func Adapt[OrigArgType any, DestArgType any](origEvent Event[OrigArgType], origToDestMapper func(OrigArgType) DestArgType, ...) Event[DestArgType]
  • func New[T any]() Event[T]
• type Keyed
  • func NewKeyed[KeyType comparable, ArgType any]() Keyed[KeyType, ArgType]
• type NoArgEvent
  • func NewNoArg() NoArgEvent

Constants

const (
	// BufferNone: subscribers will be notified only if they are actively waiting on the channel.
	// (logically, it follows that any notifications happening inbetween channel reads will be lost)
	BufferNone = iota

	// BufferFirst: subscribers will be notified on the next channel read, even if they are not actively waiting on the channel.
	// They will receive the first notification that was sent after their latest read.
	// If more than one notification happens inbetween channel reads, they will be lost.
	BufferFirst

	// BufferLatest: subscribers will be notified on the next channel read, even if they are not actively waiting on the channel.
	// They will receive the latest notification that was sent after their latest read.
	// If more than one notification happens inbetween channel reads, they will be lost.
	BufferLatest

	// BufferAll: subscribers will be notified exactly as many times as the event is fired,
	// even if those notifications happen when they are not waiting on the channel.
	// The order of the events is preserved.
	BufferAll
)

Types

type BufferStrategy

type BufferStrategy int

BufferStrategy defines how much buffering happens on the receiving side for event subscribers

type Event

type Event[T any] interface {
	// Subscribe returns a channel that will receive notification events.
	// The returned function should be called when one wishes to unsubscribe
	Subscribe(bufferStrategy BufferStrategy) (<-chan T, func())

	// SubscribeUsingCallback subscribes to an event by calling the provided function with the argument passed on Notify
	// The returned function should be called when one wishes to unsubscribe
	SubscribeUsingCallback(bufferStrategy BufferStrategy, cbFunction func(arg T)) func()

	// SubscribeUsingCallbackContext subscribes to an event by calling the provided function with the argument passed on Notify
	// Unsubscription happens when either the provided context is cancelled or the returned function is called
	SubscribeUsingCallbackContext(ctx context.Context, bufferStrategy BufferStrategy, cbFunction func(arg T)) func()

	// Notify notifies subscribers that the event has occurred.
	// deferNotification controls whether an attempt will be made at late delivery if there are no subscribers to this event at the time of notification
	// (subject to the buffer strategy chosen on the subscription side)
	Notify(param T, deferNotification bool)

	// Close notifies subscribers that no more events will be sent
	Close()

	// Unsubscribed returns an event that is notified with the current subscriber count whenever a subscriber unsubscribes
	// from this event. This allows references to the event to be manually freed in code patterns that require it.
	Unsubscribed() Event[int]
}

Event is an event including dispatching mechanism

func Adapt

func Adapt[OrigArgType any, DestArgType any](origEvent Event[OrigArgType], origToDestMapper func(OrigArgType) DestArgType, destToOrigMapper func(DestArgType) OrigArgType) Event[DestArgType]

Adapt converts one event with a given argument type to one with a different argument type

func New

func New[T any]() Event[T]

New returns a new Event

type Keyed

type Keyed[KeyType comparable, ArgType any] interface {
	Subscribe(key KeyType, guaranteeType BufferStrategy) (<-chan ArgType, func())
	SubscribeUsingCallback(key KeyType, guaranteeType BufferStrategy, cbFunction func(arg ArgType)) func()
	Notify(key KeyType, param ArgType, deferNotification bool)
	NotifyAll(param ArgType)
	Close(key KeyType)
	Unsubscribed(key KeyType) Event[int]
}

Keyed is a set of key-addressable events

func NewKeyed

func NewKeyed[KeyType comparable, ArgType any]() Keyed[KeyType, ArgType]

NewKeyed returns a new Keyed event

type NoArgEvent

type NoArgEvent interface {
	// Subscribe returns a channel that will receive notification events.
	// The returned function should be called when one wishes to unsubscribe
	Subscribe(guaranteeType BufferStrategy) (<-chan struct{}, func())

	// SubscribeUsingCallback subscribes to an event by calling the provided function with the argument passed on Notify
	// The returned function should be called when one wishes to unsubscribe
	SubscribeUsingCallback(guaranteeType BufferStrategy, cbFunction func()) func()

	// SubscribeUsingCallbackContext subscribes to an event by calling the provided function with the argument passed on Notify
	// Unsubscription happens when either the provided context is cancelled or the returned function is called
	SubscribeUsingCallbackContext(ctx context.Context, bufferStrategy BufferStrategy, cbFunction func()) func()

	// Notify notifies subscribers that the event has occurred.
	// deferNotification controls whether an attempt will be made at late delivery if there are no subscribers to this event at the time of notification
	// (subject to the GuaranteeType guarantees on the subscription side)
	Notify(deferNotification bool)

	// Close notifies subscribers that no more events will be sent
	Close()

	// Unsubscribed returns an event that is notified with the current subscriber count whenever a subscriber unsubscribes
	// from this event. This allows references to the event to be manually freed in code patterns that require it.
	Unsubscribed() Event[int]
}

NoArgEvent is an Event without arguments

func NewNoArg

func NewNoArg() NoArgEvent

New returns a new NoArgEvent