Module squeue

This module provides sojourn-time based active queue management with a similar API to OTP's queue module.

This module defines the squeue behaviour.
Required callback functions: init/1, handle_timeout/3, handle_out/3, handle_join/3.

Description

This module provides sojourn-time based active queue management with a similar API to OTP's queue module.

A subset of the squeue API is a subset of the queue module's API with one exception: when {value, Item} is returned by queue, squeue returns {SojournTime, Item}, where SojournTime (non_neg_integer()) is the sojourn time of the item (or length of time an item waited in the queue).

squeue also provides an optional first argument to some functions in common with queue: Time. This argument is of type non_neg_integer() and sets the current time of the queue, if Time is greater than (or equal) to the queue's previous time. When the Time argument is included items may be dropped by the queue's management algorithm. The dropped items will be included in the return value when the queue itself is also returned. The dropped items are a list of the form: [{SojournTime, Item}], which is ordered with the item with the greatest SojournTime (i.e. the oldest) at the head.

squeue includes 3 queue management algorithms: squeue_naive, squeue_timeout, squeue_codel.

Data Types

squeue()

abstract datatype: squeue(Item)

squeue()

squeue() = squeue(term())

Function Index

filter/2Applys a fun, Filter, to all items in the queue, S, and returns the resulting queue, NS.
filter/3Advances the queue, S, to time Time and drops items, then applys a fun, Filter, to all remaining items in the queue.
in/2Inserts the item, Item, at the tail of queue, S.
in/3Advances the queue, S, to time Time and drops item, then inserts the item, Item, at the tail of queue, S.
is_queue/1Tests if a term, Term, is an squeue queue, returns true if is, otherwise false.
join/2Joins two queues, S1 and S2, into one queue, NS, with the items in S1 at the head and the items in S2 at the tail.
len/1Returns the length of the queue, S.
new/0Returns an empty queue, S, with the squeue_naive management algorithm, and time of 0.
new/1Returns a tuple containing an empty list of dropped items, Drops, and an empty queue, S, with the squeue_naive management algorithm, and time of Time.
new/2Returns an empty queue, S, with the Module management algorithm started with arguments Args and time of 0.
new/3Returns a tuple containing an empty list of dropped items, Drops, and an empty queue, S, with the Module management algorithm started with arguments Args and time of Time.
out/1Drops items, Drops, from the queue, S, and then removes the item, Item, from the head of the remaining queue.
out/2Advances the queue, S, to time Time and drops items, Drops, then removes the item, Item, from the head of queue, S.
out_r/1Drops items, Drops, from the queue, S, and then removes the item, Item, from the tail of the remaining queue.
out_r/2Advances the queue, S, to time Time and drops items, Drops, then removes the item, Item, from the tail of queue, S.
time/1Returns the current time , Time, of the queue, S.
timeout/2Advances the queue, S, to time Time and drops item.
to_list/1Returns a list of items, List, in the queue, S.

Function Details

filter/2

filter(Filter, S) -> {Drops, NS}

Applys a fun, Filter, to all items in the queue, S, and returns the resulting queue, NS.

If Filter(Item) returns true, the item appears in the new queue.

If Filter(Item) returns false, the item does not appear in the new queue.

If Filter(Item) returns a list of items, these items appear in the new queue with all items having the start time of the origin item, Item.

filter/3

filter(Time, Filter, S) -> {Drops, NS}

Advances the queue, S, to time Time and drops items, then applys a fun, Filter, to all remaining items in the queue. Returns a tuple containing the dropped items and their sojourn times, Drops, and the new queue, NS.

If Filter(Item) returns true, the item appears in the new queue.

If Filter(Item) returns false, the item does not appear in the new queue.

If Filter(Item) returns a list of items, these items appear in the new queue with all items having the start time of the origin item, Item.

This function raises the error badtime if Time is not a valid time greater than or equal to the current time of the queue, S.

in/2

in(Item, S) -> NS

Inserts the item, Item, at the tail of queue, S. Returns the resulting queue, NS.

in/3

in(Time, Item, S) -> {Drops, NS}

Advances the queue, S, to time Time and drops item, then inserts the item, Item, at the tail of queue, S. Returns a tuple containing the dropped items and their sojourn times, Drops, and resulting queue, NS.

