doc/xalloc.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 GSS API does not have a standard error code for the out of memory
   7 error condition.  Instead of adding a non-standard error code, this
   8 library has chosen to adopt a different strategy.  Out of memory
   9 handling happens in rare situations, but performing the out of memory
  10 error handling after almost all API function invocations pollute your
  11 source code and might make it harder to spot more serious problems.
  12 The strategy chosen improve 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 occur is the best that can be wished
  17 for.  This is how the library behaves by default.
  18
  19 @vindex xalloc_fail_func
  20 However, we realize that some applications may not want to have the
  21 GSS library abort execution in any situation.  The GSS library support
  22 a hook to let the application regain control and perform its own
  23 cleanups when an out of memory situation has occured.  The application
  24 can define a function (having a @code{void} prototype, i.e., no return
  25 value and no parameters) and set the library variable
  26 @code{xalloc_fail_func} to that function.  The variable should be
  27 declared as follows.
  28
  29 @example
  30 extern void (*xalloc_fail_func) (void);
  31 @end example
  32
  33 The GSS library will invoke this function if an out of memory error
  34 occurs.  Note that after this the GSS library is in an undefined
  35 state, so you must unload or restart the application to continue call
  36 GSS library functions.  The hook is only intended to allow the
  37 application to log the situation in a special way.  Of course, care
  38 must be taken to not allocate more memory, as that will likely also
  39 fail.