This is the public API of the JOBS framework.
Authors: : Ulf Wiger (ulf.wiger@erlang-solutions.com).
| add_counter/2 | Adds a named counter to the load regulator on the current node. |
| add_group_rate/2 | Adds a group rate regulator to the load regulator on the current node. |
| add_queue/2 | Installs a new queue in the load regulator on the current node. |
| ask/1 | Asks permission to run a job of Type. |
| ask_queue/2 | Sends a synchronous request to a specific queue. |
| delete_counter/1 | Deletes a named counter from the load regulator on the current node. |
| delete_group_rate/1 | |
| delete_queue/1 | Deletes the named queue from the load regulator on the current node. |
| dequeue/2 | |
| done/1 | Signals completion of an executed task. |
| enqueue/2 | |
| info/1 | |
| job_info/1 | Retrieves job-specific information from the Opaque data object. |
| modify_counter/2 | |
| modify_group_rate/2 | |
| modify_regulator/4 | |
| queue_info/1 | |
| queue_info/2 | |
| run/2 | Executes Function() when permission has been granted by job regulator. |
add_counter(Name, Options) -> ok
Adds a named counter to the load regulator on the current node.
Fails if there already is a counter the name Name.
add_group_rate(Name, Options) -> ok
Adds a group rate regulator to the load regulator on the current node. Fails if there is already a group rate regulator of the same name.
add_queue(Name::any(), Options::[{Key, Value}]) -> ok
Installs a new queue in the load regulator on the current node.
ask(Type) -> {ok, Opaque} | {error, Reason}
Asks permission to run a job of Type. Returns when permission granted.
The simplest way to have jobs regulated is to spawn a request per job.
The process should immediately call this function, and when granted
permission, execute the job, and then terminate.
If for some reason the process needs to remain, to execute more jobs,
it should explicitly call jobs:done(Opaque).
This is not strictly needed when regulation is rate-based, but as the
regulation strategy may change over time, it is the prudent thing to do.
ask_queue(QueueName, Request) -> Reply
Sends a synchronous request to a specific queue.
This function is mainly intended to be used for back-end processes that act as custom extensions to the load regulator itself. It should not be used by regular clients. Sophisticated queue behaviours could export gen_server-like logic allowing them to respond to synchronous calls, either for special inspection, or for influencing the queue state.
delete_counter(Name) -> boolean()
Deletes a named counter from the load regulator on the current node.
Returns true if there was in fact such a counter; false otherwise.
delete_group_rate(Name) -> any()
delete_queue(Name) -> boolean()
Deletes the named queue from the load regulator on the current node.
Returns true if there was in fact such a queue; false otherwise.
dequeue(Queue, N) -> any()
done(Opaque) -> ok
Signals completion of an executed task.
This is used when the current process wants to submit more jobs to load regulation. It is mandatory when performing counter-based regulation (unless the process terminates after completing the task). It has no effect if the job type is purely rate-regulated.
enqueue(Queue, Item) -> any()
info(Item) -> any()
job_info(X1::Opaque) -> undefined | Info
Retrieves job-specific information from the Opaque data object.
The queue could choose to return specific information that is passed to a granted job request. This could be used e.g. for load-balancing strategies.
modify_counter(CName, Opts) -> any()
modify_group_rate(GRName, Opts) -> any()
modify_regulator(Type, QName, RegName, Opts) -> any()
queue_info(Name) -> any()
queue_info(Name, Item) -> any()
run(Queue::Type, Function::function()) -> Result
Executes Function() when permission has been granted by job regulator.
This is equivalent to performing the following sequence:
case jobs:ask(Type) of
{ok, Opaque} ->
try Function()
after
jobs:done(Opaque)
end;
{error, Reason} ->
erlang:error(Reason)
end.