### Run Hoard Benchmarks

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Example command for running the Hoard benchmark suite, specifying parameters for threads, iterations, objects, work type, and object size.

```bash
./threadtest <threads> <iterations> <objects> <work> <size>
# Example: ./threadtest 4 1000 10000 0 8
```

--------------------------------

### Threadtest Benchmark Usage

Source: https://context7.com/emeryberger/hoard/llms.txt

Demonstrates how to compile and run the threadtest benchmark. It shows example commands for baseline system malloc and Hoard (using LD_PRELOAD).

```bash
cd benchmarks/threadtest && make

# Usage: threadtest <threads> <iterations> <objects> <work> <objSize>
# Baseline (system malloc)
./threadtest 8 1000 30000 0 8
# Time elapsed = 1.87

# With Hoard (LD_PRELOAD)
LD_PRELOAD=../../build/libhoard.so ./threadtest 8 1000 30000 0 8
```

--------------------------------

### Run Hoard Benchmarks on Windows

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Example command for running the Hoard benchmark suite on Windows using `withdll.exe` for DLL injection, specifying the same parameters as the Linux/macOS version.

```powershell
withdll.exe /d:hoard.dll threadtest.exe 4 1000 10000 0 8
```

--------------------------------

### Install Hoard via Homebrew

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Use Homebrew to install the latest version of Hoard and its command-line tool. This installs the Hoard library and creates a 'hoard' command for running programs with Hoard.

```bash
brew tap emeryberger/hoard
brew install --HEAD emeryberger/hoard/libhoard
```

```bash
hoard myprogram-goes-here
```

--------------------------------

### Build Hoard with System Detours on Windows

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Instructions for building Hoard on Windows when Detours is already installed, either via vcpkg or a custom path. This avoids re-downloading and building Detours.

```bash
# Install via vcpkg
vcpkg install detours:x64-windows      # or arm64-windows, x86-windows

# Build with system Detours
cmake .. -DUSE_SYSTEM_DETOURS=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake

# Or if built from source
cmake .. -DUSE_SYSTEM_DETOURS=ON -DDETOURS_ROOT=C:/path/to/Detours
```

--------------------------------

### Install libstdc++-dev on Linux

Source: https://github.com/emeryberger/hoard/blob/master/README.md

On Linux, you may need to first install the appropriate version of libstdc++-dev.

```bash
sudo apt install libstdc++-dev
```

--------------------------------

### Install Hoard via Homebrew (macOS)

Source: https://context7.com/emeryberger/hoard/llms.txt

Installs Hoard using Homebrew on macOS, including a 'hoard' wrapper command for easy activation.

```bash
brew tap emeryberger/hoard
brew install --HEAD emeryberger/hoard/libhoard
# Installs a 'hoard' wrapper command:
hoard myprogram
```

--------------------------------

### CMake Package Integration for Hoard

Source: https://context7.com/emeryberger/hoard/llms.txt

Example of how a dependent project can find and link against Hoard using CMake's package management system after Hoard has been installed.

```cmake
# CMakeLists.txt of a dependent project
cmake_minimum_required(VERSION 3.15)
project(MyApp)

find_package(Hoard REQUIRED)      # Locates HoardConfig.cmake

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE Hoard::Hoard)

# Hoard::Hoard is a shared library alias; it sets include dirs and links
```

--------------------------------

### Build Hoard Library

Source: https://context7.com/emeryberger/hoard/llms.txt

Builds the Hoard library using CMake. Ensure the prefix path is set correctly if Hoard is installed in a non-standard location.

```bash
cmake -S . -B build -DCMAKE_PREFIX_PATH=/usr/local
cmake --build build
```

--------------------------------

### Custom Allocator Wrapping Hoard Internals

Source: https://context7.com/emeryberger/hoard/llms.txt

An example of how to create a custom allocator that utilizes Hoard's internal `xxmalloc` and `xxfree` functions. This demonstrates a simple C++ allocator interface.

```cpp
// --- Example: custom allocator wrapping Hoard internals ---
#include <cstdlib>
extern "C" void * xxmalloc(size_t);
extern "C" void   xxfree(void *);

struct MyAllocator {
    void * allocate(std::size_t n) {
        return xxmalloc(n);        // lock-free TLAB fast path
    }
    void deallocate(void * p) {
        xxfree(p);
    }
};
```

