Behaviours: gen_fsm.
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
.
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
.
broker() = pid() | atom() | {atom(), node()} | {global, any()} | {via, module(), any()}
name() = {local, atom()} | {global, any()} | {via, module(), any()}
queue_spec() = {module(), any(), out | out_r, non_neg_integer() | infinity, drop | drop_r}
start_return() = {ok, pid()} | {error, any()}
ask/1 | Tries to match with a process calling ask_r/1 on the same broker. |
ask_r/1 | Tries to match with a process calling ask/1 on the same broker. |
async_ask/1 | Sends an asynchronous request to match with a process calling ask_r/1 . |
async_ask_r/1 | Sends an asynchronous request to match with a process calling ask/1 . |
cancel/2 | Cancels an asynchronous request. |
start_link/0 | Starts a broker with default queues. |
start_link/1 | Starts a registered broker with default queues. |
start_link/3 | Starts a broker with custom queues. |
start_link/4 | Starts a registered broker with custom queues. |
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(Broker) -> Go | Drop
Tries to match with a process calling ask/1
on the same broker.
See also: ask/1.
async_ask(Broker) -> ARef
Sends an asynchronous request to match with a process calling ask_r/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, {go, Ref, Pid, SojournTime}
or
{ARef, {drop, SojournTime}}
.
See also: cancel/2.
async_ask_r(Broker) -> ARef
Sends an asynchronous request to match with a process calling ask/1
.
See also: async_ask/1, 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_ask_r/1.
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(Name) -> StartReturn
Starts a registered broker with default queues.
See also: start_link/1.
start_link(AskQueueSpec, AskRQueueSpec, Interval) -> StartReturn
Starts a broker with custom queues.
The first argument, AskQueueSpec
, is the queue specification for the ask
queue. Processes that call ask/1
(or async_ask/1
) can not be matched with
a process calling ask_r/1
(or async_ask_r/1
) will be queued in this
queue. Similarly, the second argument, AskRQueueSpec
, is the queue
specification for ask_r
queue. Processes that call ask_r/1
(or
async_ask_r/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.
{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(Name, AskQueueSpec, AskRQueueSpec, Interval) -> StartReturn
Starts a registered broker with custom queues.
See also: start_link/3.
Generated by EDoc, Jan 17 2015, 16:58:31.