View Source amoc_throttle (amoc v3.0.0-rc2)

This module allows to synchronize the users and act on groups of them.

Summary

Functions

Sets Rate and Interval for Name according to the given values.

Allows to set a plan of gradual rate changes for a given Name.

Pauses executions for the given Name as if Rate was set to 0.

Resumes the executions for the given Name, to their original Rate and Interval values.

Executes a given function Fn when it does not exceed the rate for Name.

Sends a given message to erlang:self/0

See also: send/3.

Sends a given message Msg to a given Pid when the rate for Name allows for that. May be used to schedule tasks.
Sends and receives the given message Msg. Can be used to halt execution if we want a process to be idle when waiting for rate increase or other processes finishing their tasks.

Starts the throttle mechanism for a given Name with a given Rate.

Stops the throttle mechanism for the given Name.

Types

-type name() :: atom().

Functions

Link to this function

change_rate(Name, Rate, Interval)

View Source
-spec change_rate(name(), pos_integer(), non_neg_integer()) -> ok | {error, any()}.

Sets Rate and Interval for Name according to the given values.

Can change whether Amoc throttle limits Name to parallel executions or to Rate per Interval, according to the given Interval value.
Link to this function

change_rate_gradually(Name, LowRate, HighRate, RateInterval, StepInterval, NoOfSteps)

View Source
-spec change_rate_gradually(name(),
                      pos_integer(),
                      pos_integer(),
                      non_neg_integer(),
                      pos_integer(),
                      pos_integer()) ->
                         ok | {error, any()}.

Allows to set a plan of gradual rate changes for a given Name.

Rate will be changed from From to To in a series of consecutive steps. From does not need to be lower than To, rates can be changed downwards. The rate is calculated at each step in relation to the RateInterval, which can also be 0. Each step will take the StepInterval time in milliseconds. There will be NoOfSteps steps. Be aware that, at first, the rate will be changed to From per RateInterval and this is not considered a step.
-spec pause(name()) -> ok | {error, any()}.

Pauses executions for the given Name as if Rate was set to 0.

Does not stop the scheduled rate changes.
-spec resume(name()) -> ok | {error, any()}.
Resumes the executions for the given Name, to their original Rate and Interval values.
-spec run(name(), fun(() -> any())) -> ok | {error, any()}.

Executes a given function Fn when it does not exceed the rate for Name.

Fn is executed in the context of a new process spawned on the same node on which the process executing run/2 runs, so a call to run/2 is non-blocking. This function is used internally by both send and send_and_wait/2 functions, so all those actions will be limited to the same rate when called with the same Name.

Diagram showing function execution flow in distributed environment, generated using https://sequencediagram.org/:
         title Amoc distributed
         participantgroup  **Slave node**
             participant User
             participant Async runner
         end
         participantgroup **Master node**
             participant Throttle process
         end
         box left of User: inc req rate
 
         User -> *Async runner : Fun
 
         User -> Throttle process : {schedule, Async runner PID}
         box right of Throttle process : inc req rate
 
         ==throtlling delay==
 
         Throttle process -> Async runner: scheduled
 
         box left of Async runner : inc exec rate
         abox over Async runner : Fun()
         activate Async runner
         box right of Throttle process : inc exec rate
         deactivate Async runner
         Async runner ->Throttle process:'DOWN'
         destroy Async runner
for the local execution, req/exec rates are increased only by throttle process.
-spec send(name(), any()) -> ok | {error, any()}.
Sends a given message to erlang:self/0

See also: send/3.

-spec send(name(), pid(), any()) -> ok | {error, any()}.
Sends a given message Msg to a given Pid when the rate for Name allows for that. May be used to schedule tasks.
Link to this function

send_and_wait(Name, Msg)

View Source
-spec send_and_wait(name(), any()) -> ok | {error, any()}.
Sends and receives the given message Msg. Can be used to halt execution if we want a process to be idle when waiting for rate increase or other processes finishing their tasks.
-spec start(name(), pos_integer()) -> ok | {error, any()}.

See also: start/4.

Link to this function

start(Name, Rate, Interval)

View Source
-spec start(name(), pos_integer(), non_neg_integer()) -> ok | {error, any()}.

See also: start/4.

Link to this function

start(Name, Rate, Interval, NoOfProcesses)

View Source
-spec start(name(), pos_integer(), non_neg_integer(), pos_integer()) -> ok | {error, any()}.

Starts the throttle mechanism for a given Name with a given Rate.

The optional arguments are an Interval (default is one minute) and a NoOfProcesses (default is 10). Name is needed to identify the rate as a single test can have different rates for different tasks. Interval is given in milliseconds and can be changed to a different value for convenience or higher granularity. It also accepts a special value of 0 which limits the number of parallel executions associated with Name to Rate.
-spec stop(name()) -> ok | {error, any()}.
Stops the throttle mechanism for the given Name.