mongory 0.7.5 → 0.7.7

data/ext/mongory_ext/mongory-core/src/foundations/config.c

@@ -0,0 +1,270 @@
+/**
+ * @file config.c
+ * @brief Implements global configuration and initialization for the Mongory
+ * library.
+ *
+ * This file manages the lifecycle of global resources such as the internal
+ * memory pool, regex adapter, matcher registration table, and value converters.
+ * It provides the `mongory_init` and `mongory_cleanup` functions, as well as
+ * setters for customizable components and a string copy utility.
+ */
+#include "mongory-core/foundations/config.h"
+#include "../matchers/base_matcher.h"      // For mongory_matcher_build_func
+#include "../matchers/compare_matcher.h"   // For specific matcher constructors
+#include "../matchers/composite_matcher.h" // For specific matcher constructors
+#include "../matchers/existance_matcher.h" // For specific matcher constructors
+#include "../matchers/inclusion_matcher.h" // For specific matcher constructors
+#include "../matchers/literal_matcher.h"   // For specific matcher constructors
+#include "../matchers/external_matcher.h"     // For specific matcher constructors
+#include "config_private.h"                // For mongory_regex_adapter, mongory_value_converter, etc.
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/foundations/value.h"
+
+static bool mongory_regex_default_func(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value);
+static char *mongory_regex_default_stringify_func(mongory_memory_pool *pool, mongory_value *pattern);
+
+// Global internal memory pool for the library.
+mongory_memory_pool *mongory_internal_pool = NULL;
+// Global adapter for regex operations.
+mongory_regex_adapter mongory_internal_regex_adapter = {
+  .match_func = mongory_regex_default_func,
+  .stringify_func = mongory_regex_default_stringify_func,
+};
+// Global table mapping matcher names (e.g., "$eq") to their build functions.
+mongory_table *mongory_matcher_mapping = NULL;
+// Global converter for handling external data types.
+mongory_value_converter mongory_internal_value_converter = {
+  .deep_convert = NULL,
+  .shallow_convert = NULL,
+  .recover = NULL,
+};
+// Global adapter for custom matchers.
+mongory_matcher_custom_adapter mongory_custom_matcher_adapter = {
+  .build = NULL,
+  .lookup = NULL,
+  .match = NULL,
+};
+
+bool mongory_matcher_trace_result_colorful = true;
+
+/**
+ * @brief Initializes the internal memory pool if it hasn't been already.
+ * This pool is used for allocations by various library components.
+ */
+static inline void mongory_internal_pool_init() {
+  if (mongory_internal_pool != NULL) {
+    return; // Already initialized.
+  }
+  mongory_internal_pool = mongory_memory_pool_new();
+  // TODO: Add error handling if mongory_memory_pool_new returns NULL.
+}
+
+/**
+ * @brief Default regex function that always returns false.
+ * Used if no custom regex function is set via mongory_regex_func_set.
+ * @param pool Unused.
+ * @param pattern Unused.
+ * @param value Unused.
+ * @return Always false.
+ */
+static bool mongory_regex_default_func(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  (void)value;   // Mark as unused.
+  return false;  // Default behavior is no match.
+}
+
+static char *mongory_regex_default_stringify_func(mongory_memory_pool *pool, mongory_value *pattern) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  return "//";   // Default behavior is no stringification.
+}
+
+/**
+ * @brief Sets the global regex matching function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex function to use.
+ */
+void mongory_regex_func_set(mongory_regex_func func) {
+  mongory_internal_regex_adapter.match_func = func;
+}
+
+/**
+ * @brief Sets the global regex stringify function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex stringify function to use.
+ */
+void mongory_regex_stringify_func_set(mongory_regex_stringify_func func) {
+  mongory_internal_regex_adapter.stringify_func = func;
+}
+/**
+ * @brief Initializes the matcher mapping table if it hasn't been already.
+ * This table stores registrations of matcher names to their constructor
+ * functions.
+ */
+static inline void mongory_matcher_mapping_init() {
+  if (mongory_matcher_mapping != NULL) {
+    return; // Already initialized.
+  }
+
+  // Ensure the internal pool is initialized first.
+  mongory_internal_pool_init();
+  if (mongory_internal_pool == NULL) {
+    return; // Cannot proceed if pool initialization failed.
+  }
+
+  mongory_matcher_mapping = mongory_table_new(mongory_internal_pool);
+  if (mongory_matcher_mapping == NULL) {
+    // TODO: Set error state.
+    return;
+  }
+}
+
+/**
+ * @brief Registers a matcher build function with a given name.
+ * The build function is stored in the global matcher mapping table.
+ * @param name The name of the matcher (e.g., "$eq", "$in").
+ * @param build_func A function pointer to the matcher's constructor.
+ */
+void mongory_matcher_register(char *name, mongory_matcher_build_func build_func) {
+  // Ensure mapping is initialized.
+  if (mongory_matcher_mapping == NULL) {
+    mongory_matcher_mapping_init();
+    if (mongory_matcher_mapping == NULL) {
+      // TODO: Set error: Cannot register if mapping init failed.
+      return;
+    }
+  }
+
+  // Wrap the function pointer in a mongory_value to store in the table.
+  mongory_value *value = mongory_value_wrap_ptr(mongory_internal_pool, build_func);
+  if (value == NULL) {
+    // TODO: Set error: Failed to wrap pointer.
+    return;
+  }
+
+  mongory_matcher_mapping->set(mongory_matcher_mapping, name, value);
+  // TODO: Check return value of set?
+}
+
+/**
+ * @brief Retrieves a matcher build function by its name from the global
+ * mapping.
+ * @param name The name of the matcher to retrieve.
+ * @return mongory_matcher_build_func A function pointer to the matcher's
+ * constructor, or NULL if not found.
+ */
+mongory_matcher_build_func mongory_matcher_build_func_get(char *name) {
+  if (mongory_matcher_mapping == NULL) {
+    return NULL; // Mapping not initialized or init failed.
+  }
+
+  mongory_value *value = mongory_matcher_mapping->get(mongory_matcher_mapping, name);
+  if (value == NULL || value->type != MONGORY_TYPE_POINTER) {
+    return NULL; // Not found or not a pointer type as expected.
+  }
+
+  return (mongory_matcher_build_func)value->data.ptr;
+}
+
+/**
+ * @brief Sets the function for deep conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param deep_convert The deep conversion function.
+ */
+void mongory_value_converter_deep_convert_set(mongory_deep_convert_func deep_convert) {
+  mongory_internal_value_converter.deep_convert = deep_convert;
+}
+
+/**
+ * @brief Sets the function for shallow conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param shallow_convert The shallow conversion function.
+ */
+void mongory_value_converter_shallow_convert_set(mongory_shallow_convert_func shallow_convert) {
+  mongory_internal_value_converter.shallow_convert = shallow_convert;
+}
+
+/**
+ * @brief Sets the function for recovering external values from mongory_value.
+ * Initializes the value converter if necessary.
+ * @param recover The recovery function.
+ */
+void mongory_value_converter_recover_set(mongory_recover_func recover) {
+  mongory_internal_value_converter.recover = recover;
+}
+
+
+void mongory_custom_matcher_match_func_set(bool (*match)(void *external_matcher, mongory_value *value)) {
+  mongory_custom_matcher_adapter.match = match;
+}
+
+void mongory_custom_matcher_build_func_set(mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx)) {
+  mongory_custom_matcher_adapter.build = build;
+}
+
+void mongory_custom_matcher_lookup_func_set(bool (*lookup)(char *key)) {
+  mongory_custom_matcher_adapter.lookup = lookup;
+}
+
+void mongory_matcher_trace_result_colorful_set(bool colorful) {
+  mongory_matcher_trace_result_colorful = colorful;
+}
+
+/**
+ * @brief Initializes all core Mongory library components.
+ * This includes the internal memory pool, regex adapter, matcher mapping table,
+ * and value converter. It then registers all standard matcher types.
+ * This function MUST be called before using most other library features.
+ */
+void mongory_init() {
+  // Initialize all global components. Order can be important if one init
+  // depends on another (e.g., most depend on the pool).
+  mongory_internal_pool_init();
+  mongory_matcher_mapping_init();
+
+  // Register all standard matchers.
+  // Note: These registrations rely on mongory_internal_pool and
+  // mongory_matcher_mapping being successfully initialized.
+  // TODO: Add checks to ensure initializations were successful before
+  // proceeding.
+  mongory_matcher_register("$in", mongory_matcher_in_new);
+  mongory_matcher_register("$nin", mongory_matcher_not_in_new);
+  mongory_matcher_register("$eq", mongory_matcher_equal_new);
+  mongory_matcher_register("$ne", mongory_matcher_not_equal_new);
+  mongory_matcher_register("$gt", mongory_matcher_greater_than_new);
+  mongory_matcher_register("$gte", mongory_matcher_greater_than_or_equal_new);
+  mongory_matcher_register("$lt", mongory_matcher_less_than_new);
+  mongory_matcher_register("$lte", mongory_matcher_less_than_or_equal_new);
+  mongory_matcher_register("$exists", mongory_matcher_exists_new);
+  mongory_matcher_register("$present", mongory_matcher_present_new);
+  mongory_matcher_register("$regex", mongory_matcher_regex_new);
+  mongory_matcher_register("$and", mongory_matcher_and_new);
+  mongory_matcher_register("$or", mongory_matcher_or_new);
+  mongory_matcher_register("$elemMatch", mongory_matcher_elem_match_new);
+  mongory_matcher_register("$every", mongory_matcher_every_new);
+  mongory_matcher_register("$not", mongory_matcher_not_new);
+  mongory_matcher_register("$size", mongory_matcher_size_new);
+}
+
+/**
+ * @brief Cleans up all resources allocated by the Mongory library.
+ * This primarily involves freeing the internal memory pool, which should, in
+ * turn, release all memory allocated from it. It also resets global pointers
+ * to NULL. This should be called when the library is no longer needed to
+ * prevent memory leaks.
+ */
+void mongory_cleanup() {
+  if (mongory_internal_pool != NULL) {
+    // Freeing the pool should handle all allocations made from it,
+    // including the regex_adapter, matcher_mapping table (and its contents if
+    // they were allocated from this pool), and value_converter.
+    mongory_internal_pool->free(mongory_internal_pool);
+    mongory_internal_pool = NULL;
+  }
+
+  // Set other global pointers to NULL to indicate they are no longer valid.
+  // The memory they pointed to should have been managed by the internal pool.
+  mongory_matcher_mapping = NULL; // The table itself and its nodes.
+}

