cockroach: github.com/cockroachdb/cockroach/pkg/settings Index | Files | Directories

package settings

import "github.com/cockroachdb/cockroach/pkg/settings"

Package settings provides a central registry of runtime editable settings and accompanying helper functions for retrieving 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 access settings.

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.

Ideally, when passing configuration into some structure or subsystem, e.g. a rate limit into a client or something, passing a `*FooSetting` rather than a `Foo` and waiting to call `.Get()` until the value is actually used ensures observing the latest value.

Settings may become irrelevant over time, especially when introduced to provide a workaround to a system limitation which is later corrected. When deleting a setting's registration from the codebase, add its name to the list of `retiredSettings` in settings/registry.go -- this ensures the name cannot be accidentally reused, and suppresses log spam about the existing value.

That list of retired settings can periodically (i.e. in major versions) be "flushed" by adding a migration that deletes all stored values for those keys at which point the key would be available for reuse in a later version. Is is only safe to run such a migration after the cluster upgrade process ensures no older nodes are still using the values for those old settings though, so such a migration needs to be version gated.

Existing/off-the-shelf systems generally will not be defined in terms of our settings, but if they can either be swapped at runtime or expose some `setFoo` method, that can be used in conjunction with a change callback registered via OnChange.

Index

Package Files

bool.go byte_size.go doc.go duration.go enum.go float.go int.go registry.go setting.go statemachine.go string.go updater.go

Variables

var ReadableTypes = map[string]string{
    "s": "string",
    "i": "integer",
    "f": "float",
    "b": "boolean",
    "z": "byte size",
    "d": "duration",
    "e": "enumeration",
    "m": "custom validation",
}

ReadableTypes maps our short type identifiers to friendlier names.

var Registry = make(map[string]Setting)

Registry contains all defined settings, their types and default values.

The registry does not store the current values of the settings; those are stored separately in Values, allowing multiple independent instances of each setting in the registry.

Registry should never be mutated after creation (except in tests), as it is read concurrently by different callers.

var TestOpaque interface{} = testOpaqueType{}

TestOpaque can be passed to Values.Init when we are testing the settings infrastructure.

func EncodeBool Uses

func EncodeBool(b bool) string

EncodeBool encodes a bool in the format parseRaw expects.

func EncodeDuration Uses

func EncodeDuration(d time.Duration) string

EncodeDuration encodes a duration in the format parseRaw expects.

func EncodeFloat Uses

func EncodeFloat(f float64) string

EncodeFloat encodes a bool in the format parseRaw expects.

func EncodeInt Uses

func EncodeInt(i int64) string

EncodeInt encodes an int in the format parseRaw expects.

func Keys Uses

func Keys() (res []string)

Keys returns a sorted string array with all the known keys.

func SanitizedValue Uses

func SanitizedValue(name string, values *Values) string

SanitizedValue returns a string representation of the value for settings types the are not considered sensitive (numbers, bools, etc) or <redacted> for those with values could store sensitive things (i.e. strings).

func SetCanonicalValuesContainer Uses

func SetCanonicalValuesContainer(v *Values)

SetCanonicalValuesContainer sets the Values container that will be refreshed at runtime -- ideally we should have no other *Values containers floating around, as they will be stale / lies.

type BoolSetting Uses

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 Uses

func RegisterBoolSetting(key, desc string, defaultValue bool) *BoolSetting

RegisterBoolSetting defines a new setting with type bool.

func (BoolSetting) Description Uses

func (i BoolSetting) Description() string

func (*BoolSetting) Encoded Uses

func (b *BoolSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*BoolSetting) EncodedDefault Uses

func (b *BoolSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*BoolSetting) Get Uses

func (b *BoolSetting) Get(sv *Values) bool

Get retrieves the bool value in the setting.

func (BoolSetting) Hidden Uses

func (i BoolSetting) Hidden() bool

func (*BoolSetting) Override Uses

func (b *BoolSetting) Override(sv *Values, v bool)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*BoolSetting) SetConfidential Uses

func (i *BoolSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*BoolSetting) SetDeprecated Uses

func (i *BoolSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*BoolSetting) SetOnChange Uses

func (i *BoolSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*BoolSetting) SetSensitive Uses

func (i *BoolSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*BoolSetting) String Uses

func (b *BoolSetting) String(sv *Values) string

func (*BoolSetting) Typ Uses

func (*BoolSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type ByteSizeSetting Uses

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 Uses

func RegisterByteSizeSetting(key, desc string, defaultValue int64) *ByteSizeSetting

RegisterByteSizeSetting defines a new setting with type bytesize.

func RegisterValidatedByteSizeSetting Uses

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) Description Uses