--------------------------------

### Windows Detours Initialization

Source: https://context7.com/emeryberger/hoard/llms.txt

Initializes the Hoard memory allocator on Windows using Microsoft Detours. It primes the Windows heap and installs detours for CRT and C++ operators.

```cpp
// Called from DllMain (wintls.cpp) on DLL_PROCESS_ATTACH.
extern "C" void InitializeWinWrapper() {
    DetourRestoreAfterWith();        // Required for withdll.exe injection
    HeapAlloc(GetProcessHeap(), 0, 1); // Prime Windows heap before takeover
    bool ok = InstallDetours();      // Attach CRT + C++ operator detours
    g_initComplete = true;           // Enable fast pointer-ownership check
    printf(ok ? "Hoard: Memory allocator active\n"
              : "Hoard: FAILED TO INITIALIZE\n");
}
```

--------------------------------

### CRT Detour Table Example

Source: https://context7.com/emeryberger/hoard/llms.txt

A subset of the detour table used for hooking CRT functions like malloc, free, calloc, and realloc. It maps symbol names to original pointers and detour functions.

```cpp
// Detour table (subset) — each entry is { symbol_name, &original_ptr, detour_fn }
static DetourEntry g_CRTDetours[] = {
    { "malloc",              &Real_malloc,        Detour_malloc   },
    { "free",                &Real_free,          Detour_free     },
    { "calloc",              &Real_calloc,        Detour_calloc   },
    { "realloc",             &Real_realloc,       Detour_realloc  },
    { "_msize",              &Real_msize,         Detour_msize    },
    { "??2@YAPEAX_K@Z",      &Real_new_64,        Detour_malloc   }, // new(size_t) 64-bit
    { "??3@YAXPEAX@Z",       &Real_delete_64,     Detour_free     }, // delete(void*) 64-bit
    // ... + 32-bit, nothrow, debug, _recalloc, strdup variants
};
```

--------------------------------

### Build Hoard and Test Program

Source: https://github.com/emeryberger/hoard/blob/master/todo.md

Steps to build the Hoard project and compile a test program. Ensure you are in a release configuration for optimal performance.

```cmd
mkdir build && cd build
cmake ..
cmake --build . --config Release
```

```cmd
cl.exe /EHsc /O2 test_malloc.cpp /Fe:test_malloc.exe
```

--------------------------------

### Build Individual Benchmark

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Command to build a specific benchmark, 'threadtest', by navigating to its directory and using Make.

```bash
cd benchmarks/threadtest
make
```

--------------------------------

### Build Hoard from Source (Linux/macOS)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Clone the Hoard repository, create a build directory, configure with CMake, and build using make.

```bash
git clone https://github.com/emeryberger/Hoard
    mkdir build && cd build
    cmake ..
    make
```

--------------------------------

### Build Hoard from Source (Windows)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Clone the Hoard repository, create a build directory, configure with CMake, and build the release configuration.

```powershell
git clone https://github.com/emeryberger/Hoard
cd Hoard
mkdir build && cd build
cmake ..
cmake --build . --config Release
```

--------------------------------

### Inject Multiple DLLs on Windows

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Demonstrates how to use `withdll.exe` to inject multiple DLLs, including Hoard and potentially other libraries, into a target executable.

```powershell
withdll.exe /d:hoard.dll /d:other.dll myprogram.exe
```

--------------------------------

### Build Hoard from Source (Windows)

Source: https://context7.com/emeryberger/hoard/llms.txt

Instructions for building Hoard on Windows using CMake. Programs must be compiled with the dynamic CRT (`/MD`).

```powershell
git clone https://github.com/emeryberger/Hoard
cd Hoard
mkdir build; cd build
cmake ..
cmake --build . --config Release
# Output: build\Release\hoard.dll
#         build\Release\withdll.exe
#         build\Release\setdll.exe
```

--------------------------------

### Build Hoard Benchmarks

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Commands to build the benchmark suite for Hoard. This involves navigating to the benchmarks directory and using Make.

```bash
cd benchmarks
make
```

