updates

Author: pavel-kirienko

README.md

@@ -238,6 +238,12 @@ If not overridden by the user, for some compilers `O1HEAP_CLZ(x)` will expand to
 For other compilers it will default to a slow software implementation,
 which is likely to significantly degrade the performance of the library.
 
+#### O1HEAP_TRACE
+
+This option is intended for advanced diagnostics and may be not useful in most applications.
+If defined and is nonzero, makes o1heap invoke `extern` trace functions (implemented in the application)
+on every allocation and deallocation. Please refer to `o1heap.h` for usage details.
+
 ## Development
 
 ### Dependencies

o1heap/o1heap.c

@@ -11,17 +11,15 @@
 // OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 //
-// Copyright (c) 2020 Pavel Kirienko
+// Copyright (c) Pavel Kirienko
 // Authors: Pavel Kirienko <[email protected]>
 
+// ReSharper disable CppDFANullDereference
+
 #include "o1heap.h"
 #include <assert.h>
 #include <limits.h>
 
-#ifdef O1HEAP_INCLUDE_CONFIG_HEADER
-#include "o1heap_config.h"
-#endif
-
 // ---------------------------------------- BUILD CONFIGURATION OPTIONS ----------------------------------------
 
 /// Define this macro to include build configuration header. This is an alternative to the -D compiler flag.
@@ -83,19 +81,18 @@ O1HEAP_PRIVATE uint_fast8_t O1HEAP_CLZ(const size_t x)
 }
 #endif
 
-/// By defining these symbols, preferably in o1heap_config.h (define O1HEAP_INCLUDE_CONFIG_HEADER to include, see
-/// above), trace tools can get events when o1heap memory is allocated or free'ed. For allocations, note that
-/// if the allocated memory pointer is NULL an allocation failure has occurred. In this case the size reported is
-//  the number of bytes requested that the allocator could not provide.
-///
-/// When using the pointer provided via O1HEAP_TRACE_FREE the pointer memory must not be accessed. This pointer
-/// should only be used for its address.
-
-#ifndef O1HEAP_TRACE_ALLOCATE
-#   define O1HEAP_TRACE_ALLOCATE(handle, pointer, size)
+/// If O1HEAP_TRACE is defined and is nonzero, trace tools can get events when o1heap memory is allocated or freed.
+/// The corresponding events are delivered by invoking extern functions o1heapTraceAllocate() etc, defined in the
+/// application. Please refer to the documentation for those functions for the additional information.
+#ifndef O1HEAP_TRACE
+#    define O1HEAP_TRACE 0
 #endif
-#ifndef O1HEAP_TRACE_FREE
-#   define O1HEAP_TRACE_FREE(handle, pointer, size)
+#if O1HEAP_TRACE
+#    define O1HEAP_TRACE_ALLOCATE(handle, pointer, size) o1heapTraceAllocate(handle, pointer, size)
+#    define O1HEAP_TRACE_FREE(handle, pointer, size) o1heapTraceFree(handle, pointer, size)
+#else
+#    define O1HEAP_TRACE_ALLOCATE(handle, pointer, size) (void) 0
+#    define O1HEAP_TRACE_FREE(handle, pointer, size) (void) 0
 #endif
 
 // ---------------------------------------- INTERNAL DEFINITIONS ----------------------------------------
@@ -259,12 +256,6 @@ O1HEAP_PRIVATE void unbin(O1HeapInstance* const handle, const Fragment* const fr
     }
 }
 
-#ifdef O1HEAP_TRACE
-// The user must implement these functions or linking will fail.
-extern void o1heapAllocateTrace(O1HeapInstance* const handle, void* const allocated_memory, size_t size_bytes);
-extern void o1heapFreeTrace(O1HeapInstance* const handle, void* const freed_memory, size_t size_bytes);
-#endif
-
 // ---------------------------------------- PUBLIC API IMPLEMENTATION ----------------------------------------
 
 O1HeapInstance* o1heapInit(void* const base, const size_t size)
@@ -391,10 +382,14 @@ void* o1heapAllocate(O1HeapInstance* const handle, const size_t amount)
 
             out = ((char*) frag) + O1HEAP_ALIGNMENT;
             O1HEAP_TRACE_ALLOCATE(handle, out, frag->header.size);
-        } else {
+        }
+        else
+        {
             O1HEAP_TRACE_ALLOCATE(handle, out, amount);
         }
-    } else {
+    }
+    else
+    {
         O1HEAP_TRACE_ALLOCATE(handle, out, amount);
     }
 

o1heap/o1heap.h

@@ -11,7 +11,7 @@
 // OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 //
-// Copyright (c) 2020 Pavel Kirienko
+// Copyright (c) Pavel Kirienko
 // Authors: Pavel Kirienko <[email protected]>
 //
 // READ THE DOCUMENTATION IN README.md.
@@ -116,6 +116,19 @@ bool o1heapDoInvariantsHold(const O1HeapInstance* const handle);
 /// If the handle pointer is NULL, the behavior is undefined.
 O1HeapDiagnostics o1heapGetDiagnostics(const O1HeapInstance* const handle);
 
+/// Advanced diagnostic hooks; not used by default.
+/// If O1HEAP_TRACE is not defined or is zero, these functions should be left unimplemented.
+/// Iff O1HEAP_TRACE is defined and is nonzero, the library will emit trace events by invoking these functions,
+/// which are to be defined in the application (or linking will fail).
+///
+/// For allocations, note that if the allocated memory pointer is NULL, an allocation failure has occurred.
+/// In this case, the size reported is the number of bytes requested that the allocator could not provide.
+///
+/// When using the pointer provided via o1heapTraceFree(), the pointer memory must not be accessed.
+/// This pointer should only be used for its address.
+extern void o1heapTraceAllocate(O1HeapInstance* const handle, void* const allocated_memory, size_t size);
+extern void o1heapTraceFree(O1HeapInstance* const handle, void* const freed_memory, size_t size);
+
 #ifdef __cplusplus
 }
 #endif