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
• type MaxRateModule
  • func (m *MaxRateModule) MaxRate() int64
  • func (m *MaxRateModule) Start(rateUpdateChan chan<- struct{})
  • func (m *MaxRateModule) Stop()
• type Module
  • func NewMaxRateModule(maxRate int64) Module
• type Throttler
  • func NewThrottler(name, unit string, threadCount int, maxRate int64, maxReplicationLag int64) (*Throttler, error)
  • func (t *Throttler) Close()
  • 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
)

Types

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 (*MaxRateModule) MaxRate

func (m *MaxRateModule) MaxRate() int64

MaxRate returns the current maximum allowed rate.

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.

func NewMaxRateModule

func NewMaxRateModule(maxRate int64) Module

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

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