Completed memory alloc docs

RELEASE_NOTES.md

@@ -5,6 +5,8 @@ Release Notes v2.0 (work in progress)
 Changes
 -------
 
+- Memory allocation debugging can be switched on and off dynamically
+- Memory allocation functions are available for the main application
 - Full API documentation now available at [`www.libhttp.org/api-reference/`](http://www.libhttp.org/api-reference/)
 - Changed function and structure prefix from `mg_` to `httplib_`
 - Search in MIME types list now costs O(log(N)) instead of O(N)

doc/api/httplib_calloc.md

@@ -0,0 +1,29 @@
+# LibHTTP API Reference
+
+### `httplib_calloc:( count, size );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`count`**|`size_t`|The number of elements to allocate memory for|
+|**`size`**|`size_t`|The size of each individual element|
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`void *`|Pointer to the allocated memory block or `NULL` if an error occured|
+
+### Description
+
+The function `httplib_calloc()` tries to allocate a block of memory from the heap for an array elements with a specified size. If this succeeds, the function returns a pointer to the new block. Otherwise the value `NULL` is returned. If a callback function has been registered with the [`set_alloc_callback_func()`](set_alloc_callback_func.md) function, this function will be called to signal to the main application that a block of memory has been allocated. If a callback function has been registered and the allocation of memory fails, the value **0** is passed as the `current_bytes` parameter.
+
+Due to the allocation of extra data space for tracking the memory allocation, the LibHTTP memory management functions including the `httplib_calloc()` function are incompatible with the memory allocation functions provided by the platform. Memory allocated with one set of functions can not be reallocated or freed by the others. Memory corruption or crashes may occur in that case.
+
+### See Also
+
+* [`httplib_free();`](httplib_free.md)
+* [`httplib_malloc();`](httplib_malloc.md)
+* [`httplib_realloc();`](httplib_realloc.md)
+* [`httplib_set_alloc_callback_func();`](httplib_set_alloc_callback_func.md)

doc/api/httplib_free.md

@@ -0,0 +1,26 @@
+# LibHTTP API Reference
+
+### `httplib_free( ptr );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`ptr`**|`void *`|Pointer to the memory block which must be freed|
+
+### Return Value
+
+*none*
+
+### Description
+
+The function `httplib_free()` frees a block of memory which has been previously allocated by [`httplib_calloc()`](httplib_calloc.md), [`httplib_malloc()`](httplib_malloc.md) or [`httplib_realloc()`](httplib_realloc.md). If a callback function has been registered with the [`set_alloc_callback_func()`](set_alloc_callback_func.md) function, this function will be called to signal to the main application that a block of memory has been freed. The amount of bytes passed to the callback function is negative, to indacte that memory has been returned to the heap.
+
+Due to the allocation of extra data space for tracking the memory allocation, the LibHTTP memory management functions including the `httplib_free()` function are incompatible with the memory allocation functions provided by the platform. Memory allocated with one set of functions can not be reallocated or freed by the others. Memory corruption or crashes may occur in that case.
+
+### See Also
+
+* [`httplib_calloc();`](httplib_calloc.md)
+* [`httplib_malloc();`](httplib_malloc.md)
+* [`httplib_realloc();`](httplib_realloc.md)
+* [`httplib_set_alloc_callback_func();`](httplib_set_alloc_callback_func.md)

doc/api/httplib_malloc.md

@@ -0,0 +1,28 @@
+# LibHTTP API Reference
+
+### `httplib_malloc( size );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`size`**|`size_t`|The amount of bytes to allocate|
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`void *`|Pointer to the allocated memory block or `NULL` if an error occured|
+
+### Description
+
+The function `httplib_malloc()` tries to allocate a block of memory from the heap with a specified size. If this succeeds, the function returns a pointer to the new block. Otherwise the value `NULL` is returned. If a callback function has been registered with the [`set_alloc_callback_func()`](set_alloc_callback_func.md) function, this function will be called to signal to the main application that a block of memory has been allocated. If a callback function has been registered and the allocation of memory fails, the value **0** is passed as the `current_bytes` parameter.
+
+Due to the allocation of extra data space for tracking the memory allocation, the LibHTTP memory management functions including the `httplib_malloc()` function are incompatible with the memory allocation functions provided by the platform. Memory allocated with one set of functions can not be reallocated or freed by the others. Memory corruption or crashes may occur in that case.
+
+### See Also
+
+* [`httplib_calloc();`](httplib_calloc.md)
+* [`httplib_free();`](httplib_free.md)
+* [`httplib_realloc();`](httplib_realloc.md)
+* [`httplib_set_alloc_callback_func();`](httplib_set_alloc_callback_func.md)

doc/api/httplib_realloc.md

@@ -0,0 +1,33 @@
+# LibHTTP API Reference
+
+### `httplib_realloc( ptr, size );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`ptr`**|`void *`|A pointer to the existing memory block|
+|**`size`**|`size_t`|The amount of bytes to allocate|
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`void *`|Pointer to the allocated memory block or `NULL` if an error occured|
+
+### Description
+
+The function `httplib_realloc()` tries to change the size of an existing allocated memory block. A pointer to the existing memory area is passed together with the requested new size. new size can both be smaller or larger than the current size of the memory block. The returned pointer can be the same pointer to the original memory block, or a new pointer to another location. In that case the contents of the memory block have been copied to the new location.
+
+If the `ptr` parameter is NULL, the function `httplib_realloc()` is equivalent to [`httplib_malloc();`](httplib_malloc.md). If the parameter `size` is **0**, the function `httplib_realloc()` will be equal to [`httplib_free();`](httplib_free.md).
+
+If a callback function has been registered with the [`set_alloc_callback_func()`](set_alloc_callback_func.md) function, this function will be called to signal to the main application that a block of memory has been allocated. If a callback function has been registered and the allocation of memory fails, the value **0** is passed as the `current_bytes` parameter. Please note that the `current_bytes` parameter passed to the callback function can both be a positive and negative value. A positive value indicates that the size of the memory block has increased while a negative value signals a decrease in the allocated size.
+
+Due to the allocation of extra data space for tracking the memory allocation, the LibHTTP memory management functions including the `httplib_realloc()` function are incompatible with the memory allocation functions provided by the platform. Memory allocated with one set of functions can not be reallocated or freed by the others. Memory corruption or crashes may occur in that case.
+
+### See Also
+
+* [`httplib_calloc();`](httplib_calloc.md)
+* [`httplib_free();`](httplib_free.md)
+* [`httplib_realloc();`](httplib_malloc.md)
+* [`httplib_set_alloc_callback_func();`](httplib_set_alloc_callback_func.md)

src/httplib_malloc.c

@@ -22,7 +22,7 @@
  * THE SOFTWARE.
  *
  * ============
- * Release: 1.8
+ * Release: 2.0
  */
 
 #include "httplib_main.h"
@@ -56,8 +56,19 @@ LIBHTTP_API void *XX_httplib_malloc_ex( size_t size, const char *file, unsigned
 
 	size_t *data;
 
+	if ( size == 0 ) {
+
+		if ( alloc_log_func != NULL ) alloc_log_func( file, line, "malloc", 0, httplib_memory_blocks_used, httplib_memory_bytes_used );
+		return NULL;
+	}
+
 	data = malloc( size + sizeof(size_t) );
-	if ( data == NULL ) return NULL;
+
+	if ( data == NULL ) {
+	
+		if ( alloc_log_func != NULL ) alloc_log_func( file, line, "malloc", 0, httplib_memory_blocks_used, httplib_memory_bytes_used );
+		return NULL;
+	}
 
 	httplib_memory_bytes_used += size;
 	httplib_memory_blocks_used++;
@@ -71,6 +82,19 @@ LIBHTTP_API void *XX_httplib_malloc_ex( size_t size, const char *file, unsigned
 }  /* XX_httplib_malloc_ex */
 
 
+
+/*
+ * void *XX_httplib_calloc_ex( size_t count, size_t size, const char *file, unsigned line );
+ *
+ * The function XX_httplib_calloc_ex() is a hidden memory allocation function
+ * called through a macro which adds the filename and line number from where
+ * the function has been called.
+ *
+ * The function provided memory allocation functionality like the standard
+ * calloc() function but with added memory tracking and optional a callback
+ * to main application with logging information.
+ */
+
 LIBHTTP_API void *XX_httplib_calloc_ex( size_t count, size_t size, const char *file, unsigned line ) {
 
 	void *data;
@@ -85,11 +109,26 @@ LIBHTTP_API void *XX_httplib_calloc_ex( size_t count, size_t size, const char *f
 }  /* XX_httplib_calloc_ex */
 
 
+
+/*
+ * void XX_httplib_free_ex( void *memory, const char *file, unsigned file );
+ *
+ * The function XX_httplib_free_ex() is a hidden function which frees a
+ * previously allocated memory object which was allocated with one of the
+ * LibHTTP allocation functions. The function has the option to do memory
+ * tracking and memory leak debugging through a callback function which can
+ * be registered by the main application.
+ */
+
 LIBHTTP_API void XX_httplib_free_ex( void *memory, const char *file, unsigned line ) {
 
 	size_t *data;
 
-	if ( memory == NULL ) return;
+	if ( memory == NULL ) {
+		
+		if ( alloc_log_func != NULL ) alloc_log_func( file, line, "free", 0, httplib_memory_blocks_used, httplib_memory_bytes_used );
+		return;
+	}
 
 	data = ((size_t *)memory) - 1;
 
@@ -103,6 +142,24 @@ LIBHTTP_API void XX_httplib_free_ex( void *memory, const char *file, unsigned li
 }  /* XX_httplib_free_ex */
 
 
+
+/*
+ * void *XX_httplib_realloc_ex( void *memory, size_t newsize, const char *file, unsigned line );
+ *
+ * The function XX_httplib_realloc_ex() is a hidden function used to resize
+ * a memory block which has been previously allocated from the heap. A macro is
+ * used to call this function together with the file name and line number
+ * where the call originates.
+ *
+ * The function returns a pointer to the new block, or NULL if an error occurs.
+ * If NULL is returned because there was not enough space to reallocate the
+ * block, the contents of the original block are preserved.
+ *
+ * Optionally a registered is called to signal the main application about the
+ * current and totally allocated memory. This can be used for debugging
+ * purposes and finding memory leaks.
+ */
+
 LIBHTTP_API void *XX_httplib_realloc_ex( void *memory, size_t newsize, const char *file, unsigned line ) {
 
 	size_t *olddata;
@@ -121,7 +178,11 @@ LIBHTTP_API void *XX_httplib_realloc_ex( void *memory, size_t newsize, const cha
 	olddata = ((size_t *)memory) - 1;
 	oldsize = *olddata;
 	newdata = realloc( olddata, newsize + sizeof(size_t) );
-	if ( newdata == NULL ) return NULL;
+	if ( newdata == NULL ) {
+		
+		if ( alloc_log_func != NULL ) alloc_log_func( file, line, "realloc", 0, httplib_memory_blocks_used, httplib_memory_bytes_used );
+		return NULL;
+	}
 
 	httplib_memory_bytes_used -= oldsize;
 	httplib_memory_bytes_used += newsize;