Documentation
¶
Overview ¶
Package events contains an event dispatcher loosely inspired by the PSR-14 specification, published under the MIT license by the PHP-FIG.
See https://www.php-fig.org/psr/psr-14/ for details and background.
Package events contains an event dispatcher loosely inspired by the PSR-14 specification, published under the MIT license by the PHP-FIG.
See https://www.php-fig.org/psr/psr-14/ for details and background.
Index ¶
- Constants
- type Dispatcher
- type Error
- type Event
- type EventBase
- func (eb *EventBase) Data() interface{}
- func (eb *EventBase) Err() error
- func (eb *EventBase) Request() *http.Request
- func (eb *EventBase) Response() *http.Response
- func (eb *EventBase) SetData(data interface{}) Event
- func (eb *EventBase) SetError(err error) Event
- func (eb *EventBase) SetRequest(r *http.Request) Event
- func (eb *EventBase) SetResponse(r *http.Response) Event
- func (eb *EventBase) SetTopic(topic string) Event
- func (eb *EventBase) Topic() Topic
- type Listener
- type ListenerProvider
- type ListenerProviderFunc
- type Topic
Constants ¶
const DispatchStopRequest = Error("stop dispatch")
DispatchStopRequest is a sentinel error used by listeners to request that propagation be stopped, without any error condition being reported to the Emitter.
const TopicEmpty = "-empty-"
TopicEmpty is the replacement string for empty topics
const TopicFormat = `^[-_[:alnum:]]+$`
TopicFormat is the format of strings used as Event Topics.
const TopicReplacement = `[^_[:alnum:]]+`
TopicReplacement is the format used to replace non-well-formed Topic strings.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dispatcher ¶
type Dispatcher interface {
// Dispatch provides all relevant listeners with an event to process.
// It returns the same Event object it was passed after it is done invoking
// Listeners. The Event may have been mutated by Listeners.
// If an error or propagation stop was returned by one of the Listeners,
// or if the context is canceled, the dispatch loop is terminated and
// Dispatch returns that error, possibly wrapped with context data.
Dispatch(context.Context, Event) (Event, error)
// AddProviders sets the ListenerProviders for Events with a given Topic.
// It returns the modified provider, making the call chainable.
AddProviders(Topic, ...ListenerProvider) Dispatcher
// Reset re-initializes the list of providers for the specified Topic values,
// returning the dispatcher without any listener provider for those.
Reset(topics ...Topic) Dispatcher
}
Dispatcher is the interface for event dispatchers. It is inspired by the PSR-14 EventDispatcherInterface.
It is responsible for retrieving Listeners from a ListenerProvider for the Event to dispatch, and invoking each Listener with that Event.
It calls Listeners synchronously in the order they are returned by the ListenerProvider, then return to the Emitter:
- after all Listeners have executed,
- or an error occurred,
- or listener requested propagation to stop,
- or the context was canceled.
func NewDispatcher ¶
func NewDispatcher() Dispatcher
NewDispatcher returns a basic Dispatcher implementation.
Client code may use this constructor or create their own Dispatcher implementations.
type Error ¶
type Error string
Error provides the ability to define constant errors, preventing global modification. It is based on the https://dave.cheney.net/2016/04/07/constant-errors article by Dave Cheney (CC-4.0-BY-NC-SA).
type Event ¶
type Event interface {
// Topic returns an administrative label for the event.
Topic() Topic
// Data returns a generic payload.
//
// Event implementations should provide more strictly typed interfaces for
// Listeners to use, allowing them to assert for the actual expected type
// and use the typed getters accordingly.
Data() interface{}
Request() *http.Request
Response() *http.Response
Err() error
// SetData is a setter for the data returned by Data.
SetData(interface{}) Event
// SetRequest is a setter for the event request, returning the event.
SetRequest(r *http.Request) Event
// SetResponse is a setter for the event response, returning the event.
SetResponse(r *http.Response) Event
// SetError is a setter for the error, returning the event.
SetError(err error) Event
}
Event is the type of data passed around by a Dispatcher to Listeners.
type EventBase ¶
type EventBase struct {
Error error
// contains filtered or unexported fields
}
EventBase is a basic event implementation, meant to be composed into actual event types to provide default storage and code for the Event methods.
func (*EventBase) Data ¶
func (eb *EventBase) Data() interface{}
Data is part of the Event interface.
func (*EventBase) SetRequest ¶
SetRequest sets the http.Request in the event, which may be nil.
func (*EventBase) SetResponse ¶
SetResponse sets the http.Response in the event, which may be nil.
type Listener ¶
Listener is the type passed to Dispatchers as callbacks acting on events.
Unlike PSR-14 listeners, they return an error which, if non-nil, stops propagation and will be returned to the Emitter.
That error can be sentinel value DispatchStopRequest.
type ListenerProvider ¶
ListenerProvider provides the list of Listeners a Dispatcher must invoke for a given event.
type ListenerProviderFunc ¶
ListenerProviderFunc provides a means for a plain function to implement the ListenerProvider interface.
func (ListenerProviderFunc) Listeners ¶
func (lpf ListenerProviderFunc) Listeners(e Event) []Listener
Listeners implements the ListenerProvider interface.
Source Files