data/ext/mongory_ext/mongory-core/src/foundations/config_private.h

@@ -0,0 +1,48 @@
+#ifndef MONGORY_FOUNDATIONS_CONFIG_PRIVATE_H
+#define MONGORY_FOUNDATIONS_CONFIG_PRIVATE_H
+#include "../matchers/base_matcher.h"
+#include "mongory-core/foundations/config.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/matchers/matcher.h"
+
+typedef struct mongory_regex_adapter {
+  mongory_regex_func match_func;
+  mongory_regex_stringify_func stringify_func;
+} mongory_regex_adapter;
+
+typedef struct mongory_value_converter {
+  mongory_deep_convert_func deep_convert;
+  mongory_shallow_convert_func shallow_convert;
+  mongory_recover_func recover;
+} mongory_value_converter;
+
+/**
+ * @brief Function pointer type for matching a value against an external matcher.
+ *
+ * This function is called when a value needs to be matched against an external
+ * matcher.
+ *
+ * @param external_matcher The external reference to the matcher.
+ * @param value The value to match against.
+ * @return bool True if the value matches the matcher, false otherwise.
+ */
+typedef struct mongory_matcher_custom_adapter {
+  bool (*match)(void *external_matcher, mongory_value *value); // Match a value against an external matcher.
+  mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx); // Build an external matcher reference.
+  bool (*lookup)(char *key); // Lookup a matcher reference by key.
+} mongory_matcher_custom_adapter;
+
+extern mongory_memory_pool *mongory_internal_pool;
+extern mongory_regex_adapter mongory_internal_regex_adapter;
+extern mongory_table *mongory_matcher_mapping;
+extern mongory_value_converter mongory_internal_value_converter;
+extern mongory_matcher_custom_adapter mongory_custom_matcher_adapter;
+extern bool mongory_matcher_trace_result_colorful;
+
+typedef mongory_matcher *(*mongory_matcher_build_func)(mongory_memory_pool *pool,
+                                                       mongory_value *condition,
+                                                       void *extern_ctx); // build function
+void mongory_matcher_register(char *name, mongory_matcher_build_func build_func);
+mongory_matcher_build_func mongory_matcher_build_func_get(char *name);
+
+#endif

