jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add/update docs for Malloc(), Exit(), etc

Browse source 
See #2223
This commit is contained in:
Olly Betts 2022-03-07 14:19:34 +13:00
commit 46bdb1bb29
2 changed files with 26 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Devel/cmdopt.html
View file

@ -60,7 +60,7 @@ and issues an error message if any unconsumed arguments are found.
<b><tt>void Swig_check_options()</tt></b>
<blockquote>
Checks all command line options to see if they have all been processed. If not, an error message is generated and
execution terminates with a call to <tt>exit()</tt>. This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
SWIG exits. This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
</blockquote>
<h2>Utility Function</h2>
@ -68,7 +68,7 @@ execution terminates with a call to <tt>exit()</tt>. This function is currentl
<b><tt>void Swig_arg_error())</tt></b>
<blockquote>
A generic function that issues an error message about being unable to parse command line options. SWIG is terminated by a call to <tt>exit()</tt>.
A generic function that issues an error message about being unable to parse command line options and SWIG exits.
</body>
</html>

28
Doc/Devel/internals.html
View file

@ -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&gt;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>