From fa7c83166f2d72bccaf67d0c9e4e115b6e1744ca Mon Sep 17 00:00:00 2001 From: Jae Kwon Date: Tue, 23 Dec 2014 19:31:24 -0800 Subject: [PATCH] P2P docs --- p2p/README.md | 100 ++++++++++++++++++++++++++++++++------------- p2p/connection.go | 23 ++++++++++- p2p/listener.go | 7 +--- p2p/netaddress.go | 2 - p2p/peer.go | 2 - p2p/peer_set.go | 10 ++--- p2p/switch.go | 17 ++------ p2p/upnp/README.md | 5 +++ 8 files changed, 105 insertions(+), 61 deletions(-) create mode 100644 p2p/upnp/README.md diff --git a/p2p/README.md b/p2p/README.md index 94419848..941c93ee 100644 --- a/p2p/README.md +++ b/p2p/README.md @@ -1,35 +1,77 @@ -# P2P Module +# `tendermint/p2p` -P2P provides an abstraction around peer-to-peer communication.
-Communication happens via Reactors that react to messages from peers.
-Each Reactor has one or more Channels of communication for each Peer.
-Channels are multiplexed automatically and can be configured.
-A Switch is started upon app start, and handles Peer management.
-A PEXReactor implementation is provided to automate peer discovery.
+`tendermint/p2p` provides an abstraction around peer-to-peer communication.
-## Channels +## Peer/MConnection/Channel -Each peer connection is multiplexed into channels. -The p2p module comes with a channel implementation used for peer -discovery (called PEX, short for "peer exchange"). +Each peer has one `MConnection` (multiplex connection) instance. - - - - - - - - - -
Channel"PEX"
Messages -
    -
  • pexRequestMsg
    • -
  • pexResponseMsg
    • -
-
-
+__multiplex__ *noun* a system or signal involving simultaneous transmission of +several messages along a single channel of communication. -## Resources +Each `MConnection` handles message transmission on multiple abstract communication +`Channel`s. Each channel has a globally unique byte id. +The byte id and the relative priorities of each `Channel` are configured upon +initialization of the connection. -* http://www.upnp-hacks.org/upnp.html +There are two methods for sending messages: +```go +func (m MConnection) Send(chId byte, msg interface{}) bool {} +func (m MConnection) TrySend(chId byte, msg interface{}) bool {} +``` + +`Send(chId, msg)` is a blocking call that waits until `msg` is successfully queued +for the channel with the given id byte `chId`. The message `msg` is serialized +using the `tendermint/binary` submodule's `WriteBinary()` reflection routine. + +`TrySend(chId, msg)` is a nonblocking call that returns false if the channel's +queue is full. + +`Send()` and `TrySend()` are also exposed for each `Peer`. + +## Switch/Reactor + +The `Switch` handles peer connections and exposes an API to receive incoming messages +on `Reactors`. Each `Reactor` is responsible for handling incoming messages of one +or more `Channels`. So while sending outgoing messages is typically performed on the peer, +incoming messages are received on the reactor. + +```go +// Declare a MyReactor reactor that handles messages on MyChannelId. +type MyReactor struct{} + +func (reactor MyReactor) GetChannels() []*ChannelDescriptor { + return []*ChannelDescriptor{ChannelDescriptor{Id:MyChannelId, Priority: 1}} +} + +func (reactor MyReactor) Receive(chId byte, peer *Peer, msgBytes []byte) { + r, n, err := bytes.NewBuffer(msgBytes), new(int64), new(error) + msgString := ReadString(r, n, err) + fmt.Println(msgString) +} + +// Other Reactor methods omitted for brevity +... + +switch := NewSwitch([]Reactor{MyReactor{}}) + +... + +// Send a random message to all outbound connections +for _, peer := range switch.Peers().List() { + if peer.IsOutbound() { + peer.Send(MyChannelId, "Here's a random message") + } +} +``` + +### PexReactor/AddrBook + +A `PEXReactor` reactor implementation is provided to automate peer discovery. + +```go +book := p2p.NewAddrBook(config.AddrBookFile()) +pexReactor := p2p.NewPEXReactor(book) +... +switch := NewSwitch([]Reactor{pexReactor, myReactor, ...}) +``` diff --git a/p2p/connection.go b/p2p/connection.go index ccc16447..607f9120 100644 --- a/p2p/connection.go +++ b/p2p/connection.go @@ -34,8 +34,27 @@ type receiveCbFunc func(chId byte, msgBytes []byte) type errorCbFunc func(interface{}) /* -A MConnection wraps a network connection and handles buffering and multiplexing. -