This function raises the error badtime if Time is not a valid time greater than or equal to the current time of the queue, S.

is_queue/1

is_queue(Term) -> Bool

Tests if a term, Term, is an squeue queue, returns true if is, otherwise false.

join/2

join(S1, S2) -> NS

Joins two queues, S1 and S2, into one queue, NS, with the items in S1 at the head and the items in S2 at the tail.

This function raises the error badtime if any item in queue S1 was added after any item in queue S2.

This function raises the error badtime if the current time of the queues, S1 and S2, are not the same.

len/1

len(S) -> Len

Returns the length of the queue, S.

new/0

new() -> S

Returns an empty queue, S, with the squeue_naive management algorithm, and time of 0.

new/1

new(Time) -> {Drops, S}

Returns a tuple containing an empty list of dropped items, Drops, and an empty queue, S, with the squeue_naive management algorithm, and time of Time.

new/2

new(Module, Args) -> S

Returns an empty queue, S, with the Module management algorithm started with arguments Args and time of 0.

new/3

new(Time, Module, Args) -> {Drops, S}

Returns a tuple containing an empty list of dropped items, Drops, and an empty queue, S, with the Module management algorithm started with arguments Args and time of Time.

out/1

out(S) -> {Result, Drops, NS}

Drops items, Drops, from the queue, S, and then removes the item, Item, from the head of the remaining queue. Returns {{SojournTime, Item}, Drops, NS}, where SojournTime is the time length of time Item spent in the queue, Drops is the list of dropped items and their sojourn times and NS is the resulting queue without Drops and Item. If S is empty after dropping items {empty, Drops, S} is returned.

This function is different from queue:out/1, as the sojourn time is included in the result in the place of the atom value and the return value is a 3-tuple with the drop items, Drops, instead of a 2-tuple.

out/2

out(Time, S) -> {Result, Drops, NS}

Advances the queue, S, to time Time and drops items, Drops, then removes the item, Item, from the head of queue, S. Returns {{SojournTime, Item}, Drops, NS}, where SojournTime is the time length of time Item spent in the queue, Drops is the list of dropped items and their sojourn times, and NS is the resulting queue without the removed and dropped items, If the queue is empty after dropping items {empty, Drops, NS} is returned.

This function is slightly different from queue:out/1, as the sojourn time is included in the result in the place of the atom value and items can be dropped.

This function raises the error badtime if Time is not a valid time greater than or equal to the current time of the queue, S.

out_r/1

out_r(S) -> {Result, Drops, NS}

Drops items, Drops, from the queue, S, and then removes the item, Item, from the tail of the remaining queue. Returns {{SojournTime, Item}, Drops, NS}, where SojournTime is the time length of time Item spent in the queue, Drops is the list of dropped items and their sojourn times and NS is the resulting queue without Drops and Item. If S is empty after dropping items {empty, Drops, S} is returned.

This function is different from queue:out_r/1, as the sojourn time is included in the result in the place of the atom value and the return value is a 3-tuple with the drop items, Drops, instead of a 2-tuple.

out_r/2

out_r(Time, S) -> {Result, Drops, NS}

Advances the queue, S, to time Time and drops items, Drops, then removes the item, Item, from the tail of queue, S. Returns {{SojournTime, Item}, Drops, NS}, where SojournTime is the time length of time Item spent in the queue, Drops is the list of dropped items and their sojourn times and NS is the resulting queue without the removed and dropped items, If the queue is empty after dropping items {empty, Drops, NS} is returned.

This function is slightly different from queue:out_r/1, as the sojourn time is included in the result in the place of the atom value and items can be dropped.

This function raises the error badtime if Time is not a valid time greater than or equal to the current time of the queue, S.

time/1

time(S) -> Time

Returns the current time , Time, of the queue, S.

timeout/2

timeout(Time, S) -> {Drops, NS}

Advances the queue, S, to time Time and drops item. Returns a tuple containing the dropped items and their sojourn times, Drops, and resulting queue, NS.

This function raises the error badtime if Time is not a valid time greater than or equal to the current time of the queue, S.

to_list/1

to_list(S) -> List

Returns a list of items, List, in the queue, S.

The order of items in List matches their order in the queue, S, so that the item at the head of the queue is at the head of the list.


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