data/ext/mongory_ext/mongory-core/src/foundations/error.c

@@ -0,0 +1,38 @@
+#ifndef MONGORY_ERROR_C
+#define MONGORY_ERROR_C
+/**
+ * @file error.c
+ * @brief Implements error type to string conversion for the Mongory library.
+ */
+#include <mongory-core/foundations/error.h>
+
+/**
+ * @brief Converts a mongory_error_type enum to its human-readable string
+ * representation.
+ *
+ * This function uses the MONGORY_ERROR_TYPE_MACRO to generate a switch
+ * statement that maps each error enum to its corresponding string.
+ *
+ * @param type The mongory_error_type enum value to convert.
+ * @return const char* A string literal representing the error type. If the
+ * type is not recognized, it returns "Unknown Error Type".
+ */
+const char *mongory_error_type_to_string(enum mongory_error_type type) {
+  switch (type) {
+// Use the X-Macro to generate case statements for each error type.
+#define DEFINE_ERROR_STRING(name, num, str)                                                                            \
+  case name:                                                                                                           \
+    return str;
+    MONGORY_ERROR_TYPE_MACRO(DEFINE_ERROR_STRING)
+#undef DEFINE_ERROR_STRING // Undefine the macro after use.
+  default:
+    // Fallback for any undefined or unknown error types.
+    return "Unknown Error Type";
+  }
+}
+
+mongory_error MONGORY_ALLOC_ERROR = {
+  .type = MONGORY_ERROR_MEMORY,
+  .message = "Memory Allocation Failed",
+};
+#endif

