| Overview |  |
Throttling for activities that can potentially overload resources. Provides support for "throttling" (i.e. slowing down) calling processes that, when under heavy load, could potentially overload other resources. Activities are identified by a unique key so that different throttle values can be used for different activities.
The throttle for an activity can be set to a specific value with theset_throttle/2 function, or it can be set to a value based on the current
"load" for the activity by using the set_limits/2 function to define a
mapping from load factors to throttle values, and then periodically calling
the set_throttle_by_load/2 function with the current load factor. Note
that "load factor" is an abstract concept, the purpose of which is simply
to represent numerically the amount of load that an activity is under and
map that level of load to a particular throttle level. Examples of metrics
that could be used for load factors include the size of the mailbox for a
particular process, or the number of messages per second being sent to an
external service such as Solr.
activity_key() = atom()
app_name() = atom()
limits() = [{load_factor(), throttle_time()}]
load_factor() = number() | atom() | tuple()
throttle_time() = non_neg_integer()
| clear_limits/2 | Clears the limits for the activity identified by AppName and Key. |
| clear_throttle/2 | Clears the throttle for the activity identified by AppName and Key. |
| create_limits_translator_fun/2 | Returns a fun that used in Cuttlefish translations to translate from
configuration items of the form:
ConfigPrefix.throttle.tier1.LoadFactorMeasure
to the list of tuples form expected by the set_limits/2 function in this
module. |
| disable_throttle/2 | Disables the throttle for the activity identified by AppName and
Key. |
| enable_throttle/2 | Enables the throttle for the activity identified by AppName and
Key. |
| get_limits/2 | Returns the limits for the activity identified by AppName and Key
if defined, otherwise returns undefined. |
| get_throttle/2 | |
| init/0 | Initialize the throttling subsystem. |
| init/4 | Initializes the throttle for the activity identified by AppName and
Key using configuration values found in the application environment for
AppName. |
| is_throttle_enabled/2 | Returns true if the throttle for the activity identified by AppName
and Key is enabled, false otherwise. |
| set_limits/3 | Sets the limits for the activity identified by AppName and Key. |
| set_throttle/3 | Sets the throttle for the activity identified by AppName and Key to
the specified Time. |
| set_throttle_by_load/3 | Sets the throttle for the activity identified by AppName and Key
to a value determined by consulting the limits for the activity. |
| throttle/2 | Sleep for the number of milliseconds specified as the throttle time for
the activity identified by AppName and Key (unless the throttle for the
activity has been disabled with disable_throttle/1). |
clear_limits(AppName::app_name(), Key::activity_key()) -> ok
Clears the limits for the activity identified by AppName and Key.
clear_throttle(AppName::app_name(), Key::activity_key()) -> ok
Clears the throttle for the activity identified by AppName and Key.
create_limits_translator_fun(ConfigPrefix, LoadFactorMeasure) -> any()
Returns a fun that used in Cuttlefish translations to translate from
configuration items of the form:
ConfigPrefix.throttle.tier1.LoadFactorMeasure
to the list of tuples form expected by the set_limits/2 function in this
module. See riak_kv.schema and yokozuna.schema for example usages.
disable_throttle(AppName::app_name(), Key::activity_key()) -> ok
Disables the throttle for the activity identified by AppName and
Key.
enable_throttle(AppName::app_name(), Key::activity_key()) -> ok
Enables the throttle for the activity identified by AppName and
Key.
get_limits(AppName::app_name(), Key::activity_key()) -> limits() | undefined
Returns the limits for the activity identified by AppName and Key
if defined, otherwise returns undefined.
get_throttle(AppName::app_name(), Key::activity_key()) -> throttle_time() | undefined
init() -> ok
Initialize the throttling subsystem. Should be called just once during startup, although calling multiple times will not have any negative consequences.
init(AppName::app_name(), Key::activity_key(), X3::{LimitsKey::atom(), LimitsDefault::limits()}, X4::{EnabledKey::atom(), EnabledDefault::boolean()}) -> ok | {error, Reason::term()}
Initializes the throttle for the activity identified by AppName and
Key using configuration values found in the application environment for
AppName.
is_throttle_enabled(AppName::app_name(), Key::activity_key()) -> boolean()
Returns true if the throttle for the activity identified by AppName
and Key is enabled, false otherwise.
set_limits(AppName::app_name(), Key::activity_key(), Limits::limits()) -> ok | no_return()
Sets the limits for the activity identified by AppName and Key.
Limits is a mapping from load factors to throttle values. Once this
mapping has been established, the set_throttle_by_load/2 function can
be used to set the throttle for the activity based on the current load
factor.
All of the throttle values in the Limits list must be non-negative
integers. Additionally, the Limits list must contain a tuple with the
key -1. If either of these conditions does not hold, this function exits
with an error.
See also: set_throttle_by_load/2.
set_throttle(AppName::app_name(), Key::activity_key(), Time::throttle_time()) -> ok
Sets the throttle for the activity identified by AppName and Key to
the specified Time.
set_throttle_by_load(AppName::app_name(), Key::activity_key(), LoadFactor::load_factor()) -> throttle_time()
Sets the throttle for the activity identified by AppName and Key
to a value determined by consulting the limits for the activity. The
throttle value is the value associated with the largest
load factor <= LoadFactor.
Normally the LoadFactor will be a number representing the current level
of load for the activity, but it is also allowed to pass an atom or a tuple
as the LoadFactor. This can be used when a numeric value cannot be
established, and results in using the throttle value for the largest load
factor defined in the limits for the activity.
If there are no limits defined for the activity, exits with error({no_limits, Key}).
See also: set_limits/2.
throttle(AppName::app_name(), Key::activity_key()) -> throttle_time()
Sleep for the number of milliseconds specified as the throttle time for
the activity identified by AppName and Key (unless the throttle for the
activity has been disabled with disable_throttle/1). If there is no
throttle value configured for Key, then exits with error({badkey, Key}).
Generated by EDoc