--------------------------------

### System-wide Hoard Injection on Windows (AppInit_DLLs)

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Configures Windows to load Hoard DLL for all processes via the registry. This method is powerful but not recommended for production due to its system-wide impact and requires administrator privileges.

```powershell
# Not recommended for production - affects all processes
reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Windows" /v AppInit_DLLs /t REG_SZ /d "C:\path\to\hoard.dll"
reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Windows" /v LoadAppInit_DLLs /t REG_DWORD /d 1
```

--------------------------------

### Run cache-scratch benchmark

Source: https://context7.com/emeryberger/hoard/llms.txt

Execute the cache-scratch benchmark to detect false sharing. Run with a single thread for baseline and multiple threads with and without Hoard preloaded to observe performance differences.

```bash
cd benchmarks/cache-scratch && make

# Single thread (baseline)
./cache-scratch 1 1000 1 1000000
# Time elapsed = 0.42 seconds.

# 8 threads — ideal: 8× speedup; system allocator shows false-sharing slowdown
./cache-scratch 8 1000 1 1000000           # without Hoard: ~0.38s (near-ideal due to small obj)
LD_PRELOAD=../../build/libhoard.so \
    ./cache-scratch 8 1000 1 1000000       # Hoard: provably no cross-thread cache-line sharing
```

--------------------------------

### Build and Run Hoard on Windows

Source: https://github.com/emeryberger/hoard/blob/master/todo.md

Use these PowerShell commands to clean, build, and run the project with Hoard's DLL. Ensure the DLL and executable are in the correct release directory.

```powershell
# Clean build
rmdir /S /Q build
mkdir build && cd build
cmake ..
cmake --build . --config Release

# Run with Hoard
Release\withdll.exe /d:Release\hoard.dll program.exe [args...]
```

--------------------------------

### Build Hoard Library on Linux/macOS

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Standard build process using CMake and Make for Linux and macOS. Assumes a Unix-like environment.

```bash
mkdir build && cd build
cmake ..
make
```

--------------------------------

### Preload Hoard Library (macOS)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Set the DYLD_INSERT_LIBRARIES environment variable to point to the Hoard dynamic library to use Hoard on macOS.

```bash
export DYLD_INSERT_LIBRARIES=/path/to/libhoard.dylib
```

--------------------------------

### Activate Hoard with withdll.exe (Windows)

Source: https://context7.com/emeryberger/hoard/llms.txt

Injects Hoard into an unmodified Windows executable at runtime using `withdll.exe`. This is the recommended method for Windows and requires programs to be compiled with `/MD`.

```powershell
# Run any existing program through Hoard
.\build\Release\withdll.exe /d:.\build\Release\hoard.dll myapp.exe --threads 16

# Multiple DLLs
.\build\Release\withdll.exe /d:hoard.dll /d:profiler.dll myapp.exe

# Expected stdout on success:
# Hoard: Memory allocator active
```

--------------------------------

### Link Hoard Library at Build Time (Windows)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Link Hoard directly into your application during compilation using the cl compiler.

```powershell
cl /Ox /MD yourapp.cpp /link hoard.lib
```

--------------------------------

### Build Hoard Library on Windows

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Build process for Windows using CMake, which automatically handles Microsoft Detours. Ensure you are in a CMake-compatible shell (e.g., Developer Command Prompt for VS).

```powershell
mkdir build && cd build
cmake ..
cmake --build . --config Release
```

--------------------------------

### Run Hoard on Windows (DLL Injection)

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Utilize `withdll.exe` to inject the Hoard DLL into a target executable. This method requires the target program to be compiled with /MD.

```powershell
# From the build directory:
build\Release\withdll.exe /d:build\Release\hoard.dll myprogram.exe [args...]
```

--------------------------------

### Preload Hoard Library (Linux)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Set the LD_PRELOAD environment variable to point to the Hoard shared library to use Hoard.

```bash
export LD_PRELOAD=/path/to/libhoard.so
```

--------------------------------

### Run Hoard with Test Program

Source: https://github.com/emeryberger/hoard/blob/master/todo.md

Execute the compiled test program with Hoard DLL injection. This verifies successful initialization and allocation testing.

