Lunatik
Lua API · Runtime

fifoModule

kfifo (kernel FIFO) implementation.

This library allows creating and managing fixed-size FIFO queues for byte streams, suitable for producer-consumer scenarios within the kernel. Each call takes the object’s lock, so one fifo can be shared between runtimes, as through runtime:resume, and used from softirq.

Class fifo

fifo:close () Closes and releases the FIFO object.
fifo:pop (size) Pops data from the FIFO.
fifo:push (data) Pushes data into the FIFO.

fifo

new (size) Creates a new kernel FIFO (kfifo) object.

Class fifo in detail

Represents a kernel FIFO (kfifo) object. This is a userdata object returned by fifo.new(). It encapsulates a struct kfifo from the Linux kernel, providing a first-in, first-out byte queue.
fifo:close ()
Closes and releases the FIFO object. It also runs when a to-be-closed variable holding the object goes out of scope. Later calls raise “closed object”.

Returns

    nil

Raises

“not allowed with IRQs disabled” when called with IRQs disabled, as in every callback of a hardirq runtime, a probe’s handlers among them, where a buffer from vmalloc cannot be freed, and so does the end of the scope of a <close> variable holding the fifo there; the fifo is then released with its last reference.
fifo:pop (size)
Pops data from the FIFO. Retrieves a specified number of bytes from the FIFO.

Parameters

  • size integer maximum number of bytes to retrieve from the FIFO, up to its capacity.

Returns

  1. string A string containing the bytes popped from the FIFO. The actual length of this string might be less than size if the FIFO contained fewer bytes.
  2. integer actual number of bytes popped from the FIFO.

Raises

Error if size is out of bounds.

See also

Usage

-- Assuming 'myfifo' is a fifo object
local data, len = myfifo:pop(10)
if len > 0 then
  print("Popped " .. len .. " bytes: " .. data)
end
fifo:push (data)
Pushes data into the FIFO. Copies a string of bytes into the FIFO, whole or not at all.

Parameters

  • data string bytes to push into the FIFO, up to its capacity.

Returns

    boolean true if the FIFO took the bytes, false if it has no room for them all.

Raises

“out of bounds” for a string longer than the FIFO’s capacity, which no pop makes room for.

See also

Usage

-- Assuming 'myfifo' is a fifo object
if not myfifo:push("hello") then
  print("full")
end

fifo in detail

new (size)
Creates a new kernel FIFO (kfifo) object. Allocates and initializes a kfifo of the specified size. The size should ideally be a power of two for kfifo’s internal optimizations, though a non-power-of-two size is rounded up. In a process runtime, and in the body of a softirq or hardirq runtime, a buffer larger than a page may come from vmalloc, which needs no physically contiguous pages; past that body, the buffer needs them.

Parameters

  • size integer desired capacity of the FIFO in bytes, from 2 up to KMALLOC_MAX_SIZE.

Returns

    fifo A new fifo object.

Raises

Error if size is out of bounds; “not enough memory” if the kernel cannot allocate the buffer.

Usage

local myfifo = fifo.new(1024) -- Creates a FIFO with a capacity of 1024 bytes