event

Documentation

Overview

Package event contains the abstractions for a local event bus, along with the standard events that libp2p subsystems may emit.

Source code is arranged as follows:

• doc.go: this file.
• bus.go: abstractions for the event bus.
• rest: event structs, sensibly categorised in files by entity, and following this naming convention: Evt[Entity (noun)][Event (verb past tense / gerund)] The past tense is used to convey that something happened, whereas the gerund form of the verb (-ing) expresses that a process is in progress. Examples: EvtConnEstablishing, EvtConnEstablished.

Index

• type Bus
• type CancelFunc
• type Emitter
• type EmitterOpt
• type EvtLocalProtocolsUpdated
• type EvtPeerProtocolsUpdated
• type Subscription
• type SubscriptionOpt

Types

type Bus

type Bus interface {
	// Subscribe creates a new Subscription.
	//
	// eventType can be either a pointer to a single event type, or a slice of pointers to
	// subscribe to multiple event types at once, under a single subscription (and channel).
	//
	// Failing to drain the channel may cause publishers to block.
	//
	// Simple example
	//
	//  sub, err := eventbus.Subscribe(new(EventType))
	//  defer sub.Close()
	//  for e := range sub.Out() {
	//    event := e.(EventType) // guaranteed safe
	//    [...]
	//  }
	//
	// Multi-type example
	//
	//  sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
	//  defer sub.Close()
	//  for e := range sub.Out() {
	//    select e.(type):
	//      case EventA:
	//        [...]
	//      case EventB:
	//        [...]
	//    }
	//  }
	Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)

	// Emitter creates a new event emitter.
	//
	// eventType accepts typed nil pointers, and uses the type information for wiring purposes.
	//
	// Example:
	//  em, err := eventbus.Emitter(new(EventT))
	//  defer em.Close() // MUST call this after being done with the emitter
	//  em.Emit(EventT{})
	Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)
}

Bus is an interface for a type-based event delivery system.

type CancelFunc

type CancelFunc = func()

CancelFunc closes a subscriber.

type Emitter

type Emitter interface {
	io.Closer

	// Emit emits an event onto the eventbus. If any channel subscribed to the topic is blocked,
	// calls to Emit will block.
	//
	// Calling this function with wrong event type will cause a panic.
	Emit(evt interface{})
}

Emitter represents an actor that emits events onto the eventbus.

type EmitterOpt

type EmitterOpt = func(interface{}) error

EmitterOpt represents an emitter option. Use the options exposed by the implementation of choice.

type EvtLocalProtocolsUpdated

type EvtLocalProtocolsUpdated struct {
	// Added enumerates the protocols that were added locally.
	Added []protocol.ID
	// Removed enumerates the protocols that were removed locally.
	Removed []protocol.ID
}

EvtLocalProtocolsUpdated should be emitted when stream handlers are attached or detached from the local host. For handlers attached with a matcher predicate (host.SetStreamHandlerMatch()), only the protocol ID will be included in this event.

type EvtPeerProtocolsUpdated

type EvtPeerProtocolsUpdated struct {
	// Peer is the peer whose protocols were updated.
	Peer peer.ID
	// Added enumerates the protocols that were added by this peer.
	Added []protocol.ID
	// Removed enumerates the protocols that were removed by this peer.
	Removed []protocol.ID
}

EvtPeerProtocolsUpdated should be emitted when a peer we're connected to adds or removes protocols from their stack.

type Subscription

type Subscription interface {
	io.Closer

	// Out returns the channel from which to consume events.
	Out() <-chan interface{}
}

Subscription represents a subscription to one or multiple event types.

type SubscriptionOpt

type SubscriptionOpt = func(interface{}) error

SubscriptionOpt represents a subscriber option. Use the options exposed by the implementation of choice.