```cmd
build\Release\withdll.exe /d:build\Release\hoard.dll test_malloc.exe
```

--------------------------------

### Activate Hoard with DYLD_INSERT_LIBRARIES (macOS)

Source: https://context7.com/emeryberger/hoard/llms.txt

Activates Hoard on macOS by inserting the Hoard dynamic library into the process. The 'hoard' wrapper command from Homebrew provides a convenient alternative.

```bash
DYLD_INSERT_LIBRARIES=/usr/local/lib/libhoard.dylib ./myapp

# Or using the Homebrew wrapper
hoard ./myapp arg1 arg2
```

--------------------------------

### Run cache-thrash benchmark

Source: https://context7.com/emeryberger/hoard/llms.txt

Execute the cache-thrash benchmark to test active false sharing. This benchmark deliberately triggers false sharing with a naive allocator by passing objects between threads for writes. Compare performance with and without Hoard.

```bash
cd benchmarks/cache-thrash && make
# cache-thrash passes an object allocated on thread A to thread B for writes,
# deliberately triggering false sharing with a naive allocator.
./cache-thrash 8 1000 1 1000000           # slow: cache lines ping-pong between CPUs
LD_PRELOAD=../../build/libhoard.so \
    ./cache-thrash 8 1000 1 1000000       # Hoard: each thread gets its own cache line
```

--------------------------------

### Activate Hoard with LD_PRELOAD (Linux)

Source: https://context7.com/emeryberger/hoard/llms.txt

Activates Hoard for a single command or an entire session on Linux by preloading the Hoard shared library. This method requires no source changes.

```bash
# One-shot
LD_PRELOAD=/path/to/libhoard.so ./myserver --workers 32

# Session-wide
export LD_PRELOAD=/path/to/libhoard.so
./myserver --workers 32

# Verify interception (Hoard prints a version banner on first alloc)
LD_PRELOAD=/path/to/libhoard.so python3 -c "import ctypes; print('ok')"
# Using the Hoard memory allocator (http://www.hoard.org), version 3.13.0
```

--------------------------------

### Thread-Local Allocation Buffer (TLAB) Overview

Source: https://context7.com/emeryberger/hoard/llms.txt

Explains the Thread-Local Allocation Buffer (TLAB) mechanism in Hoard, which provides a per-thread cache for small objects to achieve O(1) allocation and deallocation without locks.

```cpp
// src/include/superblocks/tlab.h (simplified usage via hoardtlab.h)

// TheCustomHeapType = ANSIWrapper<ThreadLocalAllocationBuffer<...>>
// One instance lives in __thread storage per thread (unixtls.cpp).

// Fast-path malloc: O(1), no locking
// 1. getSizeClass(sz)  → bin index
// 2. _localHeap[bin].get() → pointer from singly-linked free list
// 3. Decrement _localHeapBytes
// Miss: fall through to parent HoardHeapType::malloc()

// Fast-path free: O(1), no locking
// 1. getSuperblock(ptr) → check isValidSuperblock()
// 2. sz <= LargestSmallObject && _localHeapBytes + sz <= 16MB
// 3. _localHeap[bin].insert(ptr)  → push onto free list
// Overflow: delegate to parent heap (acquires superblock-level lock)

// Thread exit — unixtls.cpp intercepts pthread_create/pthread_exit:
//   exitRoutine() calls heap->~TheCustomHeapType()
//   → TLAB::clear() drains all bins back to parent
//   → getMainHoardHeap()->releaseHeap() returns the per-thread slot

// Example: observe TLAB behavior with threadtest benchmark
// (no source changes needed — just LD_PRELOAD)
//
//   LD_PRELOAD=./libhoard.so ./threadtest 8 1000 30000 0 8
//   Running threadtest for 8 threads, 1000 iterations, 30000 objects, 0 work and 8 objSize...
//   Time elapsed = 0.31          ← with Hoard
//
//   ./threadtest 8 1000 30000 0 8
//   Time elapsed = 1.87          ← system malloc (typical 6x difference)
```

--------------------------------

### Run larson benchmark

Source: https://context7.com/emeryberger/hoard/llms.txt