func (i ByteSizeSetting) Description() string

func (ByteSizeSetting) Hidden Uses

func (i ByteSizeSetting) Hidden() bool

func (*ByteSizeSetting) SetConfidential Uses

func (i *ByteSizeSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*ByteSizeSetting) SetDeprecated Uses

func (i *ByteSizeSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*ByteSizeSetting) SetOnChange Uses

func (i *ByteSizeSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*ByteSizeSetting) SetSensitive Uses

func (i *ByteSizeSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*ByteSizeSetting) String Uses

func (b *ByteSizeSetting) String(sv *Values) string

func (*ByteSizeSetting) Typ Uses

func (*ByteSizeSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type DurationSetting Uses

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 Uses

func RegisterDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting

RegisterDurationSetting defines a new setting with type duration.

func RegisterNonNegativeDurationSetting Uses

func RegisterNonNegativeDurationSetting(
    key, desc string, defaultValue time.Duration,
) *DurationSetting

RegisterNonNegativeDurationSetting defines a new setting with type duration.

func RegisterValidatedDurationSetting Uses

func RegisterValidatedDurationSetting(
    key, desc string, defaultValue time.Duration, validateFn func(time.Duration) error,
) *DurationSetting

RegisterValidatedDurationSetting defines a new setting with type duration.

func (DurationSetting) Description Uses

func (i DurationSetting) Description() string

func (*DurationSetting) Encoded Uses

func (d *DurationSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*DurationSetting) EncodedDefault Uses

func (d *DurationSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*DurationSetting) Get Uses

func (d *DurationSetting) Get(sv *Values) time.Duration

Get retrieves the duration value in the setting.

func (DurationSetting) Hidden Uses

func (i DurationSetting) Hidden() bool

func (*DurationSetting) Override Uses

func (d *DurationSetting) Override(sv *Values, v time.Duration)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*DurationSetting) SetConfidential Uses

func (i *DurationSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*DurationSetting) SetDeprecated Uses

func (i *DurationSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*DurationSetting) SetOnChange Uses

func (i *DurationSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*DurationSetting) SetSensitive Uses

func (i *DurationSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*DurationSetting) String Uses

func (d *DurationSetting) String(sv *Values) string

func (*DurationSetting) Typ Uses

func (*DurationSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*DurationSetting) Validate Uses

func (d *DurationSetting) Validate(v time.Duration) error

Validate that a value conforms with the validation function.

type EnumSetting Uses

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 Uses

func RegisterEnumSetting(
    key, desc string, defaultValue string, enumValues map[int64]string,
) *EnumSetting

RegisterEnumSetting defines a new setting with type int.

func (EnumSetting) Description Uses

func (i EnumSetting) Description() string

func (EnumSetting) Hidden Uses

func (i EnumSetting) Hidden() bool

func (*EnumSetting) ParseEnum Uses

func (e *EnumSetting) ParseEnum(raw string) (int64, bool)

ParseEnum returns the enum value, and a boolean that indicates if it was parseable.

func (*EnumSetting) SetConfidential Uses

func (i *EnumSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*EnumSetting) SetDeprecated Uses

func (i *EnumSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*EnumSetting) SetOnChange Uses

func (i *EnumSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*EnumSetting) SetSensitive Uses

func (i *EnumSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*EnumSetting) String Uses

func (e *EnumSetting) String(sv *Values) string

String returns the enum's string value.

func (*EnumSetting) Typ Uses

