Documentation

Overview

    Package peerlist provides a utility for managing peer availability with a separate implementation of peer selection from just among available peers. The peer list implements the peer.ChooserList interface and accepts a peerlist.Implementation to provide the implementation-specific concern of, for example, a *roundrobin.List.

    The example is an implementation of peer.ChooserList using a random peer selection strategy, returned by newRandomListImplementation(), implementing peerlist.Implementation.

    type List struct {
    	*peerlist.List
    }
    
    func New(transport peer.Transport) *List {
    	return &List{
    		List: peerlist.New(
    			"random",
    			transport,
    			newRandomListImplementation(),
    		),
    	}
    }
    

    The abstract peer list is designed to take responsibility for concurrently communicating with three parties: the outbound (which sees it as a peer.Chooser), the peer list updater (which see it as a peer.List), and the transport (which sees it as a bank of peer.Subscriber). By taking care of concurrency, the abstract peer list frees the Implementation from the concern of thread safety.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Implementation

    type Implementation interface {
    	transport.Lifecycle
    
    	Add(peer.StatusPeer, peer.Identifier) peer.Subscriber
    	Remove(peer.StatusPeer, peer.Identifier, peer.Subscriber)
    	// Choose must return an available peer under a list read lock, so must
    	// not block.
    	Choose(context.Context, *transport.Request) peer.StatusPeer
    }

      Implementation is a collection of available peers, with its own subscribers for peer status change notifications. The available peer list encapsulates the logic for selecting from among available peers, whereas a ChooserList is responsible for retaining, releasing, and monitoring peer availability. Use "go.uber.org/yarpc/peer/peerlist".List in conjunction with a ListImplementation to produce a "go.uber.org/yarpc/api/peer".List.

      peerlist.List and peerlist.Implementation compose well with sharding schemes the degenerate to returning the only available peer.

      The peerlist.List calls Add, Remove, and Choose under a write lock so the implementation is free to perform mutations on its own data without locks.

      type List

      type List struct {
      	// contains filtered or unexported fields
      }

        List is an abstract peer list, backed by an Implementation to determine which peer to choose among available peers. The abstract list manages available versus unavailable peers, intercepting these notifications from the transport's concrete implementation of peer.Peer with the peer.Subscriber API. The peer list will not choose an unavailable peer, prefering to block until one becomes available.

        The list is a suitable basis for concrete implementations like round-robin.

        func New

        func New(name string, transport peer.Transport, availableChooser Implementation, opts ...ListOption) *List

          New creates a new peer list with an identifier chooser for available peers.

          func (*List) Available

          func (pl *List) Available(p peer.Identifier) bool

            Available returns whether the identifier peer is available for traffic.

            func (*List) Choose

            func (pl *List) Choose(ctx context.Context, req *transport.Request) (peer.Peer, func(error), error)

              Choose selects the next available peer in the peer list

              func (*List) Introspect

              func (pl *List) Introspect() introspection.ChooserStatus

                Introspect returns a ChooserStatus with a summary of the Peers.

                func (*List) IsRunning

                func (pl *List) IsRunning() bool

                  IsRunning returns whether the peer list is running.

                  func (*List) NotifyStatusChanged

                  func (pl *List) NotifyStatusChanged(pid peer.Identifier)

                    NotifyStatusChanged receives status change notifications for peers in the list.

                    func (*List) NumAvailable

                    func (pl *List) NumAvailable() int

                      NumAvailable returns how many peers are available.

                      func (*List) NumUnavailable

                      func (pl *List) NumUnavailable() int

                        NumUnavailable returns how many peers are unavailable.

                        func (*List) NumUninitialized

                        func (pl *List) NumUninitialized() int

                          NumUninitialized returns how many peers are unavailable.

                          func (*List) Peers

                          func (pl *List) Peers() []peer.Peer

                            Peers returns a snapshot of all retained (available and unavailable) peers.

                            func (*List) Start

                            func (pl *List) Start() error

                              Start notifies the List that requests will start coming

                              func (*List) Stop

                              func (pl *List) Stop() error

                                Stop notifies the List that requests will stop coming

                                func (*List) Uninitialized

                                func (pl *List) Uninitialized(p peer.Identifier) bool

                                  Uninitialized returns whether a peer is waiting for the peer list to start.

                                  func (*List) Update

                                  func (pl *List) Update(updates peer.ListUpdates) error

                                    Update applies the additions and removals of peer Identifiers to the list it returns a multi-error result of every failure that happened without circuit breaking due to failures.

                                    type ListOption

                                    type ListOption interface {
                                    	// contains filtered or unexported methods
                                    }

                                      ListOption customizes the behavior of a list.

                                      func Capacity

                                      func Capacity(capacity int) ListOption

                                        Capacity specifies the default capacity of the underlying data structures for this list

                                        Defaults to 10.

                                        func FailFast

                                        func FailFast() ListOption

                                          FailFast indicates that the peer list should not wait for peers to be added, when choosing a peer.

                                          This option is particularly useful for proxies.

                                          func NoShuffle

                                          func NoShuffle() ListOption

                                            NoShuffle disables the default behavior of shuffling peerlist order.

                                            func Seed

                                            func Seed(seed int64) ListOption

                                              Seed specifies the random seed to use for shuffling peers

                                              Defaults to approximately the process start time in nanoseconds.