peerbook

Documentation

Overview

Package peerbook implements a continuously updated eventually consistent phonebook of peers.

Index

• type LamportTime
• type PeerBook
  • func New(ctx context.Context, nodeName string, controlPort int, tags map[string]string) (*PeerBook, error)
  • func (p *PeerBook) Broadcast(name string, payload []byte, coalesce bool) error
  • func (p *PeerBook) GetPeer(key string) (peerName string, addr net.IP, tags map[string]string)
  • func (p *PeerBook) GetPeerObject(key string) (interface{}, error)
  • func (p *PeerBook) Join(addrs []string) (n int, err error)
  • func (p *PeerBook) PeerCount() int
  • func (p *PeerBook) Port() int
  • func (p *PeerBook) RefreshPeerObject(key string) (interface{}, error)
  • func (p *PeerBook) SetTags(tags map[string]string) error
  • func (p *PeerBook) WaitForShutdown()

Types

type LamportTime

type LamportTime = serf.LamportTime

LamportTime is a monotonic clock that can be used to order broadcast messages.

type PeerBook

type PeerBook struct {

	// BroadcastHandler is called to handle each broadcast message sent to
	// peers. It should complete quickly to prevent missing future messages.
	BroadcastHandler func(ltime LamportTime, name string, payload []byte, coalesce bool)

	// NewPeerObject is a function that returns an object corresponding to the
	// peer whose name, address and tags are provided. PeerBook will cache these
	// objects and provide them via GetPeerObject().
	//
	// Peer objects are usually used to cache client objects or connection
	// objects used to contact peers.
	NewPeerObject func(name string, addr net.IP, tags map[string]string) (interface{}, error)

	// DestroyPeerObject is called when a peer object is no longer useful (e.g.
	// when the peer disappears).
	//
	// DestroyPeerObject should complete quickly. Ohterwise, PeerBook may fail
	// to keep up with changes in membership among peers.
	//
	// If DestroyPeerObject is nil, then the peer object is simply dropped. If
	// PeerBook held the only reference to the peer object, then the object will
	// be deallocated.
	DestroyPeerObject func(key string, obj interface{})
	// contains filtered or unexported fields
}

PeerBook is an instance of a peer book.

Exported fields shold be set before calling Start(), and should not be changed thereafter.

func New

func New(ctx context.Context, nodeName string, controlPort int, tags map[string]string) (*PeerBook, error)

New returns a new PeerBook.

Cancelling the provided context terminates the peer.

func (*PeerBook) Broadcast

func (p *PeerBook) Broadcast(name string, payload []byte, coalesce bool) error

Broadcast broadcasts a small message to all peers in the group. Broadcasts can be used to keep peers up-to-date. Broadcasts are delivered on an eventually consistent basis.

func (*PeerBook) GetPeer

func (p *PeerBook) GetPeer(key string) (peerName string, addr net.IP, tags map[string]string)

GetPeer returns the peerName, ip and tags of the peer owning the provided key.

func (*PeerBook) GetPeerObject

func (p *PeerBook) GetPeerObject(key string) (interface{}, error)

GetPeerObject returns an object associated with the peer owning the provided key. Objects are created from the NewPeerObject function member in the PeerBook.

Peer objects are typically used for client connections.

func (*PeerBook) Join

func (p *PeerBook) Join(addrs []string) (n int, err error)

Join joins peers at the addresses in addrs.

Join must be used to bootstrap a new PeerBook by introducing it to at least one other PeerBook in a group of peers. This is usually done out of band (e.g. manually or by querying cloud infrastructure to get the local IPs of other instances in a group or tasks in a job).

Start must be called on this peer before calling Join.

func (*PeerBook) PeerCount

func (p *PeerBook) PeerCount() int

PeerCount returns the number of alive peers.

func (*PeerBook) Port

func (p *PeerBook) Port() int

Port returns the port the PeerBook is using for control traffic.

func (*PeerBook) RefreshPeerObject

func (p *PeerBook) RefreshPeerObject(key string) (interface{}, error)

RefreshPeerObject returns a new peer object associated with the peer. Any previous peer object is dropped and destroyed (if DestroyPeerObject is set).

RefreshPeerObject should only be used if an older per object returned by GetPeerObject is found to be invalid in some way (e.g. if a client handle has timed out or the connection has produced an error).

func (*PeerBook) SetTags

func (p *PeerBook) SetTags(tags map[string]string) error

SetTags updates the tags associated with the current peer. The provided tags replace any previously set tags for the current peer. The new tags will be distributed to other peers on an eventually consistent basis.

Tags are usually used to advertise information about services a peer provides to other peers, e.g. the port at which an RPC server can be reached.

func (*PeerBook) WaitForShutdown

func (p *PeerBook) WaitForShutdown()

WaitForShutdown blocks until all shutdown tasks are completed, including the peer leaving the peer group. Shutdown is initiated by cancelling the context passed to Start.

WaitForShutdown can be used to ensure a peer has released its resources (e.g. listening ports) before a new peer is created. This can be used for stateful restart or in tests.