Queue Component for Livt

This package provides a fixed-size FIFO queue in Livt for small byte-oriented buffering needs.

This repository is intentionally small, so the core design rationale is captured directly in this README rather than a separate design note.

📋 Overview

The current package is organized around one main component:

• Queue stores up to 32 entries of logic[8] using circular-buffer indexing to preserve FIFO ordering across wrap-around.

The queue is currently fixed to:

• 32 elements of storage
• 8-bit logic[8] queue entries

The public API is intentionally small and centered on predictable FIFO behavior:

• Enqueue() appends when space is available.
• Dequeue() removes the oldest queued element.
• Peek() reads the oldest queued element without removing it.
• IsEmpty(), IsFull(), and GetSize() expose queue state.
• Clear() resets the queue to an empty state.

📁 Project Structure

.
├── src/
│   └── Queue.lvt
├── tests/
│   └── QueueTest.lvt
├── LICENSE
├── README.md
└── livt.toml

🔨 Building

Build the package with:

livt build

The package configuration is defined in livt.toml. The current project name there is Queue.

🧪 Running Tests

Run the full test suite with:

livt test

Configured test components:

• QueueTest

📚 Component Guide

Queue

Small fixed-size FIFO queue in the Livt.Collections namespace.

Features:

• circular-buffer storage
• FIFO dequeue order
• explicit empty and full state checks
• defined empty-queue return value for Peek() and Dequeue()

Public methods:

• Enqueue(element: logic[8])
• Dequeue() logic[8]
• Peek() logic[8]
• IsEmpty() bool
• IsFull() bool
• GetSize() int
• Clear()

Enqueue() is ignored when the queue is full. Dequeue() and Peek() return 0b0000_0000 when the queue is empty.

💡 Example

using Livt.Collections

component Example
{
    queue: Queue

    new()
    {
        this.queue = new Queue()
    }

    public fn PushAndPop(value: logic[8]) logic[8]
    {
        this.queue.Enqueue(value)
        return this.queue.Dequeue()
    }
}

🔧 Configuration

This package does not currently expose configurable width or depth parameters.

To change the queue shape today, update the fixed constants and storage type in:

• src/Queue.lvt

If the queue contract changes, the expected behavior should also be updated in:

• tests/QueueTest.lvt

📝 Notes

• The package is intentionally minimal and focused on predictable FIFO behavior.
• The queue implementation uses circular-buffer indexing rather than shifting data.
• The empty-queue fallback value is currently fixed to 0b0000_0000.

🤝 Contributing

Contributions are welcome. Areas that would be natural extensions for this package include:

• configurable queue depth
• configurable entry width
• explicit overflow reporting for rejected Enqueue() calls
• alternative empty-read behavior beyond returning 0b0000_0000
• convenience wrappers for common buffering patterns

📄 License

This project is licensed under the MIT License. See LICENSE.