2.5 Out of Memory handling

The GSS API does not have a standard error code for the out of memory error condition. Instead of adding a non-standard error code, this library has chosen to adopt a different strategy. The rationale for the strategy chosen is that out of memory handling happens in rare situations, but performing the out of memory error handling after many API function invocations make source code harder to read. That may make it harder to spot more serious problems. The strategy chosen improve code readability and robustness.

For most applications, aborting the application with an error message when the out of memory situation occur is the best that can be wished for. This is how the library behaves by default.

However, we realize that some applications may not want to have the GSS library abort execution in any situation, or that the error message should go somewhere else than to stderr.

To meet this need, the GSS library support a callback function to let the application regain control, and perform its own cleanups, when an out of memory situation has occurred. The application can define a function and set the library variable gss_alloc_fail_function to that function. This could be implemented as follows.

     #include <gss/ext.h>
     ...
     void my_gss_alloc_failer (void)
     {
           syslog (LOG_CRIT, "GSS library out of memory");
           exit (1);
     }
     ...
     int
     main (int argc, char *argv[])
     {
       ...
       gss_alloc_fail_function = my_gss_alloc_failer;
     ...

The GSS library will invoke gss_alloc_fail_function if an out of memory error occurs. Note that after this all previously allocated GSS library variables are in an undefined state, so you must not use any previously allocated GSS variables again. You could discard all previous GSS variable and start from scratch, though. The hook is only intended to allow the application to log the situation in a special way. Of course, care must be taken to not allocate more memory, as that will likely also fail.

As can be seen, the callback is a global variable, and is thus not thread safe. It is assumed that if malloc fail in one thread, it likely do the same for all threads within the application.