Documentation

Overview

    Package event deals with subscriptions to real-time events.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var ErrMuxClosed = errors.New("event: mux closed")

      ErrMuxClosed is returned when Posting on a closed TypeMux.

      Functions

      This section is empty.

      Types

      type Feed

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

        Feed implements one-to-many subscriptions where the carrier of events is a channel. Values sent to a Feed are delivered to all subscribed channels simultaneously.

        Feeds can only be used with a single type. The type is determined by the first Send or Subscribe operation. Subsequent calls to these methods panic if the type does not match.

        The zero value is ready to use.

        Example (AcknowledgedEvents)
        Output:
        
        0
        0
        0
        1
        1
        1
        2
        2
        2
        

        func (*Feed) Send

        func (f *Feed) Send(value interface{}) (nsent int)

          Send delivers to all subscribed channels simultaneously. It returns the number of subscribers that the value was sent to.

          func (*Feed) Subscribe

          func (f *Feed) Subscribe(channel interface{}) Subscription

            Subscribe adds a channel to the feed. Future sends will be delivered on the channel until the subscription is canceled. All channels added must have the same element type.

            The channel should have ample buffer space to avoid blocking other subscribers. Slow subscribers are not dropped.

            type ResubscribeFunc

            type ResubscribeFunc func(context.Context) (Subscription, error)

              A ResubscribeFunc attempts to establish a subscription.

              type Subscription

              type Subscription interface {
              	Err() <-chan error // returns the error channel
              	Unsubscribe()      // cancels sending of events, closing the error channel
              }

                Subscription represents a stream of events. The carrier of the events is typically a channel, but isn't part of the interface.

                Subscriptions can fail while established. Failures are reported through an error channel. It receives a value if there is an issue with the subscription (e.g. the network connection delivering the events has been closed). Only one value will ever be sent.

                The error channel is closed when the subscription ends successfully (i.e. when the source of events is closed). It is also closed when Unsubscribe is called.

                The Unsubscribe method cancels the sending of events. You must call Unsubscribe in all cases to ensure that resources related to the subscription are released. It can be called any number of times.

                func NewSubscription

                func NewSubscription(producer func(<-chan struct{}) error) Subscription

                  NewSubscription runs a producer function as a subscription in a new goroutine. The channel given to the producer is closed when Unsubscribe is called. If fn returns an error, it is sent on the subscription's error channel.

                  Example
                  Output:
                  
                  0
                  1
                  2
                  3
                  4
                  unsubscribed
                  

                  func Resubscribe

                  func Resubscribe(backoffMax time.Duration, fn ResubscribeFunc) Subscription

                    Resubscribe calls fn repeatedly to keep a subscription established. When the subscription is established, Resubscribe waits for it to fail and calls fn again. This process repeats until Unsubscribe is called or the active subscription ends successfully.

                    Resubscribe applies backoff between calls to fn. The time between calls is adapted based on the error rate, but will never exceed backoffMax.

                    type SubscriptionScope

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

                      SubscriptionScope provides a facility to unsubscribe multiple subscriptions at once.

                      For code that handle more than one subscription, a scope can be used to conveniently unsubscribe all of them with a single call. The example demonstrates a typical use in a larger program.

                      The zero value is ready to use.

                      Example
                      Output:
                      
                      division happened: 2
                      multiplication happened: 12
                      subscriber exited
                      

                      func (*SubscriptionScope) Close

                      func (sc *SubscriptionScope) Close()

                        Close calls Unsubscribe on all tracked subscriptions and prevents further additions to the tracked set. Calls to Track after Close return nil.

                        func (*SubscriptionScope) Count

                        func (sc *SubscriptionScope) Count() int

                          Count returns the number of tracked subscriptions. It is meant to be used for debugging.

                          func (*SubscriptionScope) Track

                            Track starts tracking a subscription. If the scope is closed, Track returns nil. The returned subscription is a wrapper. Unsubscribing the wrapper removes it from the scope.

                            type TypeMux

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

                              A TypeMux dispatches events to registered receivers. Receivers can be registered to handle events of certain type. Any operation called after mux is stopped will return ErrMuxClosed.

                              The zero value is ready to use.

                              Deprecated: use Feed

                              Example
                              Output:
                              
                              Received: event.someEvent{I:5}
                              Received: event.someEvent{I:6}
                              Received: event.otherEvent{S:"whoa"}
                              done
                              

                              func (*TypeMux) Post

                              func (mux *TypeMux) Post(ev interface{}) error

                                Post sends an event to all receivers registered for the given type. It returns ErrMuxClosed if the mux has been stopped.

                                func (*TypeMux) Stop

                                func (mux *TypeMux) Stop()

                                  Stop closes a mux. The mux can no longer be used. Future Post calls will fail with ErrMuxClosed. Stop blocks until all current deliveries have finished.

                                  func (*TypeMux) Subscribe

                                  func (mux *TypeMux) Subscribe(types ...interface{}) *TypeMuxSubscription

                                    Subscribe creates a subscription for events of the given types. The subscription's channel is closed when it is unsubscribed or the mux is closed.

                                    type TypeMuxEvent

                                    type TypeMuxEvent struct {
                                    	Time time.Time
                                    	Data interface{}
                                    }

                                      TypeMuxEvent is a time-tagged notification pushed to subscribers.

                                      type TypeMuxSubscription

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

                                        TypeMuxSubscription is a subscription established through TypeMux.

                                        func (*TypeMuxSubscription) Chan

                                        func (s *TypeMuxSubscription) Chan() <-chan *TypeMuxEvent

                                        func (*TypeMuxSubscription) Closed

                                        func (s *TypeMuxSubscription) Closed() bool

                                        func (*TypeMuxSubscription) Unsubscribe

                                        func (s *TypeMuxSubscription) Unsubscribe()