From efcea3a80da7c4479d5fe168435ecc9fd06bdc72 Mon Sep 17 00:00:00 2001
From: John Turner <jturner.usa@gmail.com>
Date: Sun, 14 Sep 2025 00:16:10 -0400
Subject: Squashed 'subprojects/boost-sqlite/' content from commit 3378e35

git-subtree-dir: subprojects/boost-sqlite
git-subtree-split: 3378e353705271e569cf4ba15c467b840a39798c
---
 doc/reference/allocator.adoc | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 doc/reference/allocator.adoc

(limited to 'doc/reference/allocator.adoc')

diff --git a/doc/reference/allocator.adoc b/doc/reference/allocator.adoc
new file mode 100644
index 0000000..ab9a4e9
--- /dev/null
+++ b/doc/reference/allocator.adoc
@@ -0,0 +1,31 @@
+== `sqlite/allocator.hpp`
+[#allocator]
+
+The sqlite allocator wraps sqlite's malloc & free functions in a similar way that std::allocator wraps `new`/`delete`.
+
+This can be used for sqlite-related code (e.g. vtables or custom functions) that should use memory from the sqlite3 pool.
+
+[source,cpp,subs=+quotes]
+----
+template<typename T>
+struct allocator
+{
+  constexpr allocator() noexcept {}
+  constexpr allocator( const allocator& other ) noexcept {}
+  template< class U >
+  constexpr allocator( const allocator<U>& other ) noexcept {}
+
+  constexpr static std::size_t alignment = __implementation_defined__;
+
+
+  static_assert(alignof(T) <= alignment, "T alignment can't be fulfilled by sqlite");
+
+  [[nodiscard]] T* allocate( std::size_t n ); // <1>
+  void deallocate( T* p, std::size_t); // <2>
+};
+----
+<1> Invokes `sqlite3_malloc64` and throws `std::bad_alloc` if it fails.
+<2> Invokes `sqlite3_free`
+
+NOTE: Sqlite provides extensive https://www.sqlite.org/malloc.html[customizability for its dynamic memory allocation].
+
-- 
cgit v1.2.3

