doc/out-of-memory.texi

   1 @node Out of memory handling
   2 @section Out of memory handling
   3
   4 @cindex Out of Memory handling
   5 @cindex Memory allocation failure
   6 The gnulib API does not have a standard error code for the out of memory
   7 error condition.  Instead of adding a non-standard error code, gnulib
   8 has chosen to adopt a different strategy.  Out of memory handling
   9 happens in rare situations, but performing the out of memory error
  10 handling after almost all API function invocations pollute your source
  11 code and might make it harder to spot more serious problems.  The
  12 strategy chosen improves code readability and robustness.
  13
  14 @cindex Aborting execution
  15 For most applications, aborting the application with an error message
  16 when the out of memory situation occurs is the best that can be wished
  17 for.  This is how the library behaves by default (using
  18 the @samp{xalloc-die} module).
  19
  20 @vindex xalloc_die
  21 However, we realize that some applications may not want to abort
  22 execution in any situation.  Gnulib supports a hook to let the
  23 application regain control and perform its own cleanups when an out of
  24 memory situation has occurred.  The application can define a function
  25 (having a @code{void} prototype, i.e., no return value and no
  26 parameters) and set the library variable
  27 @code{xalloc_die} to that function.  The variable should be
  28 declared as follows.
  29
  30 @example
  31 extern void (*xalloc_die) (void);
  32 @end example
  33
  34 Gnulib will invoke this function if an out of memory error occurs.  Note
  35 that the function should not return.  Of course, care must be taken to
  36 not allocate more memory, as that will likely also fail.