Mercurial > hg > octave-lyh > gnulib-hg
changeset 13714:f4bf48c2a955
Manual: improve out-of-memory documentation.
* gnulib.texi: Rewrite “Out of memory handling” section to be
about gnulib, not GSS.
Signed-off-by: Simon Josefsson <simon@josefsson.org>
author | Reuben Thomas <rrt@sc3d.org> |
---|---|
date | Tue, 21 Sep 2010 15:29:45 +0100 |
parents | 9797d4d7c515 |
children | 04126a7f5fd5 |
files | doc/gnulib.texi |
diffstat | 1 files changed, 22 insertions(+), 25 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -715,40 +715,37 @@ @cindex Out of Memory handling @cindex Memory allocation failure -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. Out of memory -handling happens in rare situations, but performing the out of memory -error handling after almost all API function invocations pollute your -source code and might make it harder to spot more serious problems. -The strategy chosen improves code readability and robustness. +The gnulib API does not have a standard error code for the out of memory +error condition. Instead of adding a non-standard error code, gnulib +has chosen to adopt a different strategy. Out of memory handling +happens in rare situations, but performing the out of memory error +handling after almost all API function invocations pollute your source +code and might make it harder to spot more serious problems. The +strategy chosen improves code readability and robustness. @cindex Aborting execution For most applications, aborting the application with an error message when the out of memory situation occurs is the best that can be wished -for. This is how the library behaves by default. - -@vindex xalloc_fail_func -However, we realize that some applications may not want to have the -GSS library abort execution in any situation. The GSS library supports -a hook 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 (having a @code{void} prototype, i.e., no return -value and no parameters) and set the library variable -@code{xalloc_fail_func} to that function. The variable should be +for. This is how the library behaves by default (using +the @samp{xalloc-die} module). + +@vindex xalloc_die +However, we realize that some applications may not want to abort +execution in any situation. Gnulib supports a hook 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 +(having a @code{void} prototype, i.e., no return value and no +parameters) and set the library variable +@code{xalloc_die} to that function. The variable should be declared as follows. @example -extern void (*xalloc_fail_func) (void); +extern void (*xalloc_die) (void); @end example -The GSS library will invoke this function if an out of memory error -occurs. Note that after this the GSS library is in an undefined -state, so you must unload or restart the application to continue call -GSS library functions. 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. +Gnulib will invoke this function if an out of memory error occurs. Note +that the function should not return. Of course, care must be taken to +not allocate more memory, as that will likely also fail. @node Obsolete modules