Module sbroker

This module provides a process match making service.

Behaviours: gen_fsm.

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: bid/1 and ask/1. Processes that call bid/1 are matched against processes that call ask/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 bid/1 try to match with/dequeue a process in the ask queue. If no process exists they are queued in the bid queue and await a process to call ask/1.

Similarly processes calling ask/1 try to match with/dequeue a process in the bid queue. If no process exists they are queued in the ask queue and await a process to call bid/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 bid/1 on the same broker.
async_ask/1Sends an asynchronous request to match with a process calling bid/1.
async_bid/1Sends an asynchronous request to match with a process calling ask/1.
bid/1Tries to match with a process calling ask/1 on the same broker.
cancel/2Cancels an asynchronous request.
start_link/0Starts a broker with default queues.
start_link/1Starters a registered broker with default queues.
start_link/3Starts a broker with custom queues.
start_link/4Starters a registered broker with custom queues.

Function Details

ask/1

ask(Broker) -> Settled | Dropped

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

See also: bid/1.

async_ask/1

async_ask(Broker) -> ARef

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

See also: async_bid/1, cancel/2.

async_bid/1

async_bid(Broker) -> ARef

Sends an asynchronous request to match with a process calling ask/1. Returns a reference(), ARef, which can be used to identify the reply containing the result of the request, or to cancel the request using cancel/1.

The reply is of the form {ARef, {settle, Ref, Pid, SojournTime} or {ARef, {dropped, 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 appriopriate steps to handle this scenario.

See also: cancel/2.

bid/1

bid(Broker) -> Settled | Dropped

Tries to match with a process calling ask/1 on the same broker. Returns {settled, Ref, Pid, SojournTime} on a successful match or {dropped, 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.

cancel/2

cancel(Broker, ARef) -> 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_bid/1.

start_link/0

start_link() -> StartReturn

Starts a broker with default queues. The default queue uses squeue_timeout with a timeout of 5000, which means that items are dropped if they spend longer than 5000ms in the queue. The queue has a size of infinity and uses out to dequeue items. The tick interval is 200, so the active queue management timeout strategy is applied at least every 200ms.

start_link/1

start_link(Name) -> StartReturn

Starters a registered broker with default queues.

See also: start_link/1.

start_link/3

start_link(BiddingSpec, AskingSpec, Interval) -> StartReturn

Starts a broker with custom queues.

The first argument, BiddingSpec, is the queue specification for the bidding queue. Processes that call bid/1 (or async_bid/1) can not be matched with a process calling ask/1 (or async_ask/1) will be queued in this queue. Similarly, the second argument, AskingSpec, is the queue specification for the asking queue. Processes that call ask/1 (or async_ask/1) are enqueued in this queue The third argument, Interval, is the interval 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.

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/4

start_link(Name, BiddingSpec, AskingSpec, Interval) -> StartReturn

Starters a registered broker with custom queues.

See also: start_link/3.


Generated by EDoc, Dec 22 2014, 14:24:17.