Documentation
¶
Overview ¶
Package pubsub implements helpers to connect to and read events from Redis in a reliable way.
Subscriptions are handled on a Redis connection; multiple listeners can be attached to single events, and subscription and unsubscription on the connection are handled automatically. If the connection goes down, a new connection will be established and events will be automatically re-subscribed to. All methods are thread-safe.
Sometimes you wish to subscribe to a simple, single event in Redis, but more often than not you want to subscribe to an event on a resource. Pubsub gives gives you an easy way to handle these kinds of subscriptions, without the need for `fmt` on your part or any kind or reflection-based formatting on ours. You create Event structures with typed fields and can later inspect those fields when you receive an event from Redis, in a reasonably fluid and very type-safe manner.
Simple Event
pub := pubsub.New(cnx)
pub.Subscribe(pubsub.NewEvent("foo"), function (e pubsub.Event, b []byte) {
// You're passed the subscribed event and any byte payload
fmt.Printf("foo happened with payload %#v\n", b)
})
Patterns and Inspections
pub := pubsub.New(cnx)
event := pubsub.NewPattern().
String("foo:").
Start().As("id").
String(":bar")
pub.Subscribe(event, function (e pubsub.Event, b []byte) {
// You can alias fields and look them up by their names. Pattern
// events will have their "stars" filled in.
id, _ := e.Find("id").Int()
fmt.Printf("just got foo:%d:bar!\n", id)
})
Index ¶
- type Emitter
- type Event
- type EventBuilder
- func (e EventBuilder) Alternatives(alts string) EventBuilder
- func (e EventBuilder) As(alias string) EventBuilder
- func (e EventBuilder) Int(x int) EventBuilder
- func (e EventBuilder) Name() string
- func (e EventBuilder) Placeholder() EventBuilder
- func (e EventBuilder) Star() EventBuilder
- func (e EventBuilder) String(str string) EventBuilder
- func (e EventBuilder) ToEvent(channel, pattern string) Event
- type EventType
- type Field
- type Listener
- type Pubsub
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Emitter ¶
type Emitter interface {
// Subscribe registers that the provided lister wants to be notified
// of the given Event. If the Listener is already subscribed to the
// event, it will be added again and the listener will be invoked
// multiple times when that event occurs.
Subscribe(e EventBuilder, l Listener)
// Unsubscribe unregisters a listener from an event. If the listener
// is not subscribed to the event, this will be a noop. Note that this
// only unsubscribes *one* listener from the event; if it's subscribed
// multiple times, it will need to unsubscribe multiple times.
Unsubscribe(e EventBuilder, l Listener)
// Errs returns a channel of errors that occur asynchronously on
// the Redis connection.
Errs() <-chan error
// Close frees resources associated with the Emitter.
Close()
}
Emitter is the primary interface to interact with pubsub.
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
An Event is passed down to a Listener's Handle function.
func (Event) Channel ¶
Channel returns a the channel that the event was sent down. For plain events, this is equivalent to event names. For pattern events, this is the fulfilled name of the event.
func (Event) Find ¶
Find looks up a field value by its alias. This is most useful in pattern subscriptions where might use Find to look up a parameterized property. If the alias does not exist, an empty struct will be returned.
func (Event) Get ¶
Get returns the value of a field at index `i` within the event. If the field does not exist, an empty struct will be returned.
type EventBuilder ¶
type EventBuilder struct {
// contains filtered or unexported fields
}
An Event is passed to an Emitter to manage which events a Listener is subscribed to.
func NewEvent ¶
func NewEvent(fields ...interface{}) EventBuilder
NewEvent creates and returns a new event based off the series of fields. This translates to a Redis SUBSCRIBE call.
func NewPattern ¶
func NewPattern(fields ...interface{}) EventBuilder
NewPattern creates and returns a new event pattern off the series of fields. This translates to a Redis PSUBSCRIBE call.
func (EventBuilder) Alternatives ¶
func (e EventBuilder) Alternatives(alts string) EventBuilder
Alternatives creates a field with the alts wrapped in brackets, to match one of them in a Redis pattern, and chains it on to the event.
func (EventBuilder) As ¶
func (e EventBuilder) As(alias string) EventBuilder
As sets the alias of the last field in the event list. You may then call Event.Find(alias) to look up the value of the field in the event.
func (EventBuilder) Int ¶
func (e EventBuilder) Int(x int) EventBuilder
Int creates a Field containing an integer.
func (EventBuilder) Name ¶
func (e EventBuilder) Name() string
Name returns name of the event, formed by a concatenation of all the event fields.
func (EventBuilder) Placeholder ¶
func (e EventBuilder) Placeholder() EventBuilder
Placeholder creates a field containing a `?` for a placeholder in Redis patterns, and chains it on to the event.
func (EventBuilder) Star ¶
func (e EventBuilder) Star() EventBuilder
Star creates a Field containing the Kleene star `*` for pattern subscription, and chains it on to the EventBuilder.
func (EventBuilder) String ¶
func (e EventBuilder) String(str string) EventBuilder
String creates a Field containing a string.
func (EventBuilder) ToEvent ¶
func (e EventBuilder) ToEvent(channel, pattern string) Event
ToEvent converts an EventBuilder into an immutable event which appears to have been send down the provided channel and pattern. This is primarily used internally but may also be useful for unit testing.
type EventType ¶
type EventType int
EventType is used to distinguish between pattern and plain text events.
func (EventType) SubCommand ¶
SubCommand returns the command issued to subscribe to the event in Redis.
func (EventType) UnsubCommand ¶
UnsubCommand returns the command issued o unsubscribe from the event in Redis.
type Field ¶
type Field struct {
// contains filtered or unexported fields
}
Field is a type which is are concatenated into events, listed to over Redis.
type Listener ¶
type Listener interface {
// Handle is invoked when the event occurs, with
// the byte payload it contains.
Handle(e Event, b []byte)
}
The Listener contains a function which, when passed to an Emitter, is invoked when an event occurs. It's invoked with the corresponding subscribed Event and the event's payload.
Note that if a listener is subscribed to multiple overlapping events such as `foo:bar` and `foo:*`, the listener will be called multiple times.
type Pubsub ¶
type Pubsub struct {
// contains filtered or unexported fields
}
Pubsub is an implementation of the Emitter interface using Redis pupsub.
func (*Pubsub) Subscribe ¶
func (p *Pubsub) Subscribe(ev EventBuilder, l Listener)
Subscribe implements Emitter.Subscribe
func (*Pubsub) Unsubscribe ¶
func (p *Pubsub) Unsubscribe(ev EventBuilder, l Listener)
Unsubscribe implements Emitter.Unsubscribe
Source Files