Execute the larson benchmark, which simulates a server workload with cross-thread frees. This tests Hoard's ability to handle ownership transfer between threads. Run with and without Hoard preloaded.

```bash
cd benchmarks/larson && make
# Simulates a server: thread A allocates, thread B frees.
# Tests how well the allocator handles cross-thread ownership transfer.
./larson 10 7 8 1000 100 1 8              # <threads> <minObj> <maxObj> ...
LD_PRELOAD=../../build/libhoard.so \
    ./larson 10 7 8 1000 100 1 8
```

--------------------------------

### Inject Hoard DLL into Executable (Windows)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Use withdll.exe to inject the Hoard DLL into a program at runtime. Programs must be compiled with /MD.

```powershell
build\Release\withdll.exe /d:build\Release\hoard.dll yourapp.exe [args...]
```

--------------------------------

### Link Hoard at Compile Time (Windows MSVC)

Source: https://context7.com/emeryberger/hoard/llms.txt

Links Hoard directly into an application during compilation using MSVC. Requires the application to be compiled with the `/MD` dynamic CRT.

```c
// Compile and link Hoard directly — requires /MD CRT
cl /Ox /MD myapp.cpp /link hoard.lib

# Or CMake target
# In CMakeLists.txt:
# find_package(Hoard REQUIRED)
# target_link_libraries(myapp PRIVATE Hoard::Hoard)
```

--------------------------------

### Enable Debug Logging for Hoard

Source: https://github.com/emeryberger/hoard/blob/master/todo.md

Recompile Hoard with debug logging enabled by defining 'HOARD_DEBUG'. This is useful for diagnosing issues.

```cmd
cmake .. -DCMAKE_CXX_FLAGS="/DHOARD_DEBUG"
cmake --build . --config Release
```

--------------------------------

### AlignedMmap Instance Methods

Source: https://context7.com/emeryberger/hoard/llms.txt

Declares the malloc and free methods for AlignedMmapInstance. malloc handles alignment and mapping, while free calls MmapWrapper::unmap.

```cpp
// malloc(sz):
//   1. Round sz up to page boundary.
//   2. Call MmapWrapper::map(sz).  If already SUPERBLOCK_SIZE-aligned → done.
//   3. Otherwise: map(sz + SUPERBLOCK_SIZE), align pointer, unmap prolog/epilog.
void * AlignedMmapInstance::malloc(size_t sz);

// free(ptr, sz): MmapWrapper::unmap(ptr, sz)
```

--------------------------------

### Permanently Add Hoard DLL to Executable (Windows)

Source: https://github.com/emeryberger/hoard/blob/master/README.md

Use setdll.exe to modify an executable's import table to include Hoard. A backup is created as .exe~.

```powershell
# Add Hoard to executable (creates backup as .exe~)
build\Release\setdll.exe /d:build\Release\hoard.dll yourapp.exe

# Remove Hoard from executable
build\Release\setdll.exe /r:hoard.dll yourapp.exe
```

--------------------------------

### Hoard Configuration Constants

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines key configuration constants for Hoard, including cache line size, maximum memory per TLAB, maximum threads, number of heaps per thread, and the size of the largest small object.

```cpp
namespace Hoard {
  enum { CACHE_LINE_SIZE      = 64          };  // bytes; prevents false sharing in heap arrays
  enum { MAX_MEMORY_PER_TLAB  = 16*1024*1024 }; // 16 MB max cached per TLAB
  enum { MaxThreads           = 2048        };  // max concurrent threads
  enum { NumHeaps             = 128         };  // per-thread heap pool size
  enum { LargestSmallObject   = 1024        };  // bytes; objects above this skip TLAB → BigHeap
}
```

--------------------------------

### Enable Executable Heap Memory

Source: https://context7.com/emeryberger/hoard/llms.txt

To enable executable heap memory, modify `heaplayers/heaplayers.h` and set `#define HL_EXECUTABLE_HEAP 1`. This changes `mmap` protection to `PROT_READ|PROT_WRITE|PROT_EXEC`, which is necessary for JIT compilers that emit code into `malloc`'d buffers.

