As data stores go go this is basically in memory only. The save and load process is manually triggered by the user and the save process isn't crash safe nor does it do any integrity checks.
I also don't think it has any indexes either? So search performance is a function of the number of entries.
Does declaring a function as inline do anything for any modern compiler? I understood that this is basically ignored now and is the compiler makes its own decisions based on what is fastest.
This library seems to have the annotation on every function, though, so it's possible the author is just following a convention of always using it for functions defined in header files (it'd be required if the functions weren't declared `static`).
In the former case the compiler is allowed to always inline the function.
In the latter case, even when the compiler chooses to inline the function, it also emits code for an independent instance of the function, because the function is public and it may be called from another file.
So "static inline" in the worst case does nothing, but it suggests to the compiler that the function should be inlined everywhere, which it will probably do, unless it decides that the function is too long (or it uses some features forbidden in inlined functions, e.g. variadic arguments, setjmp, alloca, etc.), so the benefits of inlining it may be less than the disadvantages.
When the compiler refuses to follow the suggestion of inlining the function, it can be made to tell the reason, e.g. with "-Winline".
So the compiler does not ignore the suggestion, even if it may choose to not follow it.
>In the latter case, even when the compiler chooses to inline the function, it also emits code for an independent instance of the function, because the function is public and it may be called from another file.
Not in standard C. "inline" function provides implementation for usage iff compiler decides to inline the call. If it does decide not to inline, it will emit call to external symbol that needs to be defined in different TU (otherwise you will get errors at link time).
The meaning of "inline" differs between C and C++.
Quote from the gcc manual:
"GCC implements three different semantics of declaring a function inline. One is available with -std=gnu89 or -fgnu89-inline or when gnu_inline attribute is present on all inline declarations, another when -std=c99, -std=gnu99 or an option for a later C version is used (without -fgnu89-inline), and the third is used when compiling C++."
Nevertheless, "static inline" means the same thing in all 3 standards, unlike "inline" alone.
This can be a reason to always prefer "static inline", because then it does not matter whether the program is compiled as C or as C++.
It is not a benefit if you do not get warnings about unused functions. With any proper library, you would also not get warnings for functions that are part of the API that are not used, but you would get warnings about non-exported functions internal to a translation unite that are accidentally not used. This is a good thing.
In the world of Kubernetes and languages where a one-liner brings in a graph of 1700 dependencies, and oceans of Yaml, it's suddently important for a C thing to be one file rather than two.
C libraries have advertised "header-only" for a long time, it's because there is no package manager/dependency management so you're literally copying all your dependencies into your project.
This is also why everyone implements their own (buggy) linked-list implementations, etc.
And header-only is more efficient to include and build with than header+source.
> And header-only is more efficient to include and build with than header+source.
Dispute.
This is C code. You can't just drop it in and build it; you have to write code to use it. You have to figure out the API to correctly use it. If memory is passed around by pointers, you have to understand the responsibilities: who allocates, who frees, who may touch what when.
In the first place, you have to decide whether to commit to that library that far; it might not be until you've done some exploratory programming with it that you want to scrap it and find another one.
The cost of adding two files versus one is practically nothing in consideration of the larger picture.
The separate header model is baked into the C mindset; the tooling readily supports it.
Many "header only" libraries are secretly two files in one. When you define a certain preprocessor symbol before including the file, you get the implementation bits. When you don't define that symbol, the header is a pure header.
That means you have to pick some existing .c file which will define the preprocessor symbol and include the heaader. That source file becomes a "surrogate" source file, taking the place of the source file it ought to have.
There's a number of extremely shitty vendor toolchain/IDE combos out there that make adding and managing dependencies unnecessarily painful. Things like only allowing one project to be open at a time, or compiler flags needing to be manually copied to each target.
Now that I'm thinking about it, CMake also isn't particularly good at this the way most people use it.
They are certainly bad vendor toolchain, but I want to push back against the idea that this is a general C problem. But even for the worst toolchains I have seen, dropping in a pair of .c/.h would not have been difficult. So it is still difficult to see how a header-only library makes a lot of sense.
One of the worst I've experienced had a bug where adding too many files would cause intermittent errors. The people affected resorted to header-izing things. Was an off-by-one in how it was constructing arguments to subshells, causing characters to occasionally drop.
But, more commonly I've seen that it's just easier to not need to add C files at all. Add a single include path and you can avoid the annoyances of vendoring dependencies, tracking upstream updates, handling separate linkage, object files, output paths, ABIs, and all the rest. Something like Cargo does all of this for you, which is why people prefer it to calling rustc directly.
People certainly sometimes create a horrible mess. I just do not see that this is a good reason to dumb everything down. With a proper .c/.h split there are many advantages, and in the worst case you could still design it in a way that it is possible "#include" the .c file.
I tried to use cargo in the past and found it very bad compared to apt / apt-get (even when ignoring that it is a supply-chain disaster), essentially the same mess as npm or pip. Some python packages certainly wasted far more time of my life than all dependencies for C projects I ever had deal with combined.
I consider it compiler abuse to #include a source file. Useful for IOCCC competitions though.
Apt is fine for local development, but it's a bit of a disaster for portability and reproducibility. Not uncommon to see a project where the dependencies either have unspecified versions whose latest versions in universe are incompatible, or where the package has been renamed and so you have to search around to find the new name. Plus package name conventions are terrible. libbenchmark-dev, libgoogle-perftools-dev, and libgtest-dev are all library packages from the same company. The second one is renamed to gperftools-lib with RPM repos, to further compound the inconsistency.
I find myself dealing with package and versioning rename issues regularly in the CI pipelines I have using apt.
Well, I consider it abuse of header files to put an implementation in there. And comparing including a c-file to IOCCC seems very exaggerated.
My experience with dependencies in Debian-derived distributions is actually very good, far less problematic than any other packaging system I ever used. But yes, one needs to maintain dependencies separately for RPM and others distributions. But obviously the problem is not lack of a package manager and adding another one would not solve anyhing: https://xkcd.com/927/ The solution would be standardizing package names and versions across distributions.
I feel like there's two kinds of developers. The ones who shit all over other people's preferences and turn everything into an almost religious discussion, and the ones who prefer to just build stuff.
Only if people provide reasons for why they think it is bad, but with people along the lines of "Header-only? Eww. Sucks." you cannot.
To comment on this, I have a couple of header-only projects I have written. It makes sense in some scenarios. Sometimes I want no external dependencies and a single header file interface.
It's a tradeoff people make between ease of integration - just download the .h file into your project folder and #include it in your source file instead of worrying about source build system vs target build system, cross compiling headaches etc...
And compilation times: any time you change any of your source files, your compiler also has to recompile your dependencies. (Assuming you haven't used precompiled headers).
I'm completely ignorant about this, but wouldn't it be possible to compile separately your project to improve compilation times? for instance, if you're using OP's vector library, which is self contained, you could compile that first and just once?
int add(int a, int b){
// Long logic and then this
return a+b;
}
Let's say this is your main.c.
#include "add.h"
int main(void) {
return add(5,6);
}
The preprocessor just copies the contents of add.h into your main.c whenever you're trying to compile main.c. (let's ignore the concept of precompiled headers for now).
What you can instead do is just put the add function declaration in add.h that just tells the compiler that add function takes two integers and returns an integer.
int add(int a, int b);
You can then put the add function definition in add.c , compile that to an add.o and link it to your main.o at link time to get your final binary - without having to recompile add.o every time you change your main.c.
Recompiling the dependencies should only really happen if you change the file with the implementation include (usually done by defining <library>_IMPLEMENTATION or something like that.
It often also means it was written more correctly. There is a bit of an art to designing a header only library and it can strike a different balance between code size and runtime speed optimization.
In strict terms when you place implementation in a .c file you probably want that code to be shared when different things call it, and the compiler will "link" to that same implementation.
When you have a header only library the compiler is free to optimize in more ways specific to your actual use case.
C's package management story is unfriendly to say the least. A header only library simplifies it dramatically, and makes it much more straightforward to integrate dependencies into your application.
Brute-force kNN gets a bad reputation, but below ~50K vectors the overhead of building and maintaining an HNSW index often costs more than it saves, especially for infrequent queries. I use sqlite-vec (also flat scan by default) in production with 10K vectors at 384 dimensions and search takes under 5ms.
The low-hanging fruit for this library would be SIMD. At 128d float32, each distance computation touches 512 bytes of data. AVX2 processes 8 floats per cycle, NEON does 4. That's a 4-6x speedup on the hot path without changing the algorithm at all. For a header-only library where simplicity is the point, that seems like the right optimization to reach for before adding approximate indexing.
One gotcha: metadata isn't persisted on save/load. The README mentions the binary format stores vectors and IDs but not metadata. Anyone attaching text chunks to their embeddings for RAG will lose them on reload.
As data stores go go this is basically in memory only. The save and load process is manually triggered by the user and the save process isn't crash safe nor does it do any integrity checks.
I also don't think it has any indexes either? So search performance is a function of the number of entries.
Does declaring a function as inline do anything for any modern compiler? I understood that this is basically ignored now and is the compiler makes its own decisions based on what is fastest.
The idea that it does nothing is a persistent myth. Both GCC and Clang heed it although neither treats it as a mandate:
https://tartanllama.xyz/posts/inline-hints/
This library seems to have the annotation on every function, though, so it's possible the author is just following a convention of always using it for functions defined in header files (it'd be required if the functions weren't declared `static`).
"static inline" is not the same as "inline".
In the former case the compiler is allowed to always inline the function.
In the latter case, even when the compiler chooses to inline the function, it also emits code for an independent instance of the function, because the function is public and it may be called from another file.
So "static inline" in the worst case does nothing, but it suggests to the compiler that the function should be inlined everywhere, which it will probably do, unless it decides that the function is too long (or it uses some features forbidden in inlined functions, e.g. variadic arguments, setjmp, alloca, etc.), so the benefits of inlining it may be less than the disadvantages.
When the compiler refuses to follow the suggestion of inlining the function, it can be made to tell the reason, e.g. with "-Winline".
So the compiler does not ignore the suggestion, even if it may choose to not follow it.
>In the latter case, even when the compiler chooses to inline the function, it also emits code for an independent instance of the function, because the function is public and it may be called from another file.
Not in standard C. "inline" function provides implementation for usage iff compiler decides to inline the call. If it does decide not to inline, it will emit call to external symbol that needs to be defined in different TU (otherwise you will get errors at link time).
The meaning of "inline" differs between C and C++.
Quote from the gcc manual:
"GCC implements three different semantics of declaring a function inline. One is available with -std=gnu89 or -fgnu89-inline or when gnu_inline attribute is present on all inline declarations, another when -std=c99, -std=gnu99 or an option for a later C version is used (without -fgnu89-inline), and the third is used when compiling C++."
Nevertheless, "static inline" means the same thing in all 3 standards, unlike "inline" alone.
This can be a reason to always prefer "static inline", because then it does not matter whether the program is compiled as C or as C++.
One obvious benefit for a header only library is that it suppresses the warning you get when a static function isn't used.
It is not a benefit if you do not get warnings about unused functions. With any proper library, you would also not get warnings for functions that are part of the API that are not used, but you would get warnings about non-exported functions internal to a translation unite that are accidentally not used. This is a good thing.
Kind of. At the end of the day the compiler can do almost anything it wants outside of unrefined behavior, which isn't much of a guard rail.
In reality header only libraries allow for deep inlining, the compiler may optimize very specifically to your code and usage.
The situation is a bit more exaggerated with C++ because of templates, but there is some remaining gains to he had in C alone.
In the world of Kubernetes and languages where a one-liner brings in a graph of 1700 dependencies, and oceans of Yaml, it's suddently important for a C thing to be one file rather than two.
C libraries have advertised "header-only" for a long time, it's because there is no package manager/dependency management so you're literally copying all your dependencies into your project.
This is also why everyone implements their own (buggy) linked-list implementations, etc.
And header-only is more efficient to include and build with than header+source.
> And header-only is more efficient to include and build with than header+source.
Dispute.
This is C code. You can't just drop it in and build it; you have to write code to use it. You have to figure out the API to correctly use it. If memory is passed around by pointers, you have to understand the responsibilities: who allocates, who frees, who may touch what when.
In the first place, you have to decide whether to commit to that library that far; it might not be until you've done some exploratory programming with it that you want to scrap it and find another one.
The cost of adding two files versus one is practically nothing in consideration of the larger picture.
The separate header model is baked into the C mindset; the tooling readily supports it.
Many "header only" libraries are secretly two files in one. When you define a certain preprocessor symbol before including the file, you get the implementation bits. When you don't define that symbol, the header is a pure header.
That means you have to pick some existing .c file which will define the preprocessor symbol and include the heaader. That source file becomes a "surrogate" source file, taking the place of the source file it ought to have.
I never copied my dependencies into my C project, nor does it usually take more than a couple of seconds to add one.
There's a number of extremely shitty vendor toolchain/IDE combos out there that make adding and managing dependencies unnecessarily painful. Things like only allowing one project to be open at a time, or compiler flags needing to be manually copied to each target.
Now that I'm thinking about it, CMake also isn't particularly good at this the way most people use it.
They are certainly bad vendor toolchain, but I want to push back against the idea that this is a general C problem. But even for the worst toolchains I have seen, dropping in a pair of .c/.h would not have been difficult. So it is still difficult to see how a header-only library makes a lot of sense.
One of the worst I've experienced had a bug where adding too many files would cause intermittent errors. The people affected resorted to header-izing things. Was an off-by-one in how it was constructing arguments to subshells, causing characters to occasionally drop.
But, more commonly I've seen that it's just easier to not need to add C files at all. Add a single include path and you can avoid the annoyances of vendoring dependencies, tracking upstream updates, handling separate linkage, object files, output paths, ABIs, and all the rest. Something like Cargo does all of this for you, which is why people prefer it to calling rustc directly.
People certainly sometimes create a horrible mess. I just do not see that this is a good reason to dumb everything down. With a proper .c/.h split there are many advantages, and in the worst case you could still design it in a way that it is possible "#include" the .c file.
I tried to use cargo in the past and found it very bad compared to apt / apt-get (even when ignoring that it is a supply-chain disaster), essentially the same mess as npm or pip. Some python packages certainly wasted far more time of my life than all dependencies for C projects I ever had deal with combined.
I consider it compiler abuse to #include a source file. Useful for IOCCC competitions though.
Apt is fine for local development, but it's a bit of a disaster for portability and reproducibility. Not uncommon to see a project where the dependencies either have unspecified versions whose latest versions in universe are incompatible, or where the package has been renamed and so you have to search around to find the new name. Plus package name conventions are terrible. libbenchmark-dev, libgoogle-perftools-dev, and libgtest-dev are all library packages from the same company. The second one is renamed to gperftools-lib with RPM repos, to further compound the inconsistency.
I find myself dealing with package and versioning rename issues regularly in the CI pipelines I have using apt.
Well, I consider it abuse of header files to put an implementation in there. And comparing including a c-file to IOCCC seems very exaggerated.
My experience with dependencies in Debian-derived distributions is actually very good, far less problematic than any other packaging system I ever used. But yes, one needs to maintain dependencies separately for RPM and others distributions. But obviously the problem is not lack of a package manager and adding another one would not solve anyhing: https://xkcd.com/927/ The solution would be standardizing package names and versions across distributions.
Exactly; I can't understand this obsession with header-only C "libraries".
Writing new C code in 2026 is already an artisanal statement, so why not got all the way in making it?
Useful for embedded devices? Crashes, disk updates not important for ephemeral process?
I feel like there's two kinds of developers. The ones who shit all over other people's preferences and turn everything into an almost religious discussion, and the ones who prefer to just build stuff.
Get over it. Some people like header only.
Agreed, once you've spent hrs fighting with C build tools under a deadline, it becomes very easy to see why this is beneficial.
No need to be an asshole; we can all discuss things civilly.
Only if people provide reasons for why they think it is bad, but with people along the lines of "Header-only? Eww. Sucks." you cannot.
To comment on this, I have a couple of header-only projects I have written. It makes sense in some scenarios. Sometimes I want no external dependencies and a single header file interface.
Some people may not have known the difference and probably thought it was more akin to a naming convention.
I'm obviously not talking about the people asking "what is it".
It would be a lot better for the community if you directly replied to the objectionable content with a civil response.
Why to call it a header? Could be just a source file. Including sources is uncommon, but why not? Solid "amalgamation" builds are a thing too.
In the early days of CUDA it was pretty common to just #include all your sources, since linking was such a nightmare.
As a non-C programmer, why would "header only" be a good thing?
It's not.
It's a tradeoff people make between ease of integration - just download the .h file into your project folder and #include it in your source file instead of worrying about source build system vs target build system, cross compiling headaches etc...
And compilation times: any time you change any of your source files, your compiler also has to recompile your dependencies. (Assuming you haven't used precompiled headers).
I'm completely ignorant about this, but wouldn't it be possible to compile separately your project to improve compilation times? for instance, if you're using OP's vector library, which is self contained, you could compile that first and just once?
Let's say you need to use a function like:
Let's say this is your main.c. The preprocessor just copies the contents of add.h into your main.c whenever you're trying to compile main.c. (let's ignore the concept of precompiled headers for now).What you can instead do is just put the add function declaration in add.h that just tells the compiler that add function takes two integers and returns an integer.
You can then put the add function definition in add.c , compile that to an add.o and link it to your main.o at link time to get your final binary - without having to recompile add.o every time you change your main.c.Precompiled headers: https://maskray.me/blog/2023-07-16-precompiled-headers
Unless you have link time optimization you would lose out on optimization and performance.
The whole thing is essentially a workaround for lack of sufficiently good/easy ways to package code in the ways people want to use it.
Recompiling the dependencies should only really happen if you change the file with the implementation include (usually done by defining <library>_IMPLEMENTATION or something like that.
It often also means it was written more correctly. There is a bit of an art to designing a header only library and it can strike a different balance between code size and runtime speed optimization.
In strict terms when you place implementation in a .c file you probably want that code to be shared when different things call it, and the compiler will "link" to that same implementation.
When you have a header only library the compiler is free to optimize in more ways specific to your actual use case.
Extremely easy copy paste deployment into projects
C's package management story is unfriendly to say the least. A header only library simplifies it dramatically, and makes it much more straightforward to integrate dependencies into your application.
Using your OS' package manager IS C's package management. Is it really that difficult to use apt, pacman, or BSD's "pkg"?
This. Wish I could upvote this 10 times.
What if I'm using 10 different OS?
I can still push the file on git and it works everywhere else.
git is not a package manager. It does not handle many things a package manager does.
GP never said it was.
But it does successfully replaces the need of using one, with less problems for certain situations.
Yes, I do use git submodules as well sometimes.
If you do not need the features of a package manager, then git submodules is great indeed.
Would it work to replace the memory store with mmap?
Brute-force kNN gets a bad reputation, but below ~50K vectors the overhead of building and maintaining an HNSW index often costs more than it saves, especially for infrequent queries. I use sqlite-vec (also flat scan by default) in production with 10K vectors at 384 dimensions and search takes under 5ms.
The low-hanging fruit for this library would be SIMD. At 128d float32, each distance computation touches 512 bytes of data. AVX2 processes 8 floats per cycle, NEON does 4. That's a 4-6x speedup on the hot path without changing the algorithm at all. For a header-only library where simplicity is the point, that seems like the right optimization to reach for before adding approximate indexing.
One gotcha: metadata isn't persisted on save/load. The README mentions the binary format stores vectors and IDs but not metadata. Anyone attaching text chunks to their embeddings for RAG will lose them on reload.
[dead]