doc poolMalloc and others

Author: wlammen

src/mmdata.c

@@ -204,12 +204,25 @@ vstring g_qsortKey; /* Used by qsortStringCmp; pointer only, do not deallocate *
  */
 #define MEM_POOL_GROW 1000 /* Amount that a pool grows when it overflows. */
 /*??? Let user set this from menu. */
+/*!
+ * \var long poolAbsoluteMax
+ * The value is a memory amount in bytes.
+ * \n
+ * The \ref suballocator scheme must not hold more memory than is short term
+ * useful.  To the operating system all memory in \ref memFreePool appears as
+ * allocated, although it is not really in use.  To prevent the system from
+ * taking unnecessary action such as saving RAM to disk, a limit to the amount
+ * of free memory managed by the suballocator can be set up.  This limit is
+ * checked in frequent operations, and an automatic purge process is initiated
+ * in \ref memFreePoolPurge should \ref poolTotalFree exceed this value.
+ */
 long poolAbsoluteMax = 1000000; /* Pools will be purged when this is reached */
 /*!
  * \var long poolTotalFree
  * contains the number of free space available in bytes, in both pools
  * \ref memFreePool and \ref memUsedPool, never counting the hidden headers at
- * the beginning of each block, see \ref block.
+ * the beginning of each block, see \ref block.  Exceeding \ref poolAbsoluteMax
+ * may trigger an automatic purge process by \ref memFreePoolPurge.
  */
 long poolTotalFree = 0; /* Total amount of free space allocated in pool */
 /*E*/long i1,j1_,k1; /* 'j1' is a built-in function */
@@ -556,6 +569,21 @@ void addToUsedPool(void *ptr)
 }
 
 /* Free all arrays in the free pool. */
