Use fixed-size circular buffer for queue

Author: dpolugic

src/draw.ts

@@ -91,17 +91,25 @@ type QueueEntry = {
   depth: number
 }
 
+// We'll use a global queue to avoid reallocating it on every preview frame.
+const patternQueue = new Queue<QueueEntry>({
+  initialItems: [],
+  size: MAX_QUEUE_SIZE,
+})
+
 function* generateDrawQueue(state: State): Generator<QueueEntry, void, void> {
   console.log(
     `generateDrawQueue start. Initial screens: ${state.screens.length}, Patterns: ${state.patterns.length}`
   )
 
-  const patternQueue = new Queue<QueueEntry>(
-    state.screens.map(screen => ({
+  patternQueue.clear()
+
+  for (const screen of state.screens) {
+    patternQueue.push({
       currentPattern: screen,
       depth: 0,
-    }))
-  )
+    })
+  }
 
   let iterations = 0
   while (patternQueue.size > 0) {
@@ -127,14 +135,15 @@ function* generateDrawQueue(state: State): Generator<QueueEntry, void, void> {
           currentPattern: virtualScreen,
           depth: entry.depth + 1,
         })
+
+        // Give up if queue becomes too large.
+        if (patternQueue.size >= MAX_QUEUE_SIZE) {
+          console.warn('Maximum queue size reached. Rendering cancelled.')
+          return
+        }
       }
     }
 
