throttler

Documentation

Overview

Package throttler provides a client-side, local throttler which is used to throttle (and actively pace) writes during the resharding process.

The throttler has two main goals: a) allow resharding data into an existing keyspace by throttling at a fixed

rate

b) ensure that the MySQL replicas do not become overloaded

To support b), the throttler constantly monitors the health of all replicas and reduces the allowed rate if the replication lag is above a certain threshold. TODO(mberlin): Implement b).

Index

• Constants
• Variables
• type Manager
• type MaxRateModule
  • func NewMaxRateModule(maxRate int64) *MaxRateModule
  • func (m *MaxRateModule) MaxRate() int64
  • func (m *MaxRateModule) SetMaxRate(rate int64)
  • func (m *MaxRateModule) Start(rateUpdateChan chan<- struct{})
  • func (m *MaxRateModule) Stop()
• type Module
• type Throttler
  • func NewThrottler(name, unit string, threadCount int, maxRate int64, maxReplicationLag int64) (*Throttler, error)
  • func (t *Throttler) Close()
  • func (t *Throttler) MaxRate() int64
  • func (t *Throttler) SetMaxRate(rate int64)
  • func (t *Throttler) ThreadFinished(threadID int)
  • func (t *Throttler) Throttle(threadID int) time.Duration

Constants

const (
	// NotThrottled will be returned by Throttle() if the application is currently
	// not throttled.
	NotThrottled time.Duration = 0

	// ZeroRateNoProgess can be used to set maxRate to 0. In this case, the
	// throttler won't let any requests through until the rate is increased again.
	ZeroRateNoProgess = 0

	// MaxRateModuleDisabled can be set in NewThrottler() to disable throttling
	// by a fixed rate.
	MaxRateModuleDisabled = math.MaxInt64

	// InvalidMaxRate is a constant which will fail in a NewThrottler() call.
	// It should be used when returning maxRate in an error case.
	InvalidMaxRate = -1

	// ReplicationLagModuleDisabled can be set in NewThrottler() to disable
	// throttling based on the MySQL replication lag.
	ReplicationLagModuleDisabled = math.MaxInt64

	// InvalidMaxReplicationLag is a constant which will fail in a NewThrottler()
	// call. It should be used when returning maxReplicationlag in an error case.
	InvalidMaxReplicationLag = -1
)

Variables

var GlobalManager = newManager()

GlobalManager is the per-process manager which manages all active throttlers.

Types

type Manager

type Manager interface {
	// MaxRates returns the max rate of all known throttlers.
	MaxRates() map[string]int64

	// SetMaxRate sets the max rate on all known throttlers.
	SetMaxRate(rate int64) []string
}

Manager defines the public interface of the throttler manager. It is used for example by the different RPC implementations.

type MaxRateModule

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

MaxRateModule allows to set and retrieve a maximum rate limit. It implements the Module interface.

func NewMaxRateModule

func NewMaxRateModule(maxRate int64) *MaxRateModule

NewMaxRateModule will create a new module instance and set the initial rate limit to maxRate.

func (*MaxRateModule) MaxRate

func (m *MaxRateModule) MaxRate() int64

MaxRate returns the current maximum allowed rate.

func (*MaxRateModule) SetMaxRate

func (m *MaxRateModule) SetMaxRate(rate int64)

SetMaxRate sets the current max rate and notifies the throttler about the rate update.

func (*MaxRateModule) Start

func (m *MaxRateModule) Start(rateUpdateChan chan<- struct{})

Start currently does nothing. It implements the Module interface.

func (*MaxRateModule) Stop

func (m *MaxRateModule) Stop()

Stop currently does nothing. It implements the Module interface.

type Module

type Module interface {
	// Start can be implemented to e.g. start own Go routines and initialize the
	// module.
	// rateUpdateChan must be used to notify the Throttler when the module's
	// maximum rate limit has changed and a subsequent MaxRate() call would return
	// a different value.
	Start(rateUpdateChan chan<- struct{})
	// Stop will free all resources and be called by Throttler.Close().
	Stop()

	// MaxRate returns the maximum allowed rate determined by the module.
	MaxRate() int64
}

Module specifies the API for a Decision Module which can tell the throttler to dynamically increase or decrease the current rate limit.

type Throttler

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

Throttler provides a client-side, thread-aware throttler. See the package doc for more information.

Calls of Throttle() and ThreadFinished() take threadID as parameter which is in the range [0, threadCount). (threadCount is set in NewThrottler().) NOTE: Trottle() and ThreadFinished() assume that *per thread* calls to them

are serialized and must not happen concurrently.

func NewThrottler

func NewThrottler(name, unit string, threadCount int, maxRate int64, maxReplicationLag int64) (*Throttler, error)

NewThrottler creates a new Throttler instance. Use the constants MaxRateModuleDisabled or ReplicationLagModuleDisabled if you want to disable parts of its functionality. maxRate will be distributed across all threadCount threads and must be >= threadCount. If it's lower, it will be automatically set to threadCount. maxRate can also be set to 0 which will effectively pause the user and constantly block until the rate has been increased again. unit refers to the type of entity you want to throttle e.g. "queries" or "transactions". name describes the Throttler instance and will be used by the webinterface.

func (*Throttler) Close

func (t *Throttler) Close()

Close stops all modules and frees all resources. When Close() returned, the Throttler object must not be used anymore.

func (*Throttler) MaxRate

func (t *Throttler) MaxRate() int64

MaxRate returns the current rate of the MaxRateModule.

func (*Throttler) SetMaxRate

func (t *Throttler) SetMaxRate(rate int64)

SetMaxRate updates the rate of the MaxRateModule.

func (*Throttler) ThreadFinished

func (t *Throttler) ThreadFinished(threadID int)

ThreadFinished marks threadID as finished and redistributes the thread's rate allotment across the other threads. After ThreadFinished() is called, Throttle() must not be called anymore.

func (*Throttler) Throttle

func (t *Throttler) Throttle(threadID int) time.Duration

Throttle returns a backoff duration which specifies for how long "threadId" should wait before it issues the next request. If the duration is zero, the thread is not throttled. If the duration is not zero, the thread must call Throttle() again after the backoff duration elapsed. The maximum value for the returned backoff is 1 second since the throttler internally operates on a per-second basis.