Changeset 288 in vbox for trunk/include/iprt

Timestamp:

Jan 25, 2007 5:14:15 AM (18 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

17834

Message:

debugged the heap.

File:

• trunk/include/iprt/heap.h (modified) (7 diffs)

trunk/include/iprt/heap.h

@@ -33 +33 @@
 /** Pointer to a handle to a simple heap. */
 typedef RTHEAPSIMPLE *PRTHEAPSIMPLE;
+
+/** NIL simple heap handle. */
+#define NIL_RTHEAPSIMPLE    ((RTHEAPSIMPLE)0)
 /* <<< types.h */
 
@@ -39 +42 @@
 /**
  * Initializes the heap.
- * 
+ *
  * @returns IPRT status code on success.
  * @param   pHeap       Where to store the heap anchor block on success.
@@ -49 +52 @@
 /**
  * Merge two simple heaps into one.
- * 
+ *
  * The requiremet is of course that they next two each other memory wise.
- * 
+ *
  * @returns IPRT status code on success.
  * @param   pHeap       Where to store the handle to the merged heap on success.
  * @param   Heap1       Handle to the first heap.
  * @param   Heap2       Handle to the second heap.
+ * @remark  This API isn't implemented yet.
  */
 RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap, RTHEAPSIMPLE Heap1, RTHEAPSIMPLE Heap2);
@@ -61 +65 @@
 /**
  * Allocates memory from the specified simple heap.
- * 
+ *
  * @returns Pointer to the allocated memory block on success.
  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
- * 
+ *
  * @param   Heap        The heap to allocate the memory on.
  * @param   cb          The requested heap block size.
@@ -74 +78 @@
 /**
  * Allocates zeroed memory from the specified simple heap.
- * 
+ *
  * @returns Pointer to the allocated memory block on success.
  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
- * 
+ *
  * @param   Heap        The heap to allocate the memory on.
  * @param   cb          The requested heap block size.
@@ -86 +90 @@
 
 /**
+ * Reallocates / Allocates / Frees a heap block.
+ *
+ * @param   Heap        The heap. This is optional and will only be used for strict assertions.
+ * @param   pv          The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAlloc().
+ * @param   cbNew       The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
+ * @param   cbAlignment The requested heap block alignment. Pass 0 for default alignment.
+ *                      Must be a power of 2.
+ * @remark  This API isn't implemented yet.
+ */
+RTDECL(void *) RTHeapSimpleRealloc(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
+
+/**
+ * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
+ *
+ * @param   Heap        The heap. This is optional and will only be used for strict assertions.
+ * @param   pv          The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAllocZ().
+ * @param   cbNew       The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
+ * @param   cbAlignment The requested heap block alignment. Pass 0 for default alignment.
+ *                      Must be a power of 2.
+ * @remark  This API isn't implemented yet.
+ */
+RTDECL(void *) RTHeapSimpleReallocZ(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
+
+/**
  * Frees memory allocated from a simple heap.
- * 
+ *
  * @param   Heap    The heap. This is optional and will only be used for strict assertions.
  * @param   pv      The heap block returned by RTHeapSimple
@@ -93 +121 @@
 RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap, void *pv);
 
-#ifdef DEBUG
 /**
- * Dumps the hypervisor heap to the (default) log.
- * 
+ * Gets the size of the specified heap block.
+ *
+ * @returns The actual size of the heap block.
+ * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An invalid \a pv
+ *          can also cause traps or trigger assertions.
+ * @param   Heap    The heap. This is optional and will only be used for strict assertions.
+ * @param   pv      The heap block returned by RTHeapSimple
+ */
+RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap, void *pv);
+
+/**
+ * Gets the size of the heap.
+ *
+ * This size includes all the internal heap structures. So, even if the heap is
+ * empty the RTHeapSimpleGetFreeSize() will never reach the heap size returned
+ * by this function.
+ *
+ * @returns The heap size.
+ * @returns 0 if heap was safely detected as being bad.
+ * @param   Heap    The heap.
+ */
+RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap);
+
+/**
+ * Returns the sum of all free heap blocks.
+ *
+ * This is the amount of memory you can theoretically allocate
+ * if you do allocations exactly matching the free blocks.
+ *
+ * @returns The size of the free blocks.
+ * @returns 0 if heap was safely detected as being bad.
+ * @param   Heap    The heap.
+ */
+RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap);
+
+/**
+ * Printf like callbaclk function for RTHeapSimpleDump.
+ * @param   pszFormat   IPRT format string.
+ * @param   ...         Format arguments.
+ */
+typedef DECLCALLBACK(void) FNRTHEAPSIMPLEPRINTF(const char *pszFormat, ...);
+/** Pointer to a FNRTHEAPSIMPLEPRINTF function. */
+typedef FNRTHEAPSIMPLEPRINTF *PFNRTHEAPSIMPLEPRINTF;
+
+/**
+ * Dumps the hypervisor heap.
+ *
  * @param   Heap        The heap handle.
+ * @param   pfnPrintf   Printf like function that groks IPRT formatting.
  */
-RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap);
-#endif
-
+RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf);
 
 __END_DECLS
 
-#endif 
+#endif