Documentation

Overview

    Package abstractlist 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 an abstractlist.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 abstractlist.Implementation.

    type List struct {
    	*abstractlist.List
    }
    
    func New(transport peer.Transport) *List {
    	return &List{
    		List: abstractlist.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 {
    	Add(peer.StatusPeer, peer.Identifier) Subscriber
    	Remove(peer.StatusPeer, peer.Identifier, Subscriber)
    	Choose(*transport.Request) peer.StatusPeer
    }

      Implementation is a collection of available peers, with its own subscribers for pending request count change notifications. The abstract list uses the implementation to track peers that can be returned by Choose, as opposed to those that were added but reported unavailable by the underlying transport. Use "go.uber.org/yarpc/peer/abstractlist".List in conjunction with an Implementation to produce a "go.uber.org/yarpc/api/peer".ChooserList.

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

      It should be noted that since the abstractlist.List is using a write lock for Add, Remove and Choose, performances of the abstract.List might be limited for a given implementation. For instance, a tworandomchoices implementation would not need a write lock for the method Choose but only a read lock.

      Choose must return nil immediately if the collection is empty. The abstractlist.List guarantees that peers will only be added if they're absent, and only removed they are present. Choose should not block.

      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.StatusPeer 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.

        This abstract list does not participate in the transport’s pending request count tracking. The list tracks pending request counts for the peers that it chooses, does not inform the transport of these choices, and ignores notifications from the transport about choices other peer lists that share the same peers have made.

        func New

        func New(name string, transport peer.Transport, implementation Implementation, opts ...Option) *List

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

          func (*List) Available

          func (pl *List) Available(pid 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) Name

                  func (pl *List) Name() string

                    Name returns the name of the list.

                    func (*List) NotifyStatusChanged

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

                      NotifyStatusChanged receives status change notifications for peers in the list.

                      This function exists only as is necessary for dispatching connection status changes from tests.

                      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 while the list is running.

                          func (*List) NumUninitialized

                          func (pl *List) NumUninitialized() int

                            NumUninitialized returns how many peers are unavailable because the peer list was stopped or has not yet started.

                            func (*List) Peers

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

                              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) Transport

                                  func (pl *List) Transport() peer.Transport

                                    Transport returns the underlying transport for retaining and releasing peers.

                                    func (*List) Uninitialized

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

                                      Uninitialized returns whether the identifier peer is present but uninitialized.

                                      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.

                                        Updates must be serialized so no peer is removed if it is absent and no peer is added if it is present. Updates should not have overlapping additions and removals, but the list will tollerate this case, but may cause existing connections to close and be replaced.

                                        Update will return errors if its invariants are violated, regardless of whether updates are sent while the list is running. Updates may be interleaved with Start and Stop in any order any number of times.

                                        type Option

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

                                          Option customizes the behavior of a list.

                                          func Capacity

                                          func Capacity(capacity int) Option

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

                                            Defaults to 10.

                                            func DefaultChooseTimeout

                                            func DefaultChooseTimeout(timeout time.Duration) Option

                                              DefaultChooseTimeout specifies the default timeout to add to 'Choose' calls without context deadlines. This prevents long-lived streams from setting calling deadlines.

                                              Defaults to 500ms.

                                              func FailFast

                                              func FailFast() Option

                                                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 Logger

                                                func Logger(logger *zap.Logger) Option

                                                  Logger specifies a logger.

                                                  func NoShuffle

                                                  func NoShuffle() Option

                                                    NoShuffle disables the default behavior of shuffling peer list order.

                                                    func Seed

                                                    func Seed(seed int64) Option

                                                      Seed specifies the random seed to use for shuffling peers

                                                      Defaults to approximately the process start time in nanoseconds.

                                                      type Subscriber

                                                      type Subscriber interface {
                                                      	UpdatePendingRequestCount(int)
                                                      }

                                                        Subscriber is a callback that implementations of peer list data structures must provide.

                                                        The peer list uses the Subscriber to send notifications when a peer’s pending request count changes. A peer list implementation may have a single subscriber or a subscriber for each peer. UpdatePendingRequestCount is thread safe to be called