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 EvtLocalRoutabilityPrivate
• type EvtLocalRoutabilityPublic
• type EvtLocalRoutabilityUnknown
• type EvtPeerIdentificationCompleted
• type EvtPeerIdentificationFailed
• 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{}) error
}

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 EvtLocalRoutabilityPrivate

type EvtLocalRoutabilityPrivate struct{}

EvtLocalRoutabilityPrivate is an event struct to be emitted with the local's node routability changes to PRIVATE (i.e. not routable from the Internet).

This event is usually emitted by the AutoNAT subsystem.

type EvtLocalRoutabilityPublic

type EvtLocalRoutabilityPublic struct{}

EvtLocalRoutabilityPublic is an event struct to be emitted with the local's node routability changes to PUBLIC (i.e. appear to routable from the Internet).

This event is usually emitted by the AutoNAT subsystem.

type EvtLocalRoutabilityUnknown

type EvtLocalRoutabilityUnknown struct{}

EvtLocalRoutabilityUnknown is an event struct to be emitted with the local's node routability changes to UNKNOWN (i.e. we were unable to make a determination about our NAT status with enough confidence).

This event is usually emitted by the AutoNAT subsystem.

type EvtPeerIdentificationCompleted

type EvtPeerIdentificationCompleted struct {
	// Peer is the ID of the peer whose identification succeeded.
	Peer peer.ID
}

EvtPeerIdentificationCompleted is emitted when the initial identification round for a peer is completed.

type EvtPeerIdentificationFailed

type EvtPeerIdentificationFailed struct {
	// Peer is the ID of the peer whose identification failed.
	Peer peer.ID
	// Reason is the reason why identification failed.
	Reason error
}

EvtPeerIdentificationFailed is emitted when the initial identification round for a peer failed.

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.