diff options
Diffstat (limited to 'Doc/Devel/internals.html')
| -rw-r--r-- | Doc/Devel/internals.html | 28 |
1 files changed, 24 insertions, 4 deletions
diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html index 0fc6623e8..d003d9dea 100644 --- a/Doc/Devel/internals.html +++ b/Doc/Devel/internals.html @@ -519,7 +519,27 @@ hash item: hashval3 [h3] <h3>2.10 Utility functions </h3> </a> -[ TODO ] +<p> +DOH wraps some standard C library functions - these wrapped versions should +always be used in code in the SWIG tool itself (but not in generated code). +When compiling with GCC or clang, the original library function names are +marked as "poisoned" symbols so you should get an error if you accidentally +use one of the unwrapped functions. These functions are: + +<ul> + <li><tt>Calloc(m,n)</tt> : wrapper for <tt>calloc(m,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>. + <li><tt>Malloc(n)</tt> : wrapper for <tt>malloc(n)</tt> which exits on memory failure so never returns <tt>NULL</tt>. + <li><tt>Realloc(p,n)</tt> : wrapper for <tt>realloc(p,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>. + <li><tt>Free(p)</tt> : wrapper for <tt>free(p)</tt> (doesn't currently do anything special, really done for consistency with <tt>Malloc()</tt> etc). + <li><tt>Exit(r)</tt> : wrapper for <tt>exit(r)</tt> which for SWIG removes generated files if <tt>r>0</tt>. +</ul> + +<tt>abort()</tt> is also poisoned - please use <tt>Exit(EXIT_FAILURE)</tt> instead so that generated files are removed. +</p> + +<p> +[ TODO document others ] +</p> <a name="3" href="#i3"> <h2>3. Types and Typemaps</h2> @@ -1194,12 +1214,12 @@ that are used after they have been deleted. This is because the DOH memory alloc grabs a chunk of memory from the C memory allocator and manages the usage internally. Stale DOH object usage can be checked for by defining <tt>DOH_DEBUG_MEMORY_POOLS</tt> in <tt>memory.c</tt>. If an attempt to use an object is made after the reference count is -zero, an assertion is triggered instead of quietly re-using the stale object... +zero, a fatal error is triggered instead of quietly re-using the stale object: </p> <blockquote> <pre> -swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed. +Fatal internal error: Attempt to delete a non-DOH object. </pre> </blockquote> @@ -1209,7 +1229,7 @@ only recommended for diagnosing memory corruption problems. </p> <hr> -Copyright (C) 1999-2010 SWIG Development Team. +Copyright (C) 1999-2022 SWIG Development Team. </body> </html> |