func (e *EnumSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type FloatSetting Uses

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 Uses

func RegisterFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterFloatSetting defines a new setting with type float.

func RegisterNonNegativeFloatSetting Uses

func RegisterNonNegativeFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterNonNegativeFloatSetting defines a new setting with type float.

func RegisterValidatedFloatSetting Uses

func RegisterValidatedFloatSetting(
    key, desc string, defaultValue float64, validateFn func(float64) error,
) *FloatSetting

RegisterValidatedFloatSetting defines a new setting with type float.

func (*FloatSetting) Default Uses

func (f *FloatSetting) Default() float64

Default returns the default value.

func (FloatSetting) Description Uses

func (i FloatSetting) Description() string

func (*FloatSetting) Encoded Uses

func (f *FloatSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*FloatSetting) EncodedDefault Uses

func (f *FloatSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*FloatSetting) Get Uses

func (f *FloatSetting) Get(sv *Values) float64

Get retrieves the float value in the setting.

func (FloatSetting) Hidden Uses

func (i FloatSetting) Hidden() bool

func (*FloatSetting) Override Uses

func (f *FloatSetting) Override(sv *Values, v float64)

Override changes the setting panicking if validation fails and also overrides the default value.

For testing usage only.

func (*FloatSetting) SetConfidential Uses

func (i *FloatSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*FloatSetting) SetDeprecated Uses

func (i *FloatSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*FloatSetting) SetOnChange Uses

func (i *FloatSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*FloatSetting) SetSensitive Uses

func (i *FloatSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*FloatSetting) String Uses

func (f *FloatSetting) String(sv *Values) string

func (*FloatSetting) Typ Uses

func (*FloatSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*FloatSetting) Validate Uses

func (f *FloatSetting) Validate(v float64) error

Validate that a value conforms with the validation function.

type IntSetting Uses

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 Uses

func RegisterIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterIntSetting defines a new setting with type int.

func RegisterNonNegativeIntSetting Uses

func RegisterNonNegativeIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterNonNegativeIntSetting defines a new setting with type int.

func RegisterPositiveIntSetting Uses

func RegisterPositiveIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterPositiveIntSetting defines a new setting with type int.

func RegisterValidatedIntSetting Uses

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) Default Uses

func (i *IntSetting) Default() int64

Default returns the default value.

func (IntSetting) Description Uses

func (i IntSetting) Description() string

func (*IntSetting) Encoded Uses

func (i *IntSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*IntSetting) EncodedDefault Uses

func (i *IntSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*IntSetting) Get Uses

func (i *IntSetting) Get(sv *Values) int64

Get retrieves the int value in the setting.

func (IntSetting) Hidden Uses

func (i IntSetting) Hidden() bool

func (*IntSetting) Override Uses

func (i *IntSetting) Override(sv *Values, v int64)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*IntSetting) SetConfidential Uses

func (i *IntSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*IntSetting) SetDeprecated Uses

func (i *IntSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*IntSetting) SetOnChange Uses

func (i *IntSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*IntSetting) SetSensitive Uses

func (i *IntSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*IntSetting) String Uses

func (i *IntSetting) String(sv *Values) string

func (*IntSetting) Typ Uses

func (*IntSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*IntSetting) Validate Uses

func (i *IntSetting) Validate(v int64) error

Validate that a value conforms with the validation function.

type NoopUpdater Uses

type NoopUpdater struct{}

A NoopUpdater ignores all updates.

func (NoopUpdater) ResetRemaining Uses

func (u NoopUpdater) ResetRemaining()

ResetRemaining implements Updater. It is a no-op.

func (NoopUpdater) Set Uses

func (u NoopUpdater) Set(_, _, _ string) error

Set implements Updater. It is a no-op.

type Setting Uses

type Setting interface {

    // Typ returns the short (1 char) string denoting the type of setting.
    Typ() string
    String(sv *Values) string
    Encoded(sv *Values) string

    EncodedDefault() string

    Description() string

    Hidden() bool

    SetOnChange(sv *Values, fn func())
    // contains filtered or unexported methods
}

Setting is a descriptor for each setting; once it is initialized, it is immutable. The values for the settings are stored separately, in Values. This way we can have a global set of registered settings, each with potentially multiple instances.

func Lookup Uses

func Lookup(name string) (Setting, bool)

Lookup returns a Setting by name along with its description.

type StateMachineSetting Uses

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

A StateMachineSetting is a setting that keeps a state machine driven by user input.

For (a nonsensical) example, a StateMachineSetting can be used to maintain an encoded protobuf containing an integer that the user can only increment by 3 if the int is odd and by two if it is even. More generally, the setting starts from an initial state, and can take the current state into account when determining user input. Initially this is motivated for use in cluster version upgrades.

The state machine as well as its encoding are represented by the TransformerFn backing this StateMachineSetting. It is a method that takes

- the Values instance - the known previous encoded value, if any (i.e. the current state) - the update the user wants to make to the encoded struct (i.e. the desired

transition)

and returns

- the new encoded value (i.e. the new state) - an interface backed by a "user-friendly" representation of the new state

(i.e. something that can be printed)

- an error if the input was illegal.

Furthermore,

- with a `nil` input byte slice, the default value (hidden in the

transformer) is used internally

- with a `nil` update, the previous (or default) value is returned - with both non-nil, a transition from the old state using the given update

is carried out, and the new state and representation (or an error)
returned.

The opaque member of Values can be used to associate a higher-level object to the Values instance (making it accessible to the function).

Updates to the setting via an Updater validate the new state syntactically, but not semantically. Users must call Validate with the authoritative previous state, the suggested state transition, and then overwrite the state machine with the result.

