Documentation
¶
Overview ¶
Package settings provides a central registry of runtime editable settings and accompanying helper functions for retreiving their current values.
Settings values are stored in the system.settings table (which is gossiped). A gossip-driven worker updates this package's cached value when the table changes (see the `RefreshSettings“ worker in the `sql` package).
The package's cache is global -- while all the usual drawbacks of mutable global state obviously apply, it is needed to make the package's functionality available to a wide variety of callsites, that may or may not have a *Server or similar available to plumb though.
To add a new setting, call one of the `Register` methods in `registry.go` and save the accessor created by the register function in the package where the setting is to be used. For example, to add an "enterprise" flag, adding into license_check.go:
var enterpriseEnabled = settings.RegisterBoolSetting(
"enterprise.enabled", "some doc for the setting", false,
)
Then use with `if enterpriseEnabled.Get() ...`
Settings should always be defined with "safe" default values -- until a node receives values via gossip, or even after that, if it cannot read them for some reason, it will use the default values, so define defaults that "fail safe".
In cases where the "safe" default doesn't actually match the desired default, like respecting an opt-*out* setting, we can default to `false` (opted out) and then use a migration to write an explicit `true`: in practice you'd still expect to read `true` unless a preference is expressed, but in the rare cases where you read a default, you don't risk ignoring an expressed opt-out.
Index ¶
- func EncodeBool(b bool) string
- func EncodeDuration(d time.Duration) string
- func EncodeFloat(f float64) string
- func EncodeInt(i int64) string
- func Freeze()
- func Hide(key string)
- func Keys() (res []string)
- func TestingSetBool(s **BoolSetting, v bool) func()
- func TestingSetByteSize(s **ByteSizeSetting, v int64) func()
- func TestingSetDuration(s **DurationSetting, v time.Duration) func()
- func TestingSetEnum(s **EnumSetting, i int64) func()
- func TestingSetFloat(s **FloatSetting, v float64) func()
- func TestingSetInt(s **IntSetting, v int64) func()
- func TestingSetString(s **StringSetting, v string) func()
- type BoolSetting
- type ByteSizeSetting
- type DurationSetting
- func RegisterDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting
- func RegisterPositiveDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting
- func RegisterValidatedDurationSetting(key, desc string, defaultValue time.Duration, ...) *DurationSetting
- func TestingDuration(v time.Duration) *DurationSetting
- type EnumSetting
- type FloatSetting
- type IntSetting
- type Setting
- type StringSetting
- type Updater
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeBool ¶
EncodeBool encodes a bool in the format parseRaw expects.
func EncodeDuration ¶
EncodeDuration encodes a duration in the format parseRaw expects.
func EncodeFloat ¶
EncodeFloat encodes a bool in the format parseRaw expects.
func Freeze ¶
func Freeze()
Freeze ensures that no new settings can be defined after the gossip worker has started. See settingsworker.go.
func Hide ¶
func Hide(key string)
Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.
func TestingSetBool ¶
func TestingSetBool(s **BoolSetting, v bool) func()
TestingSetBool returns a mock, unregistered bool setting for testing. It takes a pointer to a BoolSetting reference, swapping in the mock setting. It returns a cleanup function that swaps back the original setting. This function should not be used by tests that run in parallel, as it could result in race detector failures, as well as if the cleanup functions are called out of order. The original Setting remains registered for gossip-driven updates which become visible when it is restored.
func TestingSetByteSize ¶
func TestingSetByteSize(s **ByteSizeSetting, v int64) func()
TestingSetByteSize returns a mock bytesize setting for testing. See TestingSetBool for more details.
func TestingSetDuration ¶
func TestingSetDuration(s **DurationSetting, v time.Duration) func()
TestingSetDuration returns a mock, unregistered string setting for testing. See TestingSetBool for more details.
func TestingSetEnum ¶
func TestingSetEnum(s **EnumSetting, i int64) func()
TestingSetEnum returns a mock, unregistered enum setting for testing. See TestingSetBool for more details.
func TestingSetFloat ¶
func TestingSetFloat(s **FloatSetting, v float64) func()
TestingSetFloat returns a mock, unregistered float setting for testing. See TestingSetBool for more details.
func TestingSetInt ¶
func TestingSetInt(s **IntSetting, v int64) func()
TestingSetInt returns a mock, unregistered int setting for testing. See TestingSetBool for more details.
func TestingSetString ¶
func TestingSetString(s **StringSetting, v string) func()
TestingSetString returns a mock, unregistered string setting for testing. See TestingSetBool for more details.
Types ¶
type BoolSetting ¶
type BoolSetting struct {
// contains filtered or unexported fields
}
BoolSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bool" is updated.
func RegisterBoolSetting ¶
func RegisterBoolSetting(key, desc string, defaultValue bool) *BoolSetting
RegisterBoolSetting defines a new setting with type bool.
func (*BoolSetting) Get ¶
func (b *BoolSetting) Get() bool
Get retrieves the bool value in the setting.
func (*BoolSetting) String ¶
func (b *BoolSetting) String() string
func (*BoolSetting) Typ ¶
func (*BoolSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
type ByteSizeSetting ¶
type ByteSizeSetting struct {
IntSetting
}
ByteSizeSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bytesize" is updated.
func RegisterByteSizeSetting ¶
func RegisterByteSizeSetting(key, desc string, defaultValue int64) *ByteSizeSetting
RegisterByteSizeSetting defines a new setting with type bytesize.
func RegisterValidatedByteSizeSetting ¶
func RegisterValidatedByteSizeSetting( key, desc string, defaultValue int64, validateFn func(int64) error, ) *ByteSizeSetting
RegisterValidatedByteSizeSetting defines a new setting with type bytesize with a validation function.
func (*ByteSizeSetting) String ¶
func (b *ByteSizeSetting) String() string
func (*ByteSizeSetting) Typ ¶
func (*ByteSizeSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
type DurationSetting ¶
type DurationSetting struct {
// contains filtered or unexported fields
}
DurationSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "duration" is updated.
func RegisterDurationSetting ¶
func RegisterDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting
RegisterDurationSetting defines a new setting with type duration.
func RegisterPositiveDurationSetting ¶
func RegisterPositiveDurationSetting( key, desc string, defaultValue time.Duration, ) *DurationSetting
RegisterPositiveDurationSetting defines a new setting with type duration.
func RegisterValidatedDurationSetting ¶
func RegisterValidatedDurationSetting( key, desc string, defaultValue time.Duration, validateFn func(time.Duration) error, ) *DurationSetting
RegisterValidatedDurationSetting defines a new setting with type duration.
func TestingDuration ¶
func TestingDuration(v time.Duration) *DurationSetting
TestingDuration returns a one off, unregistered duration setting for test use only.
func (*DurationSetting) Get ¶
func (d *DurationSetting) Get() time.Duration
Get retrieves the duration value in the setting.
func (*DurationSetting) String ¶
func (d *DurationSetting) String() string
func (*DurationSetting) Typ ¶
func (*DurationSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
type EnumSetting ¶
type EnumSetting struct {
IntSetting
// contains filtered or unexported fields
}
EnumSetting is a StringSetting that restricts the values to be one of the `enumValues`
func RegisterEnumSetting ¶
func RegisterEnumSetting( key, desc string, defaultValue string, enumValues map[int64]string, ) *EnumSetting
RegisterEnumSetting defines a new setting with type int.
func (*EnumSetting) ParseEnum ¶
func (e *EnumSetting) ParseEnum(raw string) (int64, bool)
ParseEnum returns the enum value, and a boolean that indicates if it was parseable.
func (*EnumSetting) Typ ¶
func (e *EnumSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
type FloatSetting ¶
type FloatSetting struct {
// contains filtered or unexported fields
}
FloatSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "float" is updated.
func RegisterFloatSetting ¶
func RegisterFloatSetting(key, desc string, defaultValue float64) *FloatSetting
RegisterFloatSetting defines a new setting with type float.
func RegisterValidatedFloatSetting ¶
func RegisterValidatedFloatSetting( key, desc string, defaultValue float64, validateFn func(float64) error, ) *FloatSetting
RegisterValidatedFloatSetting defines a new setting with type float.
func (*FloatSetting) Get ¶
func (f *FloatSetting) Get() float64
Get retrieves the float value in the setting.
func (*FloatSetting) String ¶
func (f *FloatSetting) String() string
func (*FloatSetting) Typ ¶
func (*FloatSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
func (*FloatSetting) Validate ¶
func (f *FloatSetting) Validate(v float64) error
Validate that a value conforms with the validation function.
type IntSetting ¶
type IntSetting struct {
// contains filtered or unexported fields
}
IntSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "int" is updated.
func RegisterIntSetting ¶
func RegisterIntSetting(key, desc string, defaultValue int64) *IntSetting
RegisterIntSetting defines a new setting with type int.
func RegisterValidatedIntSetting ¶
func RegisterValidatedIntSetting( key, desc string, defaultValue int64, validateFn func(int64) error, ) *IntSetting
RegisterValidatedIntSetting defines a new setting with type int with a validation function.
func (*IntSetting) Get ¶
func (i *IntSetting) Get() int64
Get retrieves the int value in the setting.
func (*IntSetting) String ¶
func (i *IntSetting) String() string
func (*IntSetting) Typ ¶
func (*IntSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
func (*IntSetting) Validate ¶
func (i *IntSetting) Validate(v int64) error
Validate that a value conforms with the validation function.
type Setting ¶
type Setting interface {
// Typ returns the short (1 char) string denoting the type of setting.
Typ() string
String() string
// contains filtered or unexported methods
}
Setting implementions wrap a val with atomic access.
type StringSetting ¶
type StringSetting struct {
// contains filtered or unexported fields
}
StringSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "string" is updated.
func RegisterStringSetting ¶
func RegisterStringSetting(key, desc string, defaultValue string) *StringSetting
RegisterStringSetting defines a new setting with type string.
func RegisterValidatedStringSetting ¶
func RegisterValidatedStringSetting( key, desc string, defaultValue string, validateFn func(string) error, ) *StringSetting
RegisterValidatedStringSetting defines a new setting with type string with a validation function.
func (*StringSetting) Get ¶
func (s *StringSetting) Get() string
Get retrieves the string value in the setting.
func (*StringSetting) String ¶
func (s *StringSetting) String() string
func (*StringSetting) Typ ¶
func (*StringSetting) Typ() string
Typ returns the short (1 char) string denoting the type of setting.
func (*StringSetting) Validate ¶
func (s *StringSetting) Validate(v string) error
Validate that a value conforms with the validation function.
type Updater ¶
type Updater map[string]struct{}
Updater is a helper for updating the in-memory settings.
RefreshSettings passes the serialized representations of all individual settings -- e.g. the rows read from the system.settings table. We update the wrapped atomic settings values as we go and note which settings were updated, then set the rest to default in Done().
func MakeUpdater ¶
func MakeUpdater() Updater
MakeUpdater returns a new Updater, pre-alloced to the registry size.
Source Files