Usage Guide

NOTE: This wiki is getting updated soon to provide details regarding all 23 functions/macros

See here for details.

---

Getting Started

First, load the library into your project:

(ql:quickload :cl-freelock)

Unbounded MPMC Queue

The queue is a multi-producer, multi-consumer (MPMC) queue that can grow indefinitely. It is a good general purpose choice when the number of items is unpredictable.

When to use: General-purpose, thread-safe communication where capacity is not a concern.

;; Create the queue  
(defvar \*q\* (cl-freelock:make-queue))

;; Push an item from any thread  
(cl-freelock:queue-push *q* 100)

;; Pop an item from any thread  
(multiple-value-bind (obj success) (cl-freelock:queue-pop *q*)  
 (when success  
 (print obj)))  
;; \=\> 100  

Bounded MPMC Queue

The bounded-queue is an MPMC queue with a fixed capacity set at creation. Its capacity must be a power of two.

When to use: When you need to apply backpressure (i.e., prevent producers from getting too far ahead of consumers) or when you have predictable capacity requirements. The fixed-size buffer can also lead to better memory locality.

;; Create a queue with a capacity of 1024  
(defvar *bq* (cl-freelock:make-bounded-queue 1024))

;; Push a single item  
(cl-freelock:bounded-queue-push *bq* :hello)

;; Pop a single item  
(cl-freelock:bounded-queue-pop *bq*)  
;; \=\> :HELLO, T

;; Push a batch of items at once for higher throughput  
(cl-freelock:bounded-queue-push-batch *bq* '(1 2 3))

;; Pop a batch of up to 3 items  
(cl-freelock:bounded-queue-pop-batch *bq* 3)  
;; \=\> (1 2 3), T  

Bounded SPSC Queue

The spsc-queue is a highly specialized bounded queue for use with a single producer thread and a single consumer thread. Using it with multiple producers or consumers will result in incorrect behavior.

When to use: For maximum performance in a two-thread pipeline. It is significantly faster than the general-purpose MPMC queues.

;; Create an SPSC queue with a capacity of 2048  
(defvar *spsc-q* (cl-freelock:make-spsc-queue 2048))

;; This must only be called from your designated producer thread  
(cl-freelock:spsc-push *spsc-q* "world")

;; This must only be called from your designated consumer thread  
(cl-freelock:spsc-pop *spsc-q*)  
;; \=\> "world", T