sbroker

Sojourn Broker - process broker for matchmaking between two groups of processes using sojourn time based active queue management to prevent congestion.

Introduction

sbroker is an experiment at an alternative to pooling. The philosophy is slightly different to traditional erlang pooling approaches as an sbroker process treates both sides (clients and workers) identically so it is more like a client-client relationship. Conceptual this is slightly different as both groups are exchanging themselves to gain a process from the other group. Whereas in a worker pool model the clients contact the pool seeking a worker. This means that workers contacting an sbroker should always "want" work, just as clients always "want" a worker for work.

In terms of the traditional client-worker architecture it can be helpful for workers to call ask/1 as they are offering their time, and clients to call bid/1 as they are trying to obtain a workers time. However sbroker would work exactly the same the reverse way around.

sbroker provides a simple interface to match processes. One party calls sbroker:bid/1 and the other party sbroker:ask/1. If a match is found both return {settled, Ref, Pid, SojournTime}, where SojournTime is the time spent in milliseconds waiting for a match (one will have a time of 0), Pid is the other process in the match and Ref is the transaction reference. If no match is found, returns {droppped, SojournTime}.

Processes calling sbroker:bid/1 are only matched with a process calling sbroker:ask/1 and vice versa.

Example

{ok, Broker} = sbroker:start_link(),
Pid = spawn_link(fun() -> sbroker:ask(Broker) end),
{settled _Ref, Pid, _SojournTime} = sbroker:bid(Broker).

Usage

sbroker provides configurable queues defined by sbroker:queue_spec()s. A queue_spec takes the form:

{Module, Args, Out, Size, Drop}

Module is an squeue callback module to handle active queue management. The following modules are possible: squeue_naive, squeue_timeout, squeue_codel and squeue_codel_timeout. Args is the argument passed to the callback module. Information about the different backends and their arguments are avaliable in the documentation.

Out sets the dequeue function, either the atom out (FIFO) or the atom out_r (LIFO).

Size is the maximum size of the queue. Should the queue go above this size a process is dropped. The dropping strategy is determined by Drop, which is either the atom drop (head drop) or the atom drop_r (tail drop).

An sbroker is started using sbroker:start_link/0,1,3,4:

sbroker:start_link(BiddingSpec, AskingSpec, Interval).

BiddingSpec is the queue_spec for the queue containing processes calling bid/1. The queue is referred to as the bidding queue. Similarly AskingSpec is the queue_spec for the queue contaning processes calling ask/1.

Interval is the interval in milliseconds that an sbroker is polled to apply timeout queue management. Note that timeout queue management can occur on every enqueue and dequeue, and is not reliant on the Interval. Setting a suitable interval ensures that active queue management can occur if no processes are queued or dequeued for a period of time.

Asynchronous versions of bid/1 and ask/1 are avaliable as async_bid/1 and async_ask/1. On a successful match the following message is sent:

{Ref, {settled, Ref, Pid, SojournTime}}

Where Ref is the return value of async_bid/1 or async_ask/1. If a match is not found:

{Ref, {dropped, SojournTime}}

Asynchronous requests can be cancelled with cancel/2:

{ok, Broker} = sbroker:start_link().
Ref = sbroker:async_bid(Broker).
ok = sbroker:cancel(Broker, Ref).

To help prevent race conditions when using asynchronous requests the message to the async_ask/1 or ask/1 process is always sent before the message to the async_bid/1 or bid/1 process. Therefore if the initial message between the two groups always flows in one direction, it may be beneficial for the receiver of that message to call async_ask/1 or ask/1, and the sender to call async_bid/1 orbid/1. Build ----- Rebar builds: ``` rebar compile ``` Documentation ------------- Rebar builds documentation: ``` rebar doc ``` Then visitdoc/index.html`. Test ---- Rebar fetches test dependency and runs common test: rebar get-deps compile ct -C rebar.test.config Roadmap ------- * Implement a pool that resizes based on feedback from sbroker. License ------- Dual BSD/GPL license This is the license used by the CoDel authors in their example implementation.