data/ext/mongory_ext/mongory-core/src/foundations/memory_pool.c

@@ -0,0 +1,298 @@
+/**
+ * @file memory_pool.c
+ * @brief Implements a memory pool for the Mongory library.
+ *
+ * This implementation uses a linked list of memory chunks. Allocations are
+ * made from the current chunk. If the current chunk is full, a new, larger
+ * chunk is allocated and added to the list. Freeing the pool deallocates all
+ * chunks. It also supports tracing externally allocated memory.
+ */
+#include <mongory-core/foundations/memory_pool.h>
+#include <stdio.h>  // For NULL, though stdlib.h or stddef.h is more common
+#include <stdlib.h> // For calloc, free, etc.
+#include <string.h> // For memset
+
+/**
+ * @def MONGORY_INITIAL_CHUNK_SIZE
+ * @brief The initial size in bytes for the first memory chunk allocated by the
+ * pool.
+ */
+#define MONGORY_INITIAL_CHUNK_SIZE 2048
+
+/**
+ * @def MONGORY_ALIGN8(size)
+ * @brief Macro to align a given size to an 8-byte boundary.
+ * This is useful for ensuring that memory allocations are suitably aligned
+ * for various data types.
+ * @param size The original size.
+ * @return The size aligned up to the nearest multiple of 8.
+ */
+#define MONGORY_ALIGN8(size) (((size) + 7) & ~((size_t)7))
+
+/**
+ * @struct mongory_memory_node
+ * @brief Represents a node in the linked list of memory chunks within the pool.
+ *
+ * Each node holds a pointer to a block of memory (`ptr`), its total `size`,
+ * how much of it is `used`, and a pointer to the `next` node in the list.
+ * This structure is also used by the tracing mechanism to track external
+ * allocations.
+ */
+typedef struct mongory_memory_node {
+  void *ptr;                        /**< Pointer to the allocated memory block. */
+  size_t size;                      /**< Total size of the memory block. */
+  size_t used;                      /**< Bytes used in this memory block. */
+  struct mongory_memory_node *next; /**< Pointer to the next memory node. */
+} mongory_memory_node;
+
+/**
+ * @struct mongory_memory_pool_ctx
+ * @brief Internal context for a mongory_memory_pool.
+ *
+ * Stores the current `chunk_size` (which doubles on growth), pointers to
+ * the `head` and `current` memory nodes for allocations, and a list (`extra`)
+ * for traced external allocations.
+ */
+typedef struct mongory_memory_pool_ctx {
+  size_t chunk_size;            /**< Current preferred size for new chunks. */
+  mongory_memory_node *head;    /**< Head of the list of memory chunks. */
+  mongory_memory_node *current; /**< Current chunk to allocate from. */
+  mongory_memory_node *extra;   /**< Head of list for externally traced memory. */
+} mongory_memory_pool_ctx;
+
+/**
+ * @brief Allocates a new memory chunk (node and its associated memory block).
+ *
+ * Uses `calloc` to ensure memory is zero-initialized.
+ *
+ * @param chunk_size The size of the memory block to allocate for this chunk.
+ * @return mongory_memory_node* Pointer to the new memory node, or NULL on
+ * failure.
+ */
+static inline mongory_memory_node *mongory_memory_chunk_new(size_t chunk_size) {
+  mongory_memory_node *node = calloc(1, sizeof(mongory_memory_node));
+  if (!node) {
+    return NULL; // Failed to allocate node structure.
+  }
+
+  void *mem = calloc(1, chunk_size);
+  if (!mem) {
+    free(node);  // Clean up allocated node structure.
+    return NULL; // Failed to allocate memory block for the chunk.
+  }
+
+  node->ptr = mem;
+  node->size = chunk_size;
+  node->used = 0;
+  node->next = NULL;
+
+  return node;
+}
+
+/**
+ * @brief Grows the memory pool by adding a new, larger chunk.
+ *
+ * The new chunk size is at least double the previous chunk size, and large
+ * enough to satisfy `request_size`. The new chunk becomes the `current` chunk.
+ *
+ * @param ctx Pointer to the memory pool's context.
+ * @param request_size The minimum size required from the new chunk for an
+ * upcoming allocation.
+ * @return true if growth was successful, false otherwise.
+ */
+static inline bool mongory_memory_pool_grow(mongory_memory_pool_ctx *ctx, size_t request_size) {
+  if (ctx->current->next) {
+    ctx->current = ctx->current->next;
+    return true; // Already have a next chunk.
+  }
+  // Double the chunk size, ensuring it's at least as large as request_size.
+  ctx->chunk_size *= 2;
+  while (request_size > ctx->chunk_size) {
+    ctx->chunk_size *= 2;
+  }
+
+  mongory_memory_node *new_chunk = mongory_memory_chunk_new(ctx->chunk_size);
+  if (!new_chunk) {
+    return false; // Failed to create a new chunk.
+  }
+
+  // Link the new chunk and update the current pointer.
+  ctx->current->next = new_chunk;
+  ctx->current = new_chunk;
+
+  return true;
+}
+
+/**
+ * @brief Allocates memory from the pool. Implements `pool->alloc`.
+ *
+ * Allocates `size` bytes (aligned to 8 bytes) from the `current` chunk.
+ * If the current chunk doesn't have enough space, `mongory_memory_pool_grow`
+ * is called to add a new chunk.
+ *
+ * @param pool Pointer to the `mongory_memory_pool`.
+ * @param size The number of bytes to allocate.
+ * @return void* Pointer to the allocated memory, or NULL on failure.
+ */
+static inline void *mongory_memory_pool_alloc(mongory_memory_pool *pool, size_t size) {
+  mongory_memory_pool_ctx *pool_ctx = (mongory_memory_pool_ctx *)pool->ctx;
+  size = MONGORY_ALIGN8(size); // Ensure 8-byte alignment.
+
+  size_t balance = pool_ctx->current->size - pool_ctx->current->used;
+  if (size > balance) {
+    // Not enough space in current chunk, try to grow.
+    if (!mongory_memory_pool_grow(pool_ctx, size)) {
+      return NULL; // Growth failed.
+    }
+    // After successful growth, pool_ctx->current points to the new chunk.
+  }
+
+  // Allocate from the current chunk.
+  void *ptr = (char *)pool_ctx->current->ptr + pool_ctx->current->used;
+  pool_ctx->current->used += size;
+
+  return ptr;
+}
+
+static inline void mongory_memory_pool_reset(mongory_memory_pool *pool) {
+  mongory_memory_pool_ctx *pool_ctx = (mongory_memory_pool_ctx *)pool->ctx;
+  pool_ctx->current = pool_ctx->head;
+  mongory_memory_node *node = pool_ctx->head;
+  while (node) {
+    node->used = 0;
+    node = node->next;
+  }
+}
+
+/**
+ * @brief Frees a linked list of memory nodes.
+ *
+ * Iterates through the list, freeing the memory block (`node->ptr`) and then
+ * the node structure itself for each node. Memory blocks are zeroed out before
+ * freeing for security/safety.
+ *
+ * @param head Pointer to the head of the memory node list to free.
+ */
+static inline void mongory_memory_pool_node_list_free(mongory_memory_node *head) {
+  mongory_memory_node *node = head;
+  while (node) {
+    mongory_memory_node *next = node->next;
+    if (node->ptr) {
+      memset(node->ptr, 0, node->size); // Clear memory for safety.
+      free(node->ptr);                  // Free the actual memory block.
+    }
+    memset(node, 0,
+           sizeof(mongory_memory_node)); // Clear the node structure itself.
+    free(node);                          // Free the node structure.
+    node = next;
+  }
+}
+
+/**
+ * @brief Destroys the memory pool and frees all associated memory.
+ * Implements `pool->free`.
+ *
+ * Frees all memory chunks allocated by the pool (`ctx->head` list) and all
+ * externally traced memory blocks (`ctx->extra` list). Then frees the pool
+ * context and the pool structure itself.
+ *
+ * @param pool Pointer to the `mongory_memory_pool` to destroy.
+ */
+static inline void mongory_memory_pool_destroy(mongory_memory_pool *pool) {
+  if (!pool)
+    return;
+  mongory_memory_pool_ctx *ctx = (mongory_memory_pool_ctx *)pool->ctx;
+
+  if (ctx) {
+    // Free the main list of memory chunks.
+    mongory_memory_pool_node_list_free(ctx->head);
+    // Free the list of externally traced memory chunks.
+    mongory_memory_pool_node_list_free(ctx->extra);
+
+    memset(ctx, 0,
+           sizeof(mongory_memory_pool_ctx)); // Clear the context structure.
+    free(ctx);                               // Free the context structure.
+  }
+
+  memset(pool, 0, sizeof(mongory_memory_pool)); // Clear the pool structure.
+  free(pool);                                   // Free the pool structure.
+}
+
+/**
+ * @brief Traces an externally allocated piece of memory. Implements
+ * `pool->trace`.
+ *
+ * Creates a new `mongory_memory_node` to track the external memory block and
+ * adds it to the `extra` list in the pool's context. This memory will be
+ * freed when `mongory_memory_pool_destroy` is called if this trace function
+ * is used.
+ *
+ * @param pool Pointer to the `mongory_memory_pool`.
+ * @param ptr Pointer to the externally allocated memory.
+ * @param size Size of the externally allocated memory.
+ */
+static inline void mongory_memory_pool_trace(mongory_memory_pool *pool, void *ptr, size_t size) {
+  mongory_memory_pool_ctx *pool_ctx = (mongory_memory_pool_ctx *)pool->ctx;
+
+  // Create a new node to trace this external allocation.
+  mongory_memory_node *extra_alloc_tracer = calloc(1, sizeof(mongory_memory_node));
+  if (!extra_alloc_tracer) {
+    // Allocation of tracer node failed; cannot trace.
+    // This might lead to a leak of 'ptr' if the caller expects the pool to
+    // manage it. Consider error reporting.
+    return;
+  }
+  extra_alloc_tracer->ptr = ptr;              // This is the externally allocated memory.
+  extra_alloc_tracer->size = size;            // Its size.
+  extra_alloc_tracer->used = size;            // Mark as fully "used" in context of tracing.
+  extra_alloc_tracer->next = pool_ctx->extra; // Prepend to extra list.
+  pool_ctx->extra = extra_alloc_tracer;
+}
+
+/**
+ * @brief Creates and initializes a new memory pool.
+ *
+ * Allocates the `mongory_memory_pool` structure, its internal
+ * `mongory_memory_pool_ctx`, and the first memory chunk. Sets up the function
+ * pointers for `alloc`, `free`, and `trace`.
+ *
+ * @return mongory_memory_pool* Pointer to the new pool, or NULL on failure.
+ */
+mongory_memory_pool *mongory_memory_pool_new() {
+  // Allocate the main pool structure.
+  mongory_memory_pool *pool = calloc(1, sizeof(mongory_memory_pool));
+  if (!pool) {
+    return NULL;
+  }
+
+  // Allocate the internal context for the pool.
+  mongory_memory_pool_ctx *ctx = calloc(1, sizeof(mongory_memory_pool_ctx));
+  if (!ctx) {
+    free(pool); // Clean up partially allocated pool.
+    return NULL;
+  }
+
+  // Allocate the first memory chunk.
+  mongory_memory_node *first_chunk = mongory_memory_chunk_new(MONGORY_INITIAL_CHUNK_SIZE);
+  if (!first_chunk) {
+    free(ctx);  // Clean up context.
+    free(pool); // Clean up pool structure.
+    return NULL;
+  }
+
+  // Initialize context fields.
+  ctx->chunk_size = MONGORY_INITIAL_CHUNK_SIZE;
+  ctx->head = first_chunk;
+  ctx->current = first_chunk;
+  ctx->extra = NULL; // No extra traced allocations initially.
+
+  // Initialize pool fields.
+  pool->ctx = ctx;
+  pool->alloc = mongory_memory_pool_alloc;
+  pool->reset = mongory_memory_pool_reset;
+  pool->free = mongory_memory_pool_destroy;
+  pool->trace = mongory_memory_pool_trace;
+  pool->error = NULL; // No error initially.
+
+  return pool;
+}