hashring32

Documentation

Index

• func NewImplementation(opts ...Option) abstractlist.Implementation
• 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 AlternateShardKeyHeader(alternateShardKeyHeader string) Option
  • func DefaultChooseTimeout(timeout time.Duration) Option
  • func Logger(logger *zap.Logger) Option
  • func NumPeersEstimate(n int) Option
  • func NumReplicas(n int) Option
  • func OffsetGeneratorValue(offsetGenerator int) Option
  • func OffsetHeader(offsetHeader string) Option
  • func PeerOverrideHeader(peerOverrideHeader string) Option
  • func ReplicaDelimiter(delimiter string) Option

Functions

func NewImplementation

func NewImplementation(opts ...Option) abstractlist.Implementation

NewImplementation creates a new hashring32 abstractlist.Implementation.

Use this constructor instead of NewList, when wanting to do custom peer connection management.

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"`

	// OffsetGeneratorValue allows clients to generate an offset automatically when using hashring32
	//
	// For example, if this value is set to 4, the offset used by hashring32
	// will be between [0-4].
	//
	// It should be noted that this option will not be used if the option
	// OffsetHeader is being used.
	OffsetGeneratorValue int `config:"offsetGeneratorValue"`

	// 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"`

	// AlternateShardKeyHeader allows clients to pass a header containing the shard
	// identifier for a specific peer to override the destination address for the
	// outgoing request.
	AlternateShardKeyHeader string `config:"alternateShardKeyHeader"`

	ReplicaDelimiter string `config:"replicaDelimiter"`

	// NumReplicas specifies the number of replicas to use for each peer in the ring.
	// Default is 100
	NumReplicas int `config:"numReplicas"`

	// NumPeersEstimate specifies an estimate for the number of identified peers
	// the hashring will contain.
	//
	// This figure and the number of replicas determines the initial capacity of the ring slice.
	// Default is 1500
	NumPeersEstimate int `config:"numPeersEstimate"`

	// 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 peer list.

func AlternateShardKeyHeader

func AlternateShardKeyHeader(alternateShardKeyHeader string) Option

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

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 NumPeersEstimate

func NumPeersEstimate(n int) Option

NumPeersEstimate allows client to specifiy an estimate for the number of identified peers the hashring will contain.

func NumReplicas

func NumReplicas(n int) Option

NumReplicas allos client to specify the number of replicas to use for each peer.

More replicas produces a more even distribution of entities and slower membership updates.

func OffsetGeneratorValue

func OffsetGeneratorValue(offsetGenerator int) Option

OffsetGeneratorValue is the option function that client might give if they want to generate an offset automatically when using hashring32

For example, if this value is set to 4, the offset used by hashring32 will be between [0-4].

It should be noted that this option will not be used if the option OffsetHeader is being used.

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.