diff --git a/README.md b/README.md new file mode 100644 index 0000000..1626f2c --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +# RingBuf + +RingBuf is an allocator-agnostic, non-overwriting circular/ring buffer +implementation in C99. +See: [Circular Buffer (Wikipedia)](https://en.wikipedia.org/wiki/Circular_buffer) + +## Features +- Space Efficiency +The code is designed to be portable and flexible. The inspiration initially +came to me when designing a network driver. When operating in memory +constrained environments, every byte is of upmost importance. Traditional +metaprogramming such as templating in C++ and template metaprogramming in C, +although generic has the side effect of expanding into discrete machine code +specific for the specialization applied, essentially scaling (spatially) linear +with the amount of different datatypes we specialize on. This implementation +circumvents this by treating all data as a void pointer with a length. This +implies **no deep copies**. + +- Allocator Agnostic +Another common characteristic of memory constrained environments are +custom malloc implementations and/or variations. + - Signatures + - Arena + +## Design considerations +- Holding a reference to malloc internally would make a tidier interface +- Passing a user-defined function for deep-copies would enable certain applications + +## Usage +In essence: +```c +int value = 42; +struct RingBuf rb; +rb_init(&rb, 10, malloc, sizeof(int)); +rb_push_back(&rb, (void *)&data, memcpy); +rb_pop_front(&rb, &value, memcpy); +``` +Most of these functions return Enum result types. See: +[ringbuf.h](./ringbuf.h). + +## Future Improvements +- Trim the code +- Reduce boilerplate in tests +- Reduce the number of tests in exchange for better test fit