diff options
Diffstat (limited to 'ls_queue.h')
| -rw-r--r-- | ls_queue.h | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/ls_queue.h b/ls_queue.h new file mode 100644 index 0000000..0e5fb8f --- /dev/null +++ b/ls_queue.h @@ -0,0 +1,167 @@ +#pragma once + +/* Lion's Standard (LS) type-safe ANSI C queue. + * + * Version: 1.0 + * Repo: https://github.com/lionkor/ls_queue + * SPDX-License-Identifier: MIT + * + * ==== TABLE OF CONTENTS ==== + * + * 1. DESCRIPTION + * 2. HOW TO USE + * 3. LICENSE + * + * ==== 1. DESCRIPTION ==== + * + * A minimal, terse, generic (macro code generated) header-only library in ANSI + * C, which implements a queue. + * + * The implementation does not allocate, and uses a ring-buffer (aka a circular + * buffer) to avoid copying and moving memory. + * + * ==== 2. HOW TO USE ==== + * + * Statically sized, type-safe queue. + * + * Use LS_QUEUE_INLINE to generate a static inline version of the library. + * This is the "default" behavior. + * + * If you need a declaration and implementation separately, use + * LS_QUEUE_DECL and make sure to call it with the same arguments as + * LS_QUEUE_IMPL. Put LS_QUEUE_DECL in a header, and LS_QUEUE_IMPL in exactly + * ONE source file. + * + * Simple example: + * + * LS_QUEUE_TYPE_INLINE(int, int_queue, 32) + * + * // somewhere in the same file + * int_queue q; + * int_queue_init(&q); + * int_queue_push(&q, 42); + * int val; + * if (int_queue_pop(&q, &val)) { + * // do something with val + * } + * + * Alternative example with decl and inline split: + * + * // In your header file: + * LS_QUEUE_CAP_DECL(int, int_queue, 32) + * + * // In one source file: + * LS_QUEUE_CAP_IMPL(int, int_queue, 32) + * + * // Usage in your code: + * int_queue q; + * int_queue_init(&q); + * if (!int_queue_push(&q, 42)) { + * // handle queue full + * } + * int val; + * if (int_queue_pop(&q, &val)) { + * // do something with val + * } + * + * ==== 3. LICENSE ==== + * + * This file is provided under the MIT license. For commercial support and + * maintenance, feel free to use the e-mail below to contact the author(s). + * + * The MIT License (MIT) + * + * Copyright (c) 2026 Lion Kortlepel <[email protected]> + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the “Software”), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#include <assert.h> +#include <stddef.h> + +#define LS_QUEUE_TYPE_INLINE(T, name, cap) \ + typedef struct name##_##cap { \ + T data[(cap) + 1]; \ + size_t read; \ + size_t write; \ + } name; \ + _ls_QUEUE_TYPE_IMPL_DETAIL(T, name, cap, static inline) + +#define LS_QUEUE_TYPE_IMPL(T, name, cap) \ + _ls_QUEUE_TYPE_IMPL_DETAIL(T, name, cap, ) + +#define LS_QUEUE_TYPE_DECL(T, name, cap) \ + typedef struct name##_##cap { \ + T data[(cap) + 1]; \ + size_t read; \ + size_t write; \ + } name; \ + void name##_init(name* q); \ + /* Returns 0 if full, 1 if successful. */ \ + int name##_push(name* q, T val); \ + /* Returns 0 if empty, 1 if successful. */ \ + int name##_pop(name* q, T* out); + +/* DO NOT USE. Use LS_QUEUE_TYPE_INLINE or LS_QUEUE_TYPE_{IMPL,DECL} instead. + * + * What follows is some ramblings about the implementation. + * + * You might notice that the queue struct has two different names, once the + * normal name, e.g. `int_queue`, and once a name with size, `struct + * int_queue_16`. You might further notice that the functions take the sized + * version, not the typedef'd version. + * + * While this might seem odd, its essentially a poor-man's way to ensure that, + * if two different int_queue structs are declared, only the one that is defined + * for will work, and the error should make it painfully clear. For example: + * + * > In included file: typedef redefinition with different types ('struct + * int_queue_18' vs 'struct int_queue_16') (clang + * redefinition_different_typedef) + */ +#define _ls_QUEUE_TYPE_IMPL_DETAIL(T, name, cap, specifier) \ + specifier void name##_init(struct name##_##cap* q) { \ + assert(q != NULL); \ + q->read = 0; \ + q->write = 0; \ + } \ + /* Returns 0 if full, 1 if successful. */ \ + specifier int name##_push(struct name##_##cap* q, T val) { \ + assert(q != NULL); \ + size_t size = sizeof(q->data) / sizeof(T); \ + size_t new_write = (q->write + 1) % size; \ + if (new_write == q->read) { \ + return 0; \ + } \ + q->data[q->write] = val; \ + q->write = new_write; \ + return 1; \ + } \ + /* Returns 0 if empty, 1 if successful. */ \ + specifier int name##_pop(struct name##_##cap* q, T* out) { \ + assert(q != NULL); \ + assert(out != NULL); \ + size_t size = sizeof(q->data) / sizeof(T); \ + if (q->read == q->write) { \ + return 0; \ + } \ + *out = q->data[q->read]; \ + q->read = (q->read + 1) % size; \ + return 1; \ + } |