+/*!
+ * \fn void memFreePoolPurge(flag untilOK)
+ * \brief returns memory held in \ref memFreePool
+ * Starting with the last entry in \ref memFreePool, memory held in that pool
+ * is returned to the system until all, or at least a sufficient amount is
+ * freed again (see \p untilOK).
+ * \param[in] untilOK if 1 freeing \ref block "blocks" stops the moment
+ *   \ref poolTotalFree gets within the range of \ref poolAbsoluteMax again.
+ *   Note that it is not guaranteed that the limit \ref poolAbsoluteMax is
+ *   undercut because still too much free memory might be held in the
+ *   \ref memUsedPool.
+ *   \n
+ *   If 0, all \ref memFreePool entries are freed, and the pool itself is
+ *   shrunk back to \ref MEM_POOL_GROW size.
+ */
 void memFreePoolPurge(flag untilOK)
 {
 /*E*/if(db9)getPoolStats(&i1,&j1_,&k1); if(db9)printf("e0: pool %ld stat %ld\n",poolTotalFree,i1+j1_);
@@ -2677,9 +2705,9 @@ void pntrZapLen(pntrString *s, long length) {
  * \ref pntrString.
  *
  * This function determines the length of the source \p t by scanning for a
- * terminating null pointer element.  The destination \p s must have enough
- * space for receiving this amount of pointers, including the terminal null
- * pointer.  Then the source pointers are copied beginning with that at the
+ * terminal null pointer element.  The destination \p s must have enough space
+ * for receiving this amount of pointers, including the terminal null pointer.
+ * Then the source pointers are copied beginning with that at the
  * lowest address to the destination area \p t, including the terminal null
  * pointer.
  *
@@ -2695,8 +2723,8 @@ void pntrZapLen(pntrString *s, long length) {
  *   - \p t is terminated by the first null pointer element.
  *   - the target array \p s must have enough free space to hold the source array
  *     \p t including the terminal null pointer.
- *   - \p s and \p t can overlap if \p t points to a later element than \p s
- *     (move left semantics)
+ *   - \p s and \p t can overlap if \p t points to a later or same element than
+ *     \p s (move left semantics).
  * \invariant
  *   If \p s is contained in a \ref block "block", its administrative header is
  *   NOT updated.

src/mmdata.h

@@ -307,6 +307,20 @@ extern flag g_globalDiscouragement; /* SET DISCOURAGEMENT */
 
 /* Allocation and deallocation in memory pool */
 void *poolFixedMalloc(long size /* bytes */);
+/*!
+ * \fn void *poolMalloc(long size)
+ * \brief allocates and initializes a new \ref block
+ *
+ * allocates a \ref block, first removing and using the last element of the
+ * \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.
+ * \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
+ */
 void *poolMalloc(long size /* bytes */);
 /*!
  * \fn poolFree(void *ptr)
@@ -317,7 +331,8 @@ void *poolMalloc(long size /* bytes */);
  * added.
  * \param[in] ptr pointer to a \ref block.
  * \pre
- *   all memory pointed to by \p ptr is considered free.
+ *   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
@@ -327,8 +342,8 @@ void poolFree(void *ptr);
  * \fn addToUsedPool(void *ptr)
  * \brief announces a block with free capacity for further allocation
  *
- * This function temporarily freezes the usage of a block for an old client, and
- * allows temporary reallocation of the free capacity to a new client.
+ * This function temporarily freezes the usage of a block for the current user,
+ * and allows temporary reallocation of the free capacity to a new client.
  * \n
  * The program maintains pools of memory blocks with free capacity.  In case of
  * demand such a \ref block can temporarily allocate this capacity for new
@@ -390,7 +405,7 @@ long getFreeSpace(long max);
 
 /* Fatal memory allocation error */
 /*!
- * \fn outOfMemory
+ * \fn outOfMemory(const char *msg)
  * \brief fatal memory allocation error.
  *
  * called when memory cannot be allocated, either because memory/address space
@@ -408,7 +423,7 @@ void outOfMemory(const char *msg);
 
 /* Bug check error */
 /*!
- * \fn bug
+ * \fn bug(int bugNum)
  */
 void bug(int bugNum);
 
@@ -672,6 +687,20 @@ temp_pntrString *pntrMakeTempAlloc(pntrString *s);
 /* String assignment - MUST be used to assign vstrings */
 /*!
  * \fn void pntrLet(pntrString **target, const pntrString *source)
+ * \param[in,out] target (not null) the address of a pointer pointing to the
+ *   first byte of a \ref block receiving the copied \p source.
+ * \param[in] source (not null) a pointer to the first \ref pntrString element
+ *   in a \ref block, to be copied from.
+ * \pre
+ *   - source does not contain NULL pointer, but is terminated by one.  This
+ *     NULL pointer is not part of the array, but must be present.
+ *   - the target \ref block does not contain used data.
+ * \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.
+ *   - due to a possible reallocation the pointer \p target points to may
+ *     change.
  */
 void pntrLet(pntrString **target, const pntrString *source);
 
@@ -700,8 +729,10 @@ temp_pntrString *pntrPSpace(long n);
  * \brief Determine the length of a pntrString held in a \ref block "block"
  * dedicated to it.
  *
- * returns the number of **used** pointers in the array pointed to by \p s,
- * derived from administrative data in the surrounding block.
+ * returns the number of **reserved** pointers in the array pointed to by \p s,
+ * derived solely from administrative data in the surrounding \ref block.  NULL
+ * pointer in the array are included, a trailing one is not required to
+ * determine the length.´
  *
  * \attention This is not the capacity of the array.
  * \param[in] s points to a element 0 of a \ref pntrString  embedded in a block

src/mmvstr.h

@@ -335,7 +335,7 @@ void let(vstring *target, const char *source);
  *   The following parameters are pointers to NUL terminated strings as well,
  *   except for the last parameter that must be NULL.  It is allowed to
  *   duplicate parameters.
- * \return the concatenated \ref temp_string terminated by a NUL character.
+ * \return the concatenated \ref temp_vstring terminated by a NUL character.
  * \post the resulting string is pushed onto the \ref tempAllocStack.
  *   \ref db is updated.
  * \bug a stack overflow of \ref tempAllocStack is not handled correctly.
@@ -358,50 +358,50 @@ int linput(FILE *stream, const char *ask, vstring *target);
 /* Emulation of BASIC string functions */
 /* Indices are 1-based */
 /*!
- * \fn temp_vstring seg(const char *sin, long p1, long p2)
+ * \fn temp_vstring seg(const char *sin, long start, long stop)
  * Extracts a substring from a source and pushes it on \ref tempAllocStack.
  * Note: The bounding indices are 1-based and inclusive.
  *
  * \param[in] sin (not null) pointer to the NUL-terminated source text.
- * \param[in] p1 offset of the first byte of the substring, counted in bytes from
+ * \param[in] start offset of the first byte of the substring, counted in bytes from
  *   the first one of \p sin, a 1-based index.  A value less than 1 is
  *   internally corrected to 1, but it must not point beyond the terminating
- *   NUL of \p sin, if \p p1 <= \p p2.
- * \param[in] p2 offset of the last byte of the substring, counted in bytes from
+ *   NUL of \p sin, if \p start <= \p stop.
+ * \param[in] stop offset of the last byte of the substring, counted in bytes from
  *   the first one of \p sin, a 1-based index.  The natural bounds of this
- *   value are \p p1 - 1 and the length of \p sin.  Values outside of this
- *   range are internally corrected to the closer of these limits.  If \p p2 <
- *   \p p1 the empty string is returned.
+ *   value are \p start - 1 and the length of \p sin.  Values outside of this
+ *   range are internally corrected to the closer of these limits.  If \p stop
+ *   < \p start the empty string is returned.
  * \attention the indices are 1-based: seg("hello", 2, 3) == "el"!
  * \return a pointer to new allocated \ref temp_vstring referencing the
  *   requested substring, that is also pushed onto the top of
  *   \ref tempAllocStack
  * \pre
- *   \p p1 <= length(\p sin).
+ *   \p start <= length(\p sin).
  * \post
  *   A pointer to the substring is pushed on \ref tempAllocStack, even if it
  *   empty;
  * \warning not UTF-8 safe.
  * \bug a stack overflow of \ref tempAllocStack is not handled correctly;
  */
-temp_vstring seg(const char *sin, long p1, long p2);
+temp_vstring seg(const char *sin, long start, long stop);
 /*!
- * \fn temp_vstring mid(const char *sin, long p, long l)
+ * \fn temp_vstring mid(const char *sin, long start, long length)
  * Extracts a substring from a source and pushes it on \ref tempAllocStack
  *
  * \param[in] sin (not null) pointer to the NUL-terminated source text.
- * \param[in] p offset of the substring in bytes from the first byte of \p sin,
- *   1-based.  A value less than 1 is internally corrected to 1, but it must
- *   never point beyond the terminating NUL of \p sin.
- * \param[in] l length of substring in bytes.  Negative values are corrected to 0.
- *   If \p p + \p l exceeds the length of \p sin, then only the portion up
- *   to the terminating NUL is taken.
- * \attention the index \p p is 1-based: mid("hello", 2, 1) == "e"!
+ * \param[in] start offset of the substring in bytes from the first byte of
+ *   \p sin, 1-based.  A value less than 1 is internally corrected to 1, but it
+ *   must never point beyond the terminating NUL of \p sin.
+ * \param[in] length length of substring in bytes.  Negative values are
+ *   corrected to 0.  If \p start + \p length exceeds the length of \p sin,
+ *   then only the portion up to the terminating NUL is taken.
+ * \attention the index \p start is 1-based: mid("hello", 2, 1) == "e"!
  * \return a pointer to new allocated \ref temp_vstring referencing the
  *   requested substring, that is also pushed onto the top of
  *   \ref tempAllocStack
  * \pre
- *   \p p <= length(\p sin).  This must hold even if the requested length is
+ *   \p start <= length(\p sin).  This must hold even if the requested length is
  *   0, because its implementation in C requires the validity of the pointer,
  *   even if it is not dereferenced.
  * \post
@@ -410,7 +410,7 @@ temp_vstring seg(const char *sin, long p1, long p2);
  * \warning not UTF-8 safe.
  * \bug a stack overflow of \ref tempAllocStack is not handled correctly;
  */
-temp_vstring mid(const char *sin, long p, long l);
+temp_vstring mid(const char *sin, long start, long length);
 /*!
  * \fn temp_vstring left(const char *sin, long n)
  * \brief Extract leftmost n characters.