```c
// Enabling executable heap memory (disabled by default for security):
// In heaplayers/heaplayers.h, set:
// #define HL_EXECUTABLE_HEAP 1
// This changes mmap protection to PROT_READ|PROT_WRITE|PROT_EXEC.
// Only needed for JIT compilers that emit code into malloc'd buffers.
```

--------------------------------

### Hoard Version Constants

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines the major, minor, patch, and string representation of the Hoard version.

```c
#define HOARD_MAJOR          3
#define HOARD_MINOR         13
#define HOARD_PATCH          0
#define HOARD_VERSION_STRING "3.13.0"
```

--------------------------------

### Permanently Add Hoard to Windows Executable

Source: https://github.com/emeryberger/hoard/blob/master/CLAUDE.md

Use `setdll.exe` to modify an executable's import table, ensuring Hoard is loaded on every execution. A backup of the original executable is created.

```powershell
# Add Hoard to executable (creates backup as .exe~)
build\Release\setdll.exe /d:build\Release\hoard.dll myprogram.exe

# Remove Hoard from executable
build\Release\setdll.exe /r:hoard.dll myprogram.exe
```

--------------------------------

### Hoard Internal Allocation API

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines the core C allocation functions for Hoard. These are the canonical entry points for memory management within the library, handling allocation, deallocation, and alignment.

```cpp
// src/source/libhoard.cpp  — internal symbols, not called directly by applications

extern "C" {

// Allocate sz bytes; never returns nullptr (aborts on OOM).
// Fast path: delegates to per-thread TLAB (TheCustomHeapType).
// Bootstrap path: satisfies pre-TLAB requests from a 32MB static buffer.
void * xxmalloc(size_t sz);

// Free a pointer previously returned by xxmalloc.
// Silently ignores pointers inside the bootstrap static buffer.
// Silently ignores nullptr.
void xxfree(void * ptr);

// Aligned allocation: delegates to generic_xxmemalign which rounds
// alignment to a power of two, then calls xxmalloc with padded size.
void * xxmemalign(size_t alignment, size_t sz);

// Returns the usable size of a Hoard-allocated pointer.
// For bootstrap-buffer pointers returns remaining buffer space.
size_t xxmalloc_usable_size(void * ptr);

// Lock/unlock are no-ops in Hoard (locking is per-bin / per-superblock).
void xxmalloc_lock();
void xxmalloc_unlock();

} // extern "C"
```

--------------------------------

### Hoard Heap Constants

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines constants related to Hoard's heap management, including superblock size and the number of emptiness classes for fullness buckets.

```c
#define SUPERBLOCK_SIZE   262144UL  // 256 KB (Unix/macOS)
// #define SUPERBLOCK_SIZE  65536UL  // 64 KB (Windows)
#define EMPTINESS_CLASSES 8         // number of fullness buckets per bin
```

--------------------------------

### Modify Import Table with setdll.exe (Windows)

Source: https://context7.com/emeryberger/hoard/llms.txt

Permanently modifies an executable's import table to include Hoard on Windows. Use the `/r` flag to remove the import.

```powershell
# Permanently add Hoard to an executable's import table (creates myapp.exe~ backup)
.\build\Release\setdll.exe /d:.\build\Release\hoard.dll myapp.exe

# Remove Hoard from the import table
.\build\Release\setdll.exe /r:hoard.dll myapp.exe
```

--------------------------------

### SafeGetHoardSize for Foreign Pointers

Source: https://context7.com/emeryberger/hoard/llms.txt

Implements SafeGetHoardSize using SEH to safely retrieve the size of a pointer allocated before Hoard's hooking, preventing crashes on foreign pointers.

```cpp
// Foreign-pointer safety during the injection window:
// SafeGetHoardSize() uses SEH to catch ACCESS_VIOLATION when reading
// a superblock header for a pointer allocated before hooking was installed.
static size_t SafeGetHoardSize(void * ptr) {
    __try   { return xxmalloc_usable_size(ptr); }
    __except(EXCEPTION_ACCESS_VIOLATION) { return 0; }
}
```

--------------------------------

### Singleton Access to HoardHeap

Source: https://context7.com/emeryberger/hoard/llms.txt

Provides access to the single HoardHeapType instance, which owns TheGlobalHeap. It uses a static double buffer to prevent static-initialization-order issues.

