hashring32

Documentation

Index

• func Spec(logger *zap.Logger, meter *metrics.Scope) yarpcconfig.PeerListSpec
• type Config
• type List
  • func New(transport peer.Transport, hashFunc hashring32.HashFunc32, opts ...Option) *List
  • func (l *List) Choose(ctx context.Context, req *transport.Request) (peer peer.Peer, onFinish func(error), err error)
  • func (l *List) Introspect() introspection.ChooserStatus
  • func (l *List) IsRunning() bool
  • func (l *List) NotifyStatusChanged(pid peer.Identifier)
  • func (l *List) Peers() []peer.StatusPeer
  • func (l *List) Start() error
  • func (l *List) Stop() error
  • func (l *List) Update(updates peer.ListUpdates) error
• type Option
  • func DefaultChooseTimeout(timeout time.Duration) Option
  • func Logger(logger *zap.Logger) Option
  • func OffsetHeader(offsetHeader string) Option
  • func PeerOverrideHeader(peerOverrideHeader string) Option
  • func ReplicaDelimiter(delimiter string) Option

Functions

func Spec

func Spec(logger *zap.Logger, meter *metrics.Scope) yarpcconfig.PeerListSpec

Spec returns a configuration specification for the hashed peer list implementation, making it possible to select peer based on a specified hashing function.

Types

type Config

type Config struct {
	// OffsetHeader allows clients to pass in a header to adjust to offset value
	// in the Choose function.
	OffsetHeader string `config:"offsetHeader"`

	// PeerOverrideHeader allows clients to pass a header containing the shard
	// identifier for a specific peer to override the destination address for
	// the outgoing request.
	//
	// For example, if the peer list uses addresses to identify peers,
	// the hash ring will have retained a peer for every known address.
	// Specifying an address like "127.0.0.1" in the route override header will
	// deflect the request to that exact peer.
	// If that peer is not available, the request will continue on to the peer
	// implied by the shard key.
	PeerOverrideHeader string `config:"peerOverrideHeader"`

	ReplicaDelimiter string `config:"replicaDelimiter"`

	// DefaultChooseTimeout specifies the deadline to add to Choose calls if not
	// present. This enables calls without deadlines, ie streaming, to choose
	// peers without waiting indefinitely.
	DefaultChooseTimeout *time.Duration `config:"defaultChooseTimeout"`
}

Config is the configuration object for hashring32yarpc

type List

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

List is a PeerList which chooses peers based on a hashing function.

func New

func New(transport peer.Transport, hashFunc hashring32.HashFunc32, opts ...Option) *List

New creates a new hashring32 peer list.

func (*List) Choose

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

Choose returns a peer, suitable for sending a request.

The peer is not guaranteed to be connected and available, but the peer list makes every attempt to ensure this and minimize the probability that a chosen peer will fail to carry a request.

func (*List) Introspect

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

Introspect reveals information about the list to the internal YARPC introspection system.

func (*List) IsRunning

func (l *List) IsRunning() bool

IsRunning returns whether the list has started and not yet stopped.

func (*List) NotifyStatusChanged

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

NotifyStatusChanged forwards a status change notification to an individual peer in the list.

This satisfies the peer.Subscriber interface and should only be used to send notifications in tests. The list's RetainPeer and ReleasePeer methods deal with an individual peer.Subscriber instance for each peer in the list, avoiding a map lookup.

func (*List) Peers

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

Peers produces a slice of all retained peers.

func (*List) Start

func (l *List) Start() error

Start causes the peer list to start.

Starting will retain all peers that have been added but not removed the first time it is called.

Start may be called any number of times and in any order in relation to Stop but will only cause the list to start the first time, and only if it has not already been stopped.

func (*List) Stop

func (l *List) Stop() error

Stop causes the peer list to stop.

Stopping will release all retained peers to the underlying transport.

Stop may be called any number of times and in order in relation to Start but will only cause the list to stop the first time, and only if it has previously been started.

func (*List) Update

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

Update may add and remove logical peers in the list.

The peer list uses a transport to obtain a physical peer for each logical peer. The transport is responsible for informing the peer list whether the peer is available or unavailable, but cannot guarantee that the peer will still be available after it is chosen.

type Option

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

Option customizes the behavior of hashring32 implementation.

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 Logger

func Logger(logger *zap.Logger) Option

Logger threads a logger into the hash ring constructor.

func OffsetHeader

func OffsetHeader(offsetHeader string) Option

OffsetHeader is the option function that allows a user to pass a header key to the hashring to adjust to N value in the hashring choose function.

func PeerOverrideHeader

func PeerOverrideHeader(peerOverrideHeader string) Option

PeerOverrideHeader allows clients to pass a header containing the shard identifier for a specific peer to override the destination address for the outgoing request.

For example, if the peer list uses addresses to identify peers, the hash ring will have retained a peer for every known address. Specifying an address like "127.0.0.1" in the route override header will deflect the request to that exact peer. If that peer is not available, the request will continue on to the peer implied by the shard key.

func ReplicaDelimiter

func ReplicaDelimiter(delimiter string) Option

ReplicaDelimiter overrides the the delimiter the hash ring uses to construct replica identifiers from peer identifiers and replica numbers.

The default delimiter is an empty string.