Overviewerlang logo

Module sbroker

This module provides a process match making service.

Behaviours: gen_fsm.

This module defines the sbroker behaviour.
Required callback functions: init/1.

Description

This module provides a process match making service. A process joins one of two queues and is matches with a process in the other queue. The queues can be actively managed using an squeue callback module, and passively managed using head or tail drop. A different strategy can be used for both queues. Processes that die while in a queue are automatically removed to prevent matching with a process that is nolonger alive.

There are two functions to join a queue: ask/1 and ask_r/1. Processes that call ask/1 are matched against processes that call ask_r/1. If no match is immediately avaliable a process is queued in the relevant queue until a match becomes avaliable. If queue management is used processes may be dropped without a match.

Processes calling ask/1 try to match with/dequeue a process in the ask_r queue. If no process exists they are queued in the ask queue and await a process to call ask_r/1.

Similarly processes calling ask_r/1 try to match with/dequeue a process in the ask queue. If no process exists they are queued in the ask_r queue and await a process to call ask/1.

Data Types

broker()

broker() = pid() | atom() | {atom(), node()} | {global, any()} | {via, module(), any()}

name()

name() = {local, atom()} | {global, any()} | {via, module(), any()}

queue_spec()

queue_spec() = {module(), any(), out | out_r, non_neg_integer() | infinity, drop | drop_r}

start_return()

start_return() = {ok, pid()} | {error, any()}

Function Index

ask/1Tries to match with a process calling ask_r/1 on the same broker.
ask_r/1Tries to match with a process calling ask/1 on the same broker.
async_ask/1Monitors the broker and sends an asynchronous request to match with a process calling ask_r/1.
async_ask/2Sends an asynchronous request to match with a process calling ask_r/1.
async_ask_r/1Monitors the broker and sends an asynchronous request to match with a process calling ask/1.
async_ask_r/2Sends an asynchronous request to match with a process calling ask/1.
cancel/2Cancels an asynchronous request.
change_config/2Change the configuration of the broker.
nb_ask/1Tries to match with a process calling ask_r/1 on the same broker but does not enqueue the request if no immediate match.
nb_ask_r/1Tries to match with a process calling ask/1 on the same broker but does not enqueue the request if no immediate match.
start_link/2Starts a broker with callback module Module and argument Args.
start_link/3Starts a broker with name Name, callback module Module and argument Args.

Function Details

ask/1

ask(Broker) -> Go | Drop

Tries to match with a process calling ask_r/1 on the same broker. Returns {go, Ref, Pid, SojournTime} on a successful match or {drop, SojournTime}.

Ref is the transaction reference, which is a reference(). Pid is the matched process. SojournTime is the time spent in the queue in milliseconds.

ask_r/1

ask_r(Broker) -> Go | Drop

Tries to match with a process calling ask/1 on the same broker.

See also: ask/1.

async_ask/1

async_ask(Broker) -> {await, Tag, Process}

Monitors the broker and sends an asynchronous request to match with a process calling ask_r/1. Returns {await, Tag, Process}.

Tag is a monitor reference() that uniquely identifies the reply containing the result of the request. Process, is the pid (pid()) or process name ({atom(), node()}) of the monitored broker. To cancel the request call cancel(Process, Tag).

The reply is of the form {Tag, {go, Ref, Pid, SojournTime} or {Tag, {drop, SojournTime}}.

Multiple asynchronous requests can be made from a single process to a broker and no guarantee is made of the order of replies. A process making multiple requests can reuse the monitor reference for subsequent requests to the same broker process (Process) using async_ask/2.

See also: async_ask/2, cancel/2.

async_ask/2

async_ask(Broker, Tag) -> {await, Tag, Process}

Sends an asynchronous request to match with a process calling ask_r/1. Returns {await, Tag, Process}.

Tag is a any() that identifies the reply containing the result of the request. Process, is the pid (pid()) or process name ({atom(), node()}) of the broker. To cancel all requests identified by Tag on broker Process call cancel(Process, Tag).

The reply is of the form {Tag, {go, Ref, Pid, SojournTime} or {Tag, {drop, SojournTime}}.

Multiple asynchronous requests can be made from a single process to a broker and no guarantee is made of the order of replies. If the broker exits or is on a disconnected node there is no guarantee of a reply and so the caller should take appropriate steps to handle this scenario.

See also: cancel/2.

async_ask_r/1

async_ask_r(Broker) -> {await, Tag, Process}

Monitors the broker and sends an asynchronous request to match with a process calling ask/1.

See also: async_ask/1, cancel/2.

async_ask_r/2

async_ask_r(Broker, Tag) -> {await, Tag, Process}

Sends an asynchronous request to match with a process calling ask/1.

See also: async_ask/2, cancel/2.

cancel/2

cancel(Broker, Tag) -> ok | {error, not_found}

Cancels an asynchronous request. Returns ok on success and {error, not_found} if the request does not exist. In the later case a caller may wish to check its message queue for an existing reply.

See also: async_ask/1, async_ask_r/1.

change_config/2

change_config(Broker, Timeout) -> ok | {error, Reason}

Change the configuration of the broker. Returns ok on success and {error, Reason} on failure, where Reason, is the reason for failure.

Broker calls the init/1 callback to get the new configuration. If init/1 returns ignore the config does not change.

See also: start_link/2.

nb_ask/1

nb_ask(Broker) -> Go | Retry

Tries to match with a process calling ask_r/1 on the same broker but does not enqueue the request if no immediate match. Returns {go, Ref, Pid, 0} on a successful match or {retry, 0}.

Ref is the transaction reference, which is a reference(). Pid is the matched process. 0 reflects the fact that no time was spent in the queue.

See also: ask/1.

nb_ask_r/1

nb_ask_r(Broker) -> Go | Retry

Tries to match with a process calling ask/1 on the same broker but does not enqueue the request if no immediate match.

See also: nb_ask/1.

start_link/2

start_link(Module, Args) -> StartReturn

Starts a broker with callback module Module and argument Args.

The callback modules implements one callback, init/1, with single argument Args. init/1 should return {ok, {AskQueueSpec, AskRQueueSpec, Interval}) or ignore. AskQueuSpec is the queue specification for the ask queue and AskRQueueSpec is the queue specification for the ask_r queue. Interval is the internval in milliseconds that the active queue is polled. This ensures that the active queue management strategy is applied even if no processes are enqueued/dequeued. In the case of ignore the broker is not started and start_link returns ignore.

A queue specifcation takes the following form: {Module, Args, Out, Size, Drop}. Module is the squeue callback module and Args are its arguments. The queue is created using squeue:new(Module, Arg). Out defines the method of dequeuing, it is either the atom out (dequeue items from the head, i.e. FIFO), or the atom out_r (dequeue items from the tail, i.e. LIFO). Size is the maximum size of the queue, it is either a non_neg_integer() or infinity. Drop defines the strategy to take when the maximum size, Size, of the queue is exceeded. It is either the atom drop (drop from the head of the queue, i.e. head drop) or drop_r (drop from the tail of the queue, i.e. tail drop)

start_link/3

start_link(Name, Module, Args) -> StartReturn

Starts a broker with name Name, callback module Module and argument Args.

See also: start_link/2.

Overviewerlang logo

Generated by EDoc, Jan 28 2015, 17:16:35.