```cpp
// getMainHoardHeap() (libhoard.cpp) returns the one HoardHeapType instance,
// which owns TheGlobalHeap.  It is initialized into a static double[] buffer
// to avoid static-initialization-order issues:
Hoard::HoardHeapType *getMainHoardHeap();
```

--------------------------------

### AlignedMmap Class Definition

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines the AlignedMmap class, a template for allocating OS memory with superblock alignment. It uses LockedHeap and AlignedMmapInstance.

```cpp
template <size_t Alignment_, class LockType>
class AlignedMmap : public ExactlyOneHeap<
                      LockedHeap<LockType,
                                 AlignedMmapInstance<Alignment_>>> {};
```

--------------------------------

### HoardManager Superblock Management API

Source: https://context7.com/emeryberger/hoard/llms.txt

Details the `HoardManager` class responsible for managing memory superblocks. It handles allocation and deallocation of objects within superblocks and governs the donation of underutilized superblocks to the global heap.

```cpp
// src/include/hoard/hoardmanager.h

// malloc: find an object in a superblock bin for the right size class.
//   Acquires per-bin lock (not a global lock).
//   On miss: getAnotherSuperblock() — tries GlobalHeap first, then mmap.
void * HoardManager::malloc(size_t sz);

// free: return object to its superblock's bin.
//   Acquires per-bin lock.
//   After unlock: check emptiness threshold; if crossed → slowPathFree().
void HoardManager::free(void * ptr);

// put: receive a superblock from a child heap.
//   If accepting it would immediately cross threshold, forward to parent.
void HoardManager::put(SuperblockType * s, size_t sz);

// get: hand a superblock to a child heap.
SuperblockType * HoardManager::get(size_t sz, HeapType * dest);

// drainAllDelayedFrees: called on thread exit to process cross-thread frees.
void HoardManager::drainAllDelayedFrees();

// --- Threshold function (hoardheap.h) ---
// Returns true iff the heap should release a superblock to the global heap:
//   (8 * U < 7 * A)  &&  (U < A - 2 * SUPERBLOCK_SIZE / objSize)
static bool hoardThresholdFunctionClass::function(
    unsigned int u,       // objects in use
    unsigned int a,       // objects allocated
    size_t objSize);
```

--------------------------------

### Disable Lock Optimization

Source: https://context7.com/emeryberger/hoard/llms.txt

To disable lock optimization, typically for use in `dlopen` modules, define `#define HOARD_NO_LOCK_OPT 1`. This forces `anyThreadCreated = true` from startup, bypassing the single-threaded fast path that skips locking.

```c
// Disabling lock optimization (for use in dlopen modules):
// #define HOARD_NO_LOCK_OPT 1
// Forces anyThreadCreated = true from startup, disabling the
// single-threaded fast path that skips locking.
```

--------------------------------

### GlobalHeap Type Alias and Methods

Source: https://context7.com/emeryberger/hoard/llms.txt

Defines the GlobalHeap type alias and its core put/get methods for managing superblocks. This is the central heap managing redistribution between per-thread heaps.

```cpp
namespace Hoard {

// TheGlobalHeap type alias (hoardheap.h):
typedef GlobalHeap<SUPERBLOCK_SIZE,           // 256KB on Unix, 64KB on Windows
                   HoardSuperblockHeader,
                   EMPTINESS_CLASSES,          // 8
                   MmapSource,
                   TheLockType>
TheGlobalHeap;

// put: accept a superblock from a per-thread heap.
void GlobalHeap::put(void * s, size_t sz);

// get: hand a superblock to a per-thread heap.
// Returns nullptr if none available — caller then mmaps a new superblock.
SuperblockType * GlobalHeap::get(size_t sz, void * dest);

} // namespace Hoard
```

--------------------------------

### MmapSource Class Definition

Source: https://context7.com/emeryberger/hoard/llms.txt

Hoard's specific instantiation of AlignedMmap, using SUPERBLOCK_SIZE and TheLockType. This class handles OS memory allocation for superblocks.

```cpp
// Hoard's instantiation (hoardheap.h):
class MmapSource : public AlignedMmap<SUPERBLOCK_SIZE, TheLockType> {};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.