Add custom allocator support

1 files changed, 201 insertions, 61 deletions

diff --git a/include/serd/serd.h b/include/serd/serd.h
index 9e322c0d..2300a1a4 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -197,7 +197,102 @@ typedef struct {
 
 /**
    @}
+   @defgroup serd_memory Memory Management
+   @{
+*/
+
+struct SerdAllocatorImpl;
+
+/**
+   A memory allocator.
+
+   This object-like structure provides an interface like the standard C
+   functions malloc(), calloc(), realloc(), free(), and aligned_alloc().  It
+   contains function pointers that differ from their standard counterparts by
+   taking a context parameter (a pointer to this struct), which allows the user
+   to implement custom stateful allocators.
+*/
+typedef struct SerdAllocatorImpl SerdAllocator;
+
+/**
+   General malloc-like memory allocation function.
+
+   This works like the standard C malloc(), except has an additional handle
+   parameter for implementing stateful allocators without static data.
+*/
+typedef void* SERD_ALLOCATED (*SerdAllocatorMallocFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  size_t                       size);
+
+/**
+   General calloc-like memory allocation function.
+
+   This works like the standard C calloc(), except has an additional handle
+   parameter for implementing stateful allocators without static data.
+*/
+typedef void* SERD_ALLOCATED (*SerdAllocatorCallocFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  size_t                       nmemb,
+  size_t                       size);
+
+/**
+   General realloc-like memory reallocation function.
+
+   This works like the standard C remalloc(), except has an additional handle
+   parameter for implementing stateful allocators without static data.
+*/
+typedef void* SERD_ALLOCATED (*SerdAllocatorReallocFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  void* SERD_NULLABLE          ptr,
+  size_t                       size);
+
+/**
+   General free-like memory deallocation function.
+
+   This works like the standard C remalloc(), except has an additional handle
+   parameter for implementing stateful allocators without static data.
 */
+typedef void (*SerdAllocatorFreeFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  void* SERD_NULLABLE          ptr);
+
+/**
+   General aligned_alloc-like memory deallocation function.
+
+   This works like the standard C aligned_alloc(), except has an additional
+   handle parameter for implementing stateful allocators without static data.
+*/
+typedef void* SERD_ALLOCATED (*SerdAllocatorAlignedAllocFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  size_t                       alignment,
+  size_t                       size);
+
+/**
+   General aligned memory deallocation function.
+
+   This works like the standard C free(), but must be used to free memory
+   allocated with the aligned_alloc() method of the allocator.  This allows
+   portability to systems (like Windows) that can not use the same free function
+   in these cases.
+*/
+typedef void (*SerdAllocatorAlignedFreeFunc)( //
+  SerdAllocator* SERD_NULLABLE allocator,
+  void* SERD_NULLABLE          ptr);
+
+/// Definition of SerdAllocator
+struct SerdAllocatorImpl {
+  SerdAllocatorMallocFunc SERD_ALLOCATED       malloc;
+  SerdAllocatorCallocFunc SERD_ALLOCATED       calloc;
+  SerdAllocatorReallocFunc SERD_ALLOCATED      realloc;
+  SerdAllocatorFreeFunc SERD_ALLOCATED         free;
+  SerdAllocatorAlignedAllocFunc SERD_ALLOCATED aligned_alloc;
+  SerdAllocatorAlignedFreeFunc SERD_ALLOCATED  aligned_free;
+};
+
+/// Return the default allocator which simply uses the system allocator
+SERD_CONST_API
+SerdAllocator* SERD_NONNULL
+serd_default_allocator(void);
 
 /**
    Free memory allocated by Serd.
@@ -205,12 +300,15 @@ typedef struct {
    This function exists because some systems require memory allocated by a
    library to be freed by code in the same library.  It is otherwise equivalent
    to the standard C free() function.
+
+   This may be used to free memory allocated using serd_default_allocator().
 */
 SERD_API
 void
-serd_free(void* SERD_NULLABLE ptr);
+serd_free(SerdAllocator* SERD_NULLABLE allocator, void* SERD_NULLABLE ptr);
 
 /**
+   @}
    @defgroup serd_status Status Codes
    @{
 */
@@ -283,11 +381,13 @@ serd_strerror(SerdStatus status);
    directory separators.  Null is returned on error, including if the path does
    not exist.
 
-   @return A new string that must be freed with serd_free(), or null.
+   @return A newly allocated string that must be freed with serd_free() using
+   the world allocator, or null.
 */
 SERD_API
-char* SERD_NULLABLE
-serd_canonical_path(const char* SERD_NONNULL path);
+char* SERD_ALLOCATED
+serd_canonical_path(SerdAllocator* SERD_NULLABLE allocator,
+                    const char* SERD_NONNULL     path);
 
 /**
    Compare two strings ignoring case.
@@ -462,13 +562,16 @@ serd_parse_uri(const char* SERD_NONNULL string);
 
    The returned path and `*hostname` must be freed with serd_free().
 
+   @param allocator Allocator for the returned string.
    @param uri A file URI.
    @param hostname If non-NULL, set to the hostname, if present.
-   @return A filesystem path.
+
+   @return A newly allocated path string that must be freed with serd_free().
 */
 SERD_API
 char* SERD_NULLABLE
-serd_parse_file_uri(const char* SERD_NONNULL          uri,
+serd_parse_file_uri(SerdAllocator* SERD_NULLABLE      allocator,
+                    const char* SERD_NONNULL          uri,
                     char* SERD_NONNULL* SERD_NULLABLE hostname);
 
 /**
@@ -856,7 +959,8 @@ serd_node_construct_base64(size_t                   buf_size,
    @defgroup serd_node_allocation Dynamic Allocation
 
    This is a convenient higher-level node construction API which allocates
-   nodes on the heap.  The returned nodes must be freed with serd_node_free().
+   nodes with an allocator.  The returned nodes must be freed with
+   serd_node_free() using the same allocator.
 
    Note that in most cases it is better to use a #SerdNodes instead of managing
    individual node allocations.
@@ -875,10 +979,11 @@ serd_node_construct_base64(size_t                   buf_size,
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_node_new(SerdNodeType   type,
-              SerdStringView string,
-              SerdNodeFlags  flags,
-              SerdStringView meta);
+serd_node_new(SerdAllocator* SERD_NULLABLE allocator,
+              SerdNodeType                 type,
+              SerdStringView               string,
+              SerdNodeFlags                flags,
+              SerdStringView               meta);
 
 /**
    Create a new simple "token" node.
@@ -891,7 +996,9 @@ serd_node_new(SerdNodeType   type,
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_token(SerdNodeType type, SerdStringView string);
+serd_new_token(SerdAllocator* SERD_NULLABLE allocator,
+               SerdNodeType                 type,
+               SerdStringView               string);
 
 /**
    Create a new string literal node.
@@ -904,7 +1011,7 @@ serd_new_token(SerdNodeType type, SerdStringView string);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_string(SerdStringView string);
+serd_new_string(SerdAllocator* SERD_NULLABLE allocator, SerdStringView string);
 
 /**
    Create a new URI node from a string.
@@ -917,7 +1024,7 @@ serd_new_string(SerdStringView string);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_uri(SerdStringView string);
+serd_new_uri(SerdAllocator* SERD_NULLABLE allocator, SerdStringView string);
 
 /**
    Create a new URI node from a parsed URI.
@@ -930,7 +1037,7 @@ serd_new_uri(SerdStringView string);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_parsed_uri(SerdURIView uri);
+serd_new_parsed_uri(SerdAllocator* SERD_NULLABLE allocator, SerdURIView uri);
 
 /**
    Create a new file URI node from a path and optional hostname.
@@ -943,7 +1050,9 @@ serd_new_parsed_uri(SerdURIView uri);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_file_uri(SerdStringView path, SerdStringView hostname);
+serd_new_file_uri(SerdAllocator* SERD_NULLABLE allocator,
+                  SerdStringView               path,
+                  SerdStringView               hostname);
 
 /**
    Create a new literal node.
@@ -956,9 +1065,10 @@ serd_new_file_uri(SerdStringView path, SerdStringView hostname);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_literal(SerdStringView string,
-                 SerdNodeFlags  flags,
-                 SerdStringView meta);
+serd_new_literal(SerdAllocator* SERD_NULLABLE allocator,
+                 SerdStringView               string,
+                 SerdNodeFlags                flags,
+                 SerdStringView               meta);
 
 /**
    Create a new canonical xsd:boolean node.
@@ -971,7 +1081,7 @@ serd_new_literal(SerdStringView string,
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_boolean(bool b);
+serd_new_boolean(SerdAllocator* SERD_NULLABLE allocator, bool b);
 
 /**
    Create a new canonical xsd:decimal literal.
@@ -984,7 +1094,7 @@ serd_new_boolean(bool b);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_decimal(double d);
+serd_new_decimal(SerdAllocator* SERD_NULLABLE allocator, double d);
 
 /**
    Create a new canonical xsd:double literal.
@@ -997,7 +1107,7 @@ serd_new_decimal(double d);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_double(double d);
+serd_new_double(SerdAllocator* SERD_NULLABLE allocator, double d);
 
 /**
    Create a new canonical xsd:float literal.
@@ -1010,7 +1120,7 @@ serd_new_double(double d);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_float(float f);
+serd_new_float(SerdAllocator* SERD_NULLABLE allocator, float f);
 
 /**
    Create a new canonical xsd:integer literal.
@@ -1023,7 +1133,9 @@ serd_new_float(float f);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_integer(int64_t i, SerdStringView datatype);
+serd_new_integer(SerdAllocator* SERD_NULLABLE allocator,
+                 int64_t                      i,
+                 SerdStringView               datatype);
 
 /**
    Create a new canonical xsd:base64Binary literal.
@@ -1036,9 +1148,10 @@ serd_new_integer(int64_t i, SerdStringView datatype);
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_new_base64(const void* SERD_NONNULL buf,
-                size_t                   size,
-                SerdStringView           datatype);
+serd_new_base64(SerdAllocator* SERD_NULLABLE allocator,
+                const void* SERD_NONNULL     buf,
+                size_t                       size,
+                SerdStringView               datatype);
 
 /**
    @}
@@ -1125,12 +1238,14 @@ serd_get_base64(const SerdNode* SERD_NONNULL node,
 /// Return a deep copy of `node`
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_node_copy(const SerdNode* SERD_NULLABLE node);
+serd_node_copy(SerdAllocator* SERD_NULLABLE  allocator,
+               const SerdNode* SERD_NULLABLE node);
 
 /// Free any data owned by `node`
 SERD_API
 void
-serd_node_free(SerdNode* SERD_NULLABLE node);
+serd_node_free(SerdAllocator* SERD_NULLABLE allocator,
+               SerdNode* SERD_NULLABLE      node);
 
 /// Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL)
 SERD_PURE_API
@@ -1220,7 +1335,7 @@ typedef struct SerdNodesImpl SerdNodes;
 /// Create a new node set
 SERD_API
 SerdNodes* SERD_ALLOCATED
-serd_nodes_new(void);
+serd_nodes_new(SerdAllocator* SERD_NULLABLE allocator);
 
 /**
    Free `nodes` and all nodes that are stored in it.
@@ -1307,9 +1422,6 @@ serd_nodes_parsed_uri(SerdNodes* SERD_NONNULL nodes, SerdURIView uri);
    #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI.  If
    #SERD_HAS_LANGUAGE is set, then this must be an RFC 5646 language tag like
    "en-ca".  Otherwise, it is ignored.
-
-   @return A newly allocated literal node that must be freed with
-   serd_node_free(), or null if the arguments are invalid or allocation failed.
 */
 SERD_API
 const SerdNode* SERD_ALLOCATED
@@ -1422,6 +1534,7 @@ typedef struct SerdCaretImpl SerdCaret;
    valid.  That is, serd_caret_name() will return exactly the pointer
    `name`, not a copy.
 
+   @param allocator Allocator to use for caret memory.
    @param name The name of the document or stream (usually a file URI)
    @param line The line number in the document (1-based)
    @param col The column number in the document (1-based)
@@ -1429,17 +1542,22 @@ typedef struct SerdCaretImpl SerdCaret;
 */
 SERD_API
 SerdCaret* SERD_ALLOCATED
-serd_caret_new(const SerdNode* SERD_NONNULL name, unsigned line, unsigned col);
+serd_caret_new(SerdAllocator* SERD_NULLABLE allocator,
+               const SerdNode* SERD_NONNULL name,
+               unsigned                     line,
+               unsigned                     col);
 
 /// Return a copy of `caret`
 SERD_API
 SerdCaret* SERD_ALLOCATED
-serd_caret_copy(const SerdCaret* SERD_NULLABLE caret);
+serd_caret_copy(SerdAllocator* SERD_NULLABLE   allocator,
+                const SerdCaret* SERD_NULLABLE caret);
 
 /// Free `caret`
 SERD_API
 void
-serd_caret_free(SerdCaret* SERD_NULLABLE caret);
+serd_caret_free(SerdAllocator* SERD_NULLABLE allocator,
+                SerdCaret* SERD_NULLABLE     caret);
 
 /// Return true iff `lhs` is equal to `rhs`
 SERD_PURE_API
@@ -1492,6 +1610,7 @@ typedef enum {
    statements in models, this is the lifetime of the model.  For user-created
    statements, the simplest way to handle this is to use `SerdNodes`.
 
+   @param allocator Allocator to use for statement memory.
    @param s The subject
    @param p The predicate ("key")
    @param o The object ("value")
@@ -1501,7 +1620,8 @@ typedef enum {
 */
 SERD_API
 SerdStatement* SERD_ALLOCATED
-serd_statement_new(const SerdNode* SERD_NONNULL   s,
+serd_statement_new(SerdAllocator* SERD_NULLABLE   allocator,
+                   const SerdNode* SERD_NONNULL   s,
                    const SerdNode* SERD_NONNULL   p,
                    const SerdNode* SERD_NONNULL   o,
                    const SerdNode* SERD_NULLABLE  g,
@@ -1510,12 +1630,14 @@ serd_statement_new(const SerdNode* SERD_NONNULL   s,
 /// Return a copy of `statement`
 SERD_API
 SerdStatement* SERD_ALLOCATED
-serd_statement_copy(const SerdStatement* SERD_NULLABLE statement);
+serd_statement_copy(SerdAllocator* SERD_NULLABLE       allocator,
+                    const SerdStatement* SERD_NULLABLE statement);
 
 /// Free `statement`
 SERD_API
 void
-serd_statement_free(SerdStatement* SERD_NULLABLE statement);
+serd_statement_free(SerdAllocator* SERD_NULLABLE allocator,
+                    SerdStatement* SERD_NULLABLE statement);
 
 /// Return the given node of the statement
 SERD_PURE_API
@@ -1590,13 +1712,18 @@ typedef struct SerdWorldImpl SerdWorld;
 */
 SERD_MALLOC_API
 SerdWorld* SERD_ALLOCATED
-serd_world_new(void);
+serd_world_new(SerdAllocator* SERD_NULLABLE allocator);
 
 /// Free `world`
 SERD_API
 void
 serd_world_free(SerdWorld* SERD_NULLABLE world);
 
+/// Return the allocator used by `world`
+SERD_PURE_API
+SerdAllocator* SERD_NONNULL
+serd_world_allocator(const SerdWorld* SERD_NONNULL world);
+
 /**
    Return the nodes cache in `world`.
 
@@ -2057,7 +2184,8 @@ serd_env_new(SerdWorld* SERD_NONNULL world, SerdStringView base_uri);
 /// Copy an environment
 SERD_API
 SerdEnv* SERD_ALLOCATED
-serd_env_copy(const SerdEnv* SERD_NULLABLE env);
+serd_env_copy(SerdAllocator* SERD_NULLABLE allocator,
+              const SerdEnv* SERD_NULLABLE env);
 
 /// Return true iff `a` is equal to `b`
 SERD_PURE_API
@@ -2152,6 +2280,9 @@ serd_env_write_prefixes(const SerdEnv* SERD_NONNULL  env,
    serd_node_to_syntax().  These two functions, when used with #SERD_TURTLE,
    can be used to round-trip any node to a string and back.
 
+   @param allocator Allocator used for the returned node, and any temporary
+   objects if `env` is null.
+
    @param str String representation of a node.
 
    @param syntax Syntax to use.  Should be either SERD_TURTLE or SERD_NTRIPLES
@@ -2161,13 +2292,15 @@ serd_env_write_prefixes(const SerdEnv* SERD_NONNULL  env,
    @param env Environment of `str`.  This must define any abbreviations needed
    to parse the string.
 
-   @return A newly allocated node that must be freed with serd_node_free().
+   @return A newly allocated node that must be freed with serd_node_free()
+   using the world allocator.
 */
 SERD_API
 SerdNode* SERD_ALLOCATED
-serd_node_from_syntax(const char* SERD_NONNULL str,
-                      SerdSyntax               syntax,
-                      SerdEnv* SERD_NULLABLE   env);
+serd_node_from_syntax(SerdAllocator* SERD_NULLABLE allocator,
+                      const char* SERD_NONNULL     str,
+                      SerdSyntax                   syntax,
+                      SerdEnv* SERD_NULLABLE       env);
 
 /**
    Return a string representation of `node` in `syntax`.
@@ -2175,6 +2308,9 @@ serd_node_from_syntax(const char* SERD_NONNULL str,
    The returned string represents that node as if written as an object in the
    given syntax, without any extra quoting or punctuation.
 
+   @param allocator Allocator used for the returned node, and any temporary
+   objects if `env` is null.
+
    @param node Node to write as a string.
 
    @param syntax Syntax to use.  Should be either SERD_TURTLE or SERD_NTRIPLES
@@ -2184,11 +2320,13 @@ serd_node_from_syntax(const char* SERD_NONNULL str,
    @param env Environment for the output string.  This can be used to
    abbreviate things nicely by setting namespace prefixes.
 
-   @return A newly allocated string that must be freed with serd_free().
+   @return A newly allocated string that must be freed with serd_free() using
+   the world allocator.
 */
 SERD_API
 char* SERD_ALLOCATED
-serd_node_to_syntax(const SerdNode* SERD_NONNULL node,
+serd_node_to_syntax(SerdAllocator* SERD_NULLABLE allocator,
+                    const SerdNode* SERD_NONNULL node,
                     SerdSyntax                   syntax,
                     const SerdEnv* SERD_NULLABLE env);
 
@@ -2418,26 +2556,26 @@ serd_reader_free(SerdReader* SERD_NULLABLE reader);
    @defgroup serd_buffer Buffer
 
    The #SerdBuffer type represents a writable area of memory with a known size.
-   An implementation of #SerdWriteFunc, #SerdErrorFunc, and
-   #SerdCloseFunc are provided which allow output to be written to a
-   buffer in memory instead of to a file as with `fwrite`, `ferror`, and
-   `fclose`.
+   An implementation of #SerdWriteFunc, #SerdErrorFunc, and #SerdCloseFunc are
+   provided which allow output to be written to a buffer in memory instead of
+   to a file as with `fwrite`, `ferror`, and `fclose`.
 
    @{
 */
 
-/// A mutable buffer in memory
+/// A dynamically resizable mutable buffer in memory
 typedef struct {
-  void* SERD_NULLABLE buf; ///< Buffer
-  size_t              len; ///< Size of buffer in bytes
+  SerdAllocator* SERD_NULLABLE allocator; ///< Allocator for buf
+  void* SERD_NULLABLE          buf;       ///< Buffer
+  size_t                       len;       ///< Size of buffer in bytes
 } SerdBuffer;
 
 /**
    A function for writing to a buffer, resizing it if necessary.
 
    This function can be used as a #SerdWriteFunc to write to a #SerdBuffer
-   which is resized as necessary with realloc().  The `stream` parameter must
-   point to an initialized #SerdBuffer.
+   which is reallocated as necessary.  The `stream` parameter must point to an
+   initialized #SerdBuffer.
 
    Note that when writing a string, the string in the buffer will not be
    null-terminated until serd_buffer_close() is called.
@@ -2498,9 +2636,9 @@ serd_open_output_stream(SerdWriteFunc SERD_NONNULL  write_func,
 /**
    Open a stream that writes to a buffer.
 
-   The `buffer` is owned by the caller, but will be expanded using `realloc` as
-   necessary.  Note that the string in the buffer will not be null terminated
-   until the stream is closed.
+   The `buffer` is owned by the caller, but will be reallocated using the
+   buffer's allocator as necessary.  Note that the string in the buffer will
+   not be null terminated until the stream is closed.
 
    @param buffer Buffer to write output to.
    @return An opened output stream, or all zeros on error.
@@ -2690,7 +2828,8 @@ typedef struct SerdCursorImpl SerdCursor;
 /// Return a new copy of `cursor`
 SERD_API
 SerdCursor* SERD_ALLOCATED
-serd_cursor_copy(const SerdCursor* SERD_NULLABLE cursor);
+serd_cursor_copy(SerdAllocator* SERD_NULLABLE    allocator,
+                 const SerdCursor* SERD_NULLABLE cursor);
 
 /// Return the statement pointed to by `cursor`
 SERD_API
@@ -2826,7 +2965,8 @@ serd_model_new(SerdWorld* SERD_NONNULL world,
 /// Return a deep copy of `model`
 SERD_API
 SerdModel* SERD_ALLOCATED
-serd_model_copy(const SerdModel* SERD_NONNULL model);
+serd_model_copy(SerdAllocator* SERD_NULLABLE  allocator,
+                const SerdModel* SERD_NONNULL model);
 
 /// Return true iff `a` is equal to `b`, ignoring statement cursor metadata
 SERD_API