util.queue

This library implements a FIFO (first in, first out) queue with a fixed size limit. This is simply an ordered list of items (Lua values), where it is possible to easily add items to the beginning, and remove them from the end.

Example uses include:

Keeping track of tasks that need to be done, or data that need to be processed
Historical logging of anything, where you want to be able to store just the most recent N items/events

Standard Lua tables can be used for the same purpose (using table.insert and table.remove), but util.queue provides several advantages:

The speed of adding and removing items does not vary depending on the number of stored items (table.insert/table.remove can be slow on large lists)
Fixed size limit prevents the queue growing infinitely, and gives feedback to inserting code to allow back pressure

Usage

    local queue = require "util.queue";
 
    -- Create a queue that can hold up to 3 items
    local myqueue = queue.new(3);
 
    -- Add three items to the queue
    myqueue:push("red");
    myqueue:push("green");
    myqueue:push("blue");
 
    print(myqueue:count()) --> 3
 
    -- Trying to add another item returns an error:
    print(myqueue:push("yellow")) --> nil, "queue full"
 
    -- Retrieve the oldest item back from the queue
    print(myqueue:pop()) --> "red"
    print(myqueue:pop()) --> "green"
    print(myqueue:pop()) --> "blue"
 
    -- The queue is now empty again
    print(myqueue:count()) --> 0

By passing true as the second parameter to new(), when the queue is full, the oldest item is automatically removed. This is known as a circular buffer or 'ring buffer', and is an efficient way to cache recent values. Note: if you need the same functionality, but with key→value pairs instead of a simple list, see util.cache.

Reference

new(max_items, allow_wrapping)

Creates and returns a new queue, capable of holding up to max_items values. If allow_wrapping is provided and not nil or false, when the queue is full it will automatically overwrite the oldest item instead of returning an error.

queue:push(value)

Adds a new value to the queue. Returns true on success. If the queue does not allow wrapping, it may return nil, "queue full" when there is no space left in the queue for the new item. Otherwise, adding items will always succeed.

queue:pop()

Removes the oldest item from the queue and returns it.

queue:count()

Returns the number of items currently in the queue.

queue:items()

Returns an iterator such that the following code would print out every item currently in the queue, with its position (starting from 1):

    for position, value in myqueue:items() do
        print(position, value)
    end