event

Documentation

Overview

Package event is a library to support event producers and handlers.

Index

• func Connect(ctx context.Context, listener Listener, handler Handler) error
• func Feed(ctx context.Context, dst Handler, src Producer) error
• func Monitor(ctx context.Context, lock sync.Locker, listener Listener, producer Producer, ...) error
• type Broadcast
  • func (b *Broadcast) Listen(ctx context.Context, h Handler)
  • func (b *Broadcast) Send(ctx context.Context, event interface{}) error
• type Handler
  • func AsHandler(ctx context.Context, f interface{}) Handler
  • func Buffer(ctx context.Context, handler Handler) Handler
  • func Drain(ctx context.Context, handler Handler) (Handler, <-chan error)
  • func Filter(ctx context.Context, pred Predicate, handler Handler) Handler
  • func FilterAny(ctx context.Context, pred interface{}, dst interface{}) Handler
• type Listener
• type Predicate
  • func AsPredicate(ctx context.Context, f interface{}) Predicate
• type Producer
  • func AsProducer(ctx context.Context, f interface{}) Producer
• type Source

Functions

func Connect

func Connect(ctx context.Context, listener Listener, handler Handler) error

Connect adds a handler to a listener in a way that blocks until the handler is done.

func Feed

func Feed(ctx context.Context, dst Handler, src Producer) error

Feed passes events from a producer to the handler. It returns only when either src returns nil or dst returns an error. It will not pass the nil onto dst. It converts a pull interface to a push one.

func Monitor

func Monitor(ctx context.Context, lock sync.Locker, listener Listener, producer Producer, handler Handler) error

Monitor feeds an initial producer to the handler, and then adds a handler to the listener. It does all of that under a lock, and then waits for the event stream to drain after the lock is released. This is commonly used for things that want to feed an existing data set and then keep watching for new entries arriving.

Types

type Broadcast

type Broadcast []Handler

Broadcast implements a list of handlers that itself is a handler. Events written to the broadcast are sent to all handlers in the list

func (*Broadcast) Listen

func (b *Broadcast) Listen(ctx context.Context, h Handler)

Listen adds a new handler to the set. It conforms to the Listener signature.

func (*Broadcast) Send

func (b *Broadcast) Send(ctx context.Context, event interface{}) error

Send implements Handler to send (sequentially) to all current handlers. Handlers that return an error will be dropped from the broadcast list.

type Handler

type Handler func(ctx context.Context, event interface{}) error

Handler is the type for functions to which events can be delivered.

func AsHandler

func AsHandler(ctx context.Context, f interface{}) Handler

AsHandler wraps a destination into an event handler. The destination can be one of

func(context.Context, T, error) error
chan T
chan<- T

If it is not, this function will panic, as this is assumed to be a programming error. If the handler is invoked with an event that is not of type T the handler will return an error.

func Buffer

func Buffer(ctx context.Context, handler Handler) Handler

Buffer returns a handler that will feed the supplied handler, but inserts a unbounded buffer and goroutine switch between the two handlers so that the input handler always returns immediatly without waiting for the underlying handler to be invoked and complete. This is a *very* dangerous function to use, as it fully uncouples the handlers, and can result in unbounded memory consumption with no ability to flow control.

func Drain

func Drain(ctx context.Context, handler Handler) (Handler, <-chan error)

Drain returns a handler wrapper and a channel that will block until the event stream is done.

func Filter

func Filter(ctx context.Context, pred Predicate, handler Handler) Handler

Filter returns a handler that only forwards events to the underlying handler if pred is true for that event.

func FilterAny

func FilterAny(ctx context.Context, pred interface{}, dst interface{}) Handler

FilterAny returns a handler that only forwards events to the underlying handler if pred is true for that event. It obeys the same rules as AsHandler and AsPredicate when dealing with pred and dst.

type Listener

type Listener func(ctx context.Context, handler Handler)

Listener is the signature for a function that accepts handlers to send events to.

type Predicate

type Predicate func(ctx context.Context, event interface{}) bool

Predicate is the signature for a function that tests an event for a boolean property.

func AsPredicate

func AsPredicate(ctx context.Context, f interface{}) Predicate

AsPredicate wraps a function into an event predicate. The function must be a function of the form

func(context.Context, T) bool

If it is not, this function will panic, as this is assumed to be a programming error. If the handler is invoked with an event that is not of type T the handler will return an error.

type Producer

type Producer func(ctx context.Context) interface{}

Producer is the type for a function that generates events.

func AsProducer

func AsProducer(ctx context.Context, f interface{}) Producer

AsProducer wraps an event generator into an event producer. The generator can be one of

func(context.Context) T
Source
chan T
<-chan T
[]T
[n]T

If it is not, this function will panic, as this is assumed to be a programming error.

type Source

type Source interface {
	// Next is a method that matches the Producer signature.
	// It will respond with the events in stream order.
	Next(ctx context.Context) interface{}
	// Close can be used to notify the stream that no more events are desired.
	Close(ctx context.Context)
}

Source is the type for a closable event producer. This allows a consumer to indicate that they no longer need the source.