go-libp2p-core: github.com/libp2p/go-libp2p-core/event Index | Files

package event

import "github.com/libp2p/go-libp2p-core/event"

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

Package Files

addrs.go bus.go doc.go identify.go network.go protocol.go reachability.go

type AddrAction Uses

type AddrAction int

AddrAction represents an action taken on one of a Host's listen addresses. It is used to add context to address change events in EvtLocalAddressesUpdated.

const (
    // Unknown means that the event producer was unable to determine why the address
    // is in the current state.
    Unknown AddrAction = iota

    // Added means that the address is new and was not present prior to the event.
    Added

    // Maintained means that the address was not altered between the current and
    // previous states.
    Maintained

    // Removed means that the address was removed from the Host.
    Removed
)

type Bus Uses

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 Uses

type CancelFunc = func()

CancelFunc closes a subscriber.

type Emitter Uses

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 Uses

type EmitterOpt = func(interface{}) error

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

type EvtLocalAddressesUpdated Uses

type EvtLocalAddressesUpdated struct {

    // Diffs indicates whether this event contains a diff of the Host's previous
    // address set.
    Diffs bool

    // Current contains all current listen addresses for the Host.
    // If Diffs == true, the Action field of each UpdatedAddress will tell
    // you whether an address was Added, or was Maintained from the previous
    // state.
    Current []UpdatedAddress

    // Removed contains addresses that were removed from the Host.
    // This field is only set when Diffs == true.
    Removed []UpdatedAddress

    // SignedPeerRecord contains our own updated peer.PeerRecord, listing the addresses enumerated in Current.
    // wrapped in a record.Envelope and signed by the Host's private key.
    SignedPeerRecord record.Envelope
}

EvtLocalAddressesUpdated should be emitted when the set of listen addresses for the local host changes. This may happen for a number of reasons. For example, we may have opened a new relay connection, established a new NAT mapping via UPnP, or been informed of our observed address by another peer.

EvtLocalAddressesUpdated contains a snapshot of the current listen addresses, and may also contain a diff between the current state and the previous state. If the event producer is capable of creating a diff, the Diffs field will be true, and event consumers can inspect the Action field of each UpdatedAddress to see how each address was modified.

For example, the Action will tell you whether an address in the Current list was Added by the event producer, or was Maintained without changes. Addresses that were removed from the Host will have the AddrAction of Removed, and will be in the Removed list.

If the event producer is not capable or producing diffs, the Diffs field will be false, the Removed list will always be empty, and the Action for each UpdatedAddress in the Current list will be Unknown.

In addition to the above, EvtLocalAddressesUpdated also contains the updated peer.PeerRecord for the Current set of listen addresses, wrapped in a record.Envelope and signed by the Host's private key. This record can be shared with other peers to inform them of what we believe are our diallable addresses a secure and authenticated way.

type EvtLocalProtocolsUpdated Uses

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 EvtLocalReachabilityChanged Uses

type EvtLocalReachabilityChanged struct {
    Reachability network.Reachability
}

EvtLocalReachabilityChanged is an event struct to be emitted when the local's node reachability changes state.

This event is usually emitted by the AutoNAT subsystem.

type EvtPeerConnectednessChanged Uses

type EvtPeerConnectednessChanged struct {
    // Peer is the remote peer who's connectedness has changed.
    Peer peer.ID
    // Connectedness is the new connectedness state.
    Connectedness network.Connectedness
}

EvtPeerConnectednessChanged should be emitted every time the "connectedness" to a given peer changes. Specifically, this event is emitted in the following cases:

* Connectedness = Connected: Every time we transition from having no

connections to a peer to having at least one connection to the peer.

* Connectedness = NotConnected: Every time we transition from having at least

one connection to a peer to having no connections to the peer.

Additional connectedness states may be added in the future. This list should not be considered exhaustive.

Take note:

* It's possible to have _multiple_ connections to a given peer.
* Both libp2p and networks are asynchronous.

This means that all of the following situations are possible:

A connection is cut and is re-established:

* Peer A observes a transition from Connected -> NotConnected -> Connected
* Peer B observes a transition from Connected -> NotConnected -> Connected

Explanation: Both peers observe the connection die. This is the "nice" case.

A connection is cut and is re-established.

* Peer A observes a transition from Connected -> NotConnected -> Connected.
* Peer B observes no transition.

Explanation: Peer A re-establishes the dead connection. Peer B observes the new connection form before it observes the old connection die.

A connection is cut:

* Peer A observes no transition.
* Peer B observes no transition.

Explanation: There were two connections and one was cut. This connection might have been in active use but neither peer will observe a change in "connectedness". Peers should always make sure to re-try network requests.

type EvtPeerIdentificationCompleted Uses

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 Uses

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 Uses

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 Uses

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 Uses

type SubscriptionOpt = func(interface{}) error

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

type UpdatedAddress Uses

type UpdatedAddress struct {
    // Address contains the address that was updated.
    Address ma.Multiaddr

    // Action indicates what action was taken on the address during the
    // event. May be Unknown if the event producer cannot produce diffs.
    Action AddrAction
}

UpdatedAddress is used in the EvtLocalAddressesUpdated event to convey address change information.

Package event imports 6 packages (graph) and is imported by 19 packages. Updated 2020-04-01. Refresh now. Tools for package owners.