-    // Give up if queue becomes too large.
-    if (patternQueue.size > MAX_QUEUE_SIZE) {
-      console.warn('Maximum queue size reached. Rendering cancelled.')
-      return
-    }
   }
 
   console.log(

src/queue.test.ts

@@ -5,25 +5,34 @@ import { Queue } from './queue';
 
 describe('Queue', () => {
   it('should initialize an empty queue', () => {
-    const queue = new Queue<number>();
+    const queue = new Queue<number>({ size: 5 });
     expect(queue.size).toBe(0);
   });
 
   it('should initialize a queue with initial items', () => {
-    const queue = new Queue<number>([1, 2, 3]);
+    const queue = new Queue<number>({ initialItems: [1, 2, 3], size: 3 });
     expect(queue.size).toBe(3);
   });
 
-  it('should push items to the queue', () => {
-    const queue = new Queue<string>();
+  it('should throw an error if initial items exceed capacity', () => {
+    expect(() => new Queue<number>({ initialItems: [1, 2, 3, 4], size: 3 })).toThrow('Initial items exceed queue capacity');
+  });
+
+  it('should push items to the queue up to its capacity', () => {
+    const queue = new Queue<string>({ size: 2 });
     queue.push('a');
     expect(queue.size).toBe(1);
     queue.push('b');
     expect(queue.size).toBe(2);
   });
 
+  it('should throw an error when pushing to a full queue', () => {
+    const queue = new Queue<string>({ initialItems: ['a'], size: 1 });
+    expect(() => queue.push('b')).toThrow('Queue is full');
+  });
+
   it('should shift items from the queue in FIFO order', () => {
-    const queue = new Queue<number>([1, 2, 3]);
+    const queue = new Queue<number>({ initialItems: [1, 2, 3], size: 3 });
     expect(queue.shift()).toBe(1);
     expect(queue.size).toBe(2);
     expect(queue.shift()).toBe(2);
@@ -33,12 +42,12 @@ describe('Queue', () => {
   });
 
   it('should throw an error when shifting from an empty queue', () => {
-    const queue = new Queue<number>();
+    const queue = new Queue<number>({ size: 5 });
     expect(() => queue.shift()).toThrow('Queue is empty');
   });
 
   it('should handle a mix of push and shift operations correctly', () => {
-    const queue = new Queue<string>();
+    const queue = new Queue<string>({ size: 2 });
     queue.push('one');
     queue.push('two');
     expect(queue.shift()).toBe('one');
@@ -50,10 +59,23 @@ describe('Queue', () => {
   });
 
   it('should report correct size after multiple pushes and shifts', () => {
-    const queue = new Queue<number>([1, 2]);
+    const queue = new Queue<number>({ initialItems: [1, 2], size: 5 });
     queue.push(3);
     expect(queue.size).toBe(3);
-    queue.shift(); // 1
+    queue.shift();
+    expect(queue.size).toBe(2);
+    queue.push(4);
+    expect(queue.size).toBe(3);
+    expect(queue.shift()).toBe(2);
+    expect(queue.shift()).toBe(3);
+    expect(queue.shift()).toBe(4);
+    expect(queue.size).toBe(0);
+  });
+
+  it('should allow pushing after shifting from a full queue', () => {
+    const queue = new Queue<number>({ initialItems: [1, 2, 3], size: 3 });
+    expect(queue.size).toBe(3);
+    expect(queue.shift()).toBe(1);
     expect(queue.size).toBe(2);
     queue.push(4);
     expect(queue.size).toBe(3);
@@ -62,4 +84,59 @@ describe('Queue', () => {
     expect(queue.shift()).toBe(4);
     expect(queue.size).toBe(0);
   });
+
+  it('should throw if initializing with more items than queue size', () => {
+    expect(() => new Queue<number>({ initialItems: [1, 2], size: 1 })).toThrow('Initial items exceed queue capacity');
+  });
+
+  it('should throw if initializing with non-positive size', () => {
+    expect(() => new Queue<number>({ size: 0 })).toThrow('Queue size must be positive');
+  });
+
+  it('should handle operations on a queue of size 1', () => {
+    const queue = new Queue<number>({ size: 1 });
+    expect(queue.size).toBe(0);
+
+    queue.push(10);
+    expect(queue.size).toBe(1);
+    expect(() => queue.push(20)).toThrow('Queue is full');
+
+    expect(queue.shift()).toBe(10);
+    expect(queue.size).toBe(0);
+    expect(() => queue.shift()).toThrow('Queue is empty');
+
+    queue.push(30);
+    expect(queue.size).toBe(1);
+    expect(queue.shift()).toBe(30);
+  });
+
+  it('should correctly handle fill-empty-fill-empty cycles (circular buffer integrity)', () => {
+    const queue = new Queue<number>({ size: 3 });
+
+    // Fill 1
+    queue.push(1);
+    queue.push(2);
+    queue.push(3);
+    expect(queue.size).toBe(3);
+    expect(() => queue.push(4)).toThrow('Queue is full');
+
+    // Empty 1
+    expect(queue.shift()).toBe(1);
+    expect(queue.shift()).toBe(2);
+    expect(queue.shift()).toBe(3);
+    expect(queue.size).toBe(0);
+    expect(() => queue.shift()).toThrow('Queue is empty');
+
+    // Fill 2 (after wrapping)
+    queue.push(10);
+    queue.push(20);
+    queue.push(30);
+    expect(queue.size).toBe(3);
+
+    // Empty 2
+    expect(queue.shift()).toBe(10);
+    expect(queue.shift()).toBe(20);
+    expect(queue.shift()).toBe(30);
+    expect(queue.size).toBe(0);
+  });
 }); 

src/queue.ts

@@ -1,19 +1,42 @@
+/**
+ * A fixed-size queue, backed by a circular buffer.
+ */
 export class Queue<T> {
-  #queue: T[] = []
+  #buffer: (T | undefined)[] = []
   #head = 0
+  #tail = 0
   #size = 0
 
-  constructor(items: T[] = []) {
-    this.#queue = items
-    this.#size = items.length
+  constructor({initialItems = [], size}: { initialItems?: T[], size: number}) {
+    if (size <= 0) {
+      throw new Error('Queue size must be positive')
+    }
+
+    if (initialItems.length > size) {
+      throw new Error('Initial items exceed queue capacity')
+    }
+
+    this.#buffer = new Array(size).fill(undefined)
+
+    for (let i = 0; i< initialItems.length; i++) {
+      this.#buffer[i] = initialItems[i]
+    }
+
+    this.#size = initialItems.length
+    this.#tail = initialItems.length
   }
 
   get size() {
     return this.#size
   }
 
   push(value: T) {
-    this.#queue.push(value)
+    if (this.#size === this.#buffer.length) {
+      throw new Error('Queue is full')
+    }
+
+    this.#buffer[this.#tail] = value
+    this.#tail = (this.#tail + 1) % this.#buffer.length
     this.#size++
   }
 
@@ -22,19 +45,17 @@ export class Queue<T> {
       throw new Error('Queue is empty')
     }
 
-    const value = this.#queue[this.#head]!
+    const value = this.#buffer[this.#head]!
 
-    this.#head++
+    this.#head = (this.#head + 1) % this.#buffer.length
     this.#size--
 
     return value
   }
 
-  /**
-    * Compact the queue to make sure it doesn't grow indefinitely.
-    */
-  compact() {
-    this.#queue = this.#queue.slice(this.#head)
+  clear() {
     this.#head = 0
+    this.#tail = 0
+    this.#size = 0
   }
 }