sbroker_fair_queue behaviour (sbroker v1.1.1)

Implements a fair queue containing multiple sbroker_queue queues.

sbroker_fair_queue can be used as a sbroker_queue in a sbroker or sregulator. It will provide a queue that enqueues requests to internal queues based on an index and dequeues from the internal queues fairly. Its argument, spec(), is of the form:
  {Module :: module(), Args :: any(), Index :: index()}

Module and Args are the module and arguments of the underlying sbroker_queue. Module must implement the sbroker_fair_queue behaviour.

Index is the method of choosing the queue to store a request in. To use the application of the sender: application. If the application can not be determined uses undefined. To use the node of the sender: node. To use the pid of the sender: pid. To use the value of the request: value. To use the Nth element of a tuple value: {element, N}. If the value is not a tuple of at least size N uses undefined.

One queue is used per key and so the number of possible keys should be bounded. If the underlying queue limits the size of its queue this only applies to the queue for that key. Requests with a different key will be in a different queue and be part of a separate limit. To limit the number of queues by hashing the key: {hash, Index2, Range}, where Index2 is any index() except another hash and Range is the number of queues, from 1 to 2^32.

Queues are chosen using a simple round robin strategy. Request are dequeued and empty queues removed using the handle_fq_out/2 callback, instead of the usual handle_out/2:
  -callback handle_fq_out(Time :: integer(), State :: any()) ->
      {SendTime :: integer(), From :: {Sender :: pid(), Tag :: any()},
       Value:: any(), Ref :: reference, NState :: any(),
       TimeoutTime :: integer() | infinity} |
      {empty, NState :: any(), RemoveTime :: integer() | infinity}.
The variables are equivalent to those of the sbroker_queue callback handle_out/2 with the addition of RemoveTime, which is the time (or infinity for never) to remove the empty queue from the fair queue for that index.

Link to this section Summary

Link to this section Types

Specs

index() :: key() | {hash, key(), 1..4294967296}.

Specs

key() :: application | node | pid | value | {element, pos_integer()}.
Link to this type

robin_queue/1

Specs

robin_queue(Index) :: queue:queue(Index).

Specs

spec() :: {Module :: module(), Args :: any(), Index :: index()}.

Link to this section Callbacks

Link to this callback

handle_fq_out/2

Specs

handle_fq_out(Time :: integer(), State :: any()) ->
                 {SendTime :: integer(),
                  From :: {pid(), Tag :: any()},
                  Value :: any(),
                  Ref :: reference(),
                  NState :: any(),
                  TimeoutTime :: integer() | infinity} |
                 {empty, NState :: any(), RemoveTime :: integer() | infinity}.