func RegisterStateMachineSetting Uses

func RegisterStateMachineSetting(key, desc string, transformer TransformerFn) *StateMachineSetting

RegisterStateMachineSetting registers a StateMachineSetting. See the comment for StateMachineSetting for details.

func (StateMachineSetting) Description Uses

func (i StateMachineSetting) Description() string

func (*StateMachineSetting) Encoded Uses

func (s *StateMachineSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*StateMachineSetting) EncodedDefault Uses

func (s *StateMachineSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*StateMachineSetting) Get Uses

func (s *StateMachineSetting) Get(sv *Values) string

Get retrieves the (encoded) value in the setting (or the encoded default).

func (StateMachineSetting) Hidden Uses

func (i StateMachineSetting) Hidden() bool

func (*StateMachineSetting) SetConfidential Uses

func (i *StateMachineSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*StateMachineSetting) SetDeprecated Uses

func (i *StateMachineSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*StateMachineSetting) SetOnChange Uses

func (i *StateMachineSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*StateMachineSetting) SetSensitive Uses

func (i *StateMachineSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*StateMachineSetting) String Uses

func (s *StateMachineSetting) String(sv *Values) string

func (*StateMachineSetting) Typ Uses

func (*StateMachineSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StateMachineSetting) Validate Uses

func (s *StateMachineSetting) Validate(
    sv *Values, old []byte, update *string,
) ([]byte, interface{}, error)

Validate that the state machine accepts the user input. Returns new encoded state, unencoded state, or an error. If no update is given, round trips current state.

type StringSetting Uses

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 Uses

func RegisterStringSetting(key, desc string, defaultValue string) *StringSetting

RegisterStringSetting defines a new setting with type string.

func RegisterValidatedStringSetting Uses

func RegisterValidatedStringSetting(
    key, desc string, defaultValue string, validateFn func(*Values, string) error,
) *StringSetting

RegisterValidatedStringSetting defines a new setting with type string with a validation function.

func (StringSetting) Description Uses

func (i StringSetting) Description() string

func (*StringSetting) Encoded Uses

func (s *StringSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*StringSetting) EncodedDefault Uses

func (s *StringSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*StringSetting) Get Uses

func (s *StringSetting) Get(sv *Values) string

Get retrieves the string value in the setting.

func (StringSetting) Hidden Uses

func (i StringSetting) Hidden() bool

func (*StringSetting) SetConfidential Uses

func (i *StringSetting) SetConfidential()

SetConfidential 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 SetConfidential for data that must be hidden from standard setting report and troubleshooting screenshots, such as license data or keys.

func (*StringSetting) SetDeprecated Uses

func (i *StringSetting) SetDeprecated()

SetDeprecated marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*StringSetting) SetOnChange Uses

func (i *StringSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*StringSetting) SetSensitive Uses

func (i *StringSetting) SetSensitive()

SetSensitive marks the setting as dangerous to modify. Use SetConfidential for settings where the user must be strongly discouraged to tweak the values.

func (*StringSetting) String Uses

func (s *StringSetting) String(sv *Values) string

func (*StringSetting) Typ Uses

func (*StringSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StringSetting) Validate Uses

func (s *StringSetting) Validate(sv *Values, v string) error

Validate that a value conforms with the validation function.

type TransformerFn Uses

type TransformerFn func(sv *Values, old []byte, update *string) (finalV []byte, finalObj interface{}, _ error)

A TransformerFn encapsulates the logic of a StateMachineSetting.

type Updater Uses

type Updater interface {
    Set(k, rawValue, valType string) error
    ResetRemaining()
}

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

func NewUpdater Uses

func NewUpdater(sv *Values) Updater

NewUpdater makes an Updater.

type Values Uses

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

Values is a container that stores values for all registered settings. Each setting is assigned a unique slot (up to maxSettings). Note that slot indices are 1-based (this is to trigger panics if an uninitialized slot index is used).

func TODO Uses

func TODO() *Values

TODO is usable at callsites that do not have *settings.Values available. Please don't use this.

func (*Values) Init Uses

func (sv *Values) Init(opaque interface{})

Init must be called before using a Values instance; it initializes all variables to their defaults.

The opaque argument can be retrieved later via Opaque().

func (*Values) Opaque Uses

func (sv *Values) Opaque() interface{}

Opaque returns the argument passed to Init.

Directories

PathSynopsis
cluster

Package settings imports 14 packages (graph) and is imported by 54 packages. Updated 2019-09-14. Refresh now. Tools for package owners.