doc pntrTempAlloc

Author: wlammen

src/metamath.c

@@ -731,8 +731,8 @@ void command(int argc, char *argv[]);
  * will start main with \p argc set to 2, argv[0] to "read set.mm", argv[1]
  * to "verify proof *" (both without quotes) and argv[2] to NULL.
  * Returning 0 indicates successful completion, anything else some kind of
- failure.
- * For details see \ref https://en.cppreference.com/w/cpp/language/main_function.
+ * failure.
+ * For details see https://en.cppreference.com/w/cpp/language/main_function.
  */
 int main(int argc, char *argv[]) {
 

src/mmdata.c

@@ -2449,7 +2449,7 @@ long g_pntrStartTempAllocStack = 0;   /* Where to start freeing temporary alloca
                                     when pntrLet() is called (normally 0, except in
                                     special nested vstring functions) */
 /*!
- * \var pntrTempAllocStack
+ * \var pntrString *pntrTempAllocStack[]
  * \brief a \ref stack "stack" of \ref temp_pntrString.
  *
  * Holds pointers to temporarily allocated data of type \ref pntrString.  Such
@@ -2458,7 +2458,24 @@ long g_pntrStartTempAllocStack = 0;   /* Where to start freeing temporary alloca
  */
 pntrString *pntrTempAllocStack[M_MAX_ALLOC_STACK];
 
-
+/*!
+ * \fn temp_pntrString *pntrTempAlloc(long size)
+ * \par size > 0
+ * allocates a \ref block capable of holding \p size \ref pntrString entries
+ * and pushes it onto the \ref pntrTempAllocStack.
+ * \par size == 0
+ * pops off all entries from the \ref pntrTempAllocStack and adds them to the
+ * \ref memFreePool.
+ * \param[in] size count of \ref pntrString entries.  This value must include
+ *   a terminal NULL pointer if needed.
+ * \return a pointer to the allocated \ref block, or NULL if deallocation only
+ * \pre
+ *   \p size ==0: all entries in from \ref pntrTempAllocStack from
+ *   \ref g_pntrTempAllocStackStart do not contain relevant data any more.
+ * \post
+ *   - Exits on out-of-memory
+ *   - updates \ref db2
+ */
 temp_pntrString *pntrTempAlloc(long size) {
                                 /* pntrString memory allocation/deallocation */
   /* When "size" is >0, "size" instances of pntrString are allocated. */

src/mmdata.h

@@ -15,7 +15,7 @@
 
 /* debugging flags & variables */
 /*!
- * \var db
+ * \var long db
  * \brief bytes held by vstring instances outside of the stack of temporaries
  *
  * monitors the number of bytes (including the terminal NUL) currently used in
@@ -31,7 +31,7 @@
 /*E*/extern long db;
 /*E*/extern long db0;
 /*!
- * \var db1
+ * \var long db1
  * \brief bytes held by vstring instances inside of the stack of temporaries
  *
  * monitors the number of bytes currently pointed to by \ref vstring pointers
@@ -43,6 +43,11 @@
  * \bug Seems never be displayed.
  */
 /*E*/extern long db1;
+/*!
+ * \var long db2
+ * Bytes held in \ref blocks managed in \ref tempAllocStack
+ * "temporary pointer stacks".
+ */
 /*E*/extern long db2;
 /*!
  * \var db3
@@ -315,27 +320,27 @@ void *poolFixedMalloc(long size /* bytes */);
  * \ref memFreePool.  If this block exists, but has not sufficient size, it is
  * reallocated from the system.  If the pool is empty, a new \ref block of
  * the given size is allocated from the system.  In any case, the header of the
- * \ref block is properly initialized.
+ * \ref block is properly initialized.  Exits program on out of memory
+ * condition.
  * \param[in] size (in bytes) of the block, not including the block header.
  * \return a free and initialized block of memory with at least the requested
- *   user space.
- * \bug uses outOfMemory that can stack up endlessly
+ *   user space.  Exit on out-of-memory
  */
 void *poolMalloc(long size /* bytes */);
 /*!
  * \fn poolFree(void *ptr)
  *
  * Removes \p ptr from the \ref memUsedPool, if it is listed there.  Then tries
  * adding it to the \ref memFreePool.  If this pool is full, it is increased by
- * \ref MEM_POOL_GROW.  If this fails, an error is created, else \p ptr is
+ * \ref MEM_POOL_GROW.  If this fails, the program is exited, else \p ptr is
  * added.
  * \param[in] ptr pointer to a \ref block.
  * \pre
  *   all memory pointed to by \p ptr is considered free.  This holds even if it
  *   it is kept in \ref memUsedPool. 
  * \post
- *   \ref poolTotalFree is updated
- * \bug calls outOfMemory, that can stack up endlessly
+ *   - \ref poolTotalFree is updated
+ *   - Exit on out-of-memory (the \ref memFreePool overflows)
  */
 void poolFree(void *ptr);
 /*!
@@ -363,7 +368,7 @@ void poolFree(void *ptr);
  * \post
  *   - \ref poolTotalFree is the current free space in bytes in both pools.
  *   - A full \ref block is not added to \ref memUsedPool by this function.
- * \bug calls outOfMemory, that can stack up endlessly
+ *   - Exit on out-of-memory (\ref memUsedPool overflows)
  */
 void addToUsedPool(void *ptr);
 /* Purges reset memory pool usage */
@@ -375,7 +380,7 @@ void memFreePoolPurge(flag untilOK);
  *
  * Return the overall statistics about the pools \ref memFreePool
  * "free block array" and the \ref memUsedPool "used block array".  In MEMORY
- * STATUS mode ON, a diagnostic message compares the the contents of
+ * STATUS mode ON, a diagnostic message compares the contents of
  * \ref poolTotalFree to the values found in this statistics.  They should not
  * differ!
  *
@@ -406,7 +411,7 @@ long getFreeSpace(long max);
 /* Fatal memory allocation error */
 /*!
  * \fn outOfMemory(const char *msg)
- * \brief fatal memory allocation error.
+ * \brief exit after fatal memory allocation error.
  *
  * called when memory cannot be allocated, either because memory/address space
  * is physically exhausted, or because administrative structures would overflow.
@@ -664,12 +669,27 @@ long compressedProofSize(const nmbrString *proof, long statemNum);
 /*!
  * \var long g_pntrTempAllocStackTop
  *
- * Index of the current top af the \ref stack "stack" \ref pntrTempAlloc.
+ * Index of the current top of the \ref stack "stack" \ref pntrTempAlloc.
  * New data is pushed from this location on if space available.
  *
  * \invariant always refers the null pointer element behind the valid data.
  */
 extern long g_pntrTempAllocStackTop;   /* Top of stack for pntrTempAlloc function */
+/*!
+ * \var long g_pntrTempAllocStackStart
+ *
+ * Index of the first entry of the \ref stack "stack" \ref pntrTempAllocStack
+ * eligible for deallocation on the next call to \ref pntrTempAlloc.  Entries
+ * below this value are considered not dependent on the value at this index,
+ * but entries above are.  So when this entry gets deallocated, dependent ones
+ * should follow suit.  A function like \ref pntrTempAlloc or \ref pntrLet
+ * manage this automatic deallocation.
+ * \n
+ * Nested functions using the \ref pntrTempAllocStack usually save the current
+ * value and set it to \ref g_pntrTempAllocStackTop, so they can create their
+ * local dependency chain.  On return the saved value is restored.
+ * \invariant always less or equal to \ref g_pntrTempAllocStackTop.
+ */
 extern long g_pntrStartTempAllocStack; /* Where to start freeing temporary
     allocation when pntrLet() is called (normally 0, except for nested
     pntrString functions) */
@@ -698,7 +718,8 @@ temp_pntrString *pntrMakeTempAlloc(pntrString *s);
  * \post
  *   - the \ref block \p target points to is filled with a copy of
  *     \ref pntrString elements \p source points to, padded with a terminal
- *     NULL, or an outOfMemory error is raised.
+ *     NULL.
+ *   - Exit on out-of-memory
  *   - due to a possible reallocation the pointer \p target points to may
  *     change.
  */