add docs for new -nodefault, -nodefaultdtor and -oldnodefault
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8023 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Marcelo Matus
parent
e5482f9e08
commit
c2073866b3
5 changed files with 182 additions and 43 deletions
|
|
@ -77,22 +77,31 @@ Version 1.3.28 (unreleased).
|
|||
just to disable the destructor when the flag is mainly
|
||||
used to ignore the default constructor.
|
||||
|
||||
It should be noted that this is also the behavior for C,
|
||||
i.e., the destructor is always generated.
|
||||
If needed, you can still disable the destructor, by using
|
||||
the feature form:
|
||||
|
||||
What about adding a -nodefaultdestructor? I am not sure, I
|
||||
don't see a reason to do that as long as I don't a reason
|
||||
to add a flag like -pleasegeneratememoryleaks.
|
||||
|
||||
But don't worry, if needed, we can still generate memory
|
||||
leaks, I mean, disable the destructor, by using
|
||||
|
||||
%ignore Class::~Class();
|
||||
%nodefaultdtor MyVerySpecialClass;
|
||||
|
||||
Yes, is not as automatic as '-nodefault' or
|
||||
'-nodefaultdestructor', but in this case I think that
|
||||
forcing to do this manually and in a 'case by case' approach
|
||||
is desirable.
|
||||
Note: if you really really need it, you can still disable
|
||||
the implicit destructors at the command line using
|
||||
|
||||
swig -nodefaultdtor
|
||||
|
||||
But really, don't do that please.
|
||||
|
||||
Also, you can force the old 'nodefault' behavior by using
|
||||
|
||||
swig -oldnodefault
|
||||
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
If you use -nodefault in your interface, now some new
|
||||
destructors could be generated in the interface. This
|
||||
could solve some memory leaks but also produce some
|
||||
conflicts.
|
||||
|
||||
To restore old behavior, you can use -oldnodefault.
|
||||
|
||||
|
||||
12/08/2005: mmatus
|
||||
|
|
|
|||
|
|
@ -6124,6 +6124,7 @@ The following interface file code should be placed before SWIG parses the above
|
|||
|
||||
// Do not generate the default proxy constructor or destructor
|
||||
%nodefault Butler;
|
||||
%nodefaultdestructor Butler;
|
||||
|
||||
// Add in pure Java code proxy constructor
|
||||
%typemap(javacode) Butler %{
|
||||
|
|
@ -6159,6 +6160,12 @@ Note that the JNI code sets the proxy's <tt>swigCPtr</tt> member variable to poi
|
|||
The <tt>swigCMemOwn</tt> remains unchanged (at false), so that the proxy does not own the memory.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note: prior to 1.3.28, the %nodefault directive disabled the default
|
||||
constructor and destructor at the same time. Now it is required to explicitly use
|
||||
%nodefault and %nodefaultdestructor to achieve the same result.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The second approach offers a more object oriented interface to the Java user.
|
||||
We do this by making the Java proxy class's
|
||||
|
|
|
|||
|
|
@ -2222,13 +2222,13 @@ differently.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
If you don't want SWIG to generate constructors and destructors, you
|
||||
can use the <tt>%nodefault</tt> directive or the <tt>-no_default</tt>
|
||||
command line option. For example:
|
||||
If you don't want SWIG to generate default constructors when processing C++
|
||||
interfaces, you can use the <tt>%nodefault</tt> directive or the
|
||||
<tt>-nodefault</tt> command line option. For example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
swig -no_default example.i
|
||||
swig -nodefault example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -2238,9 +2238,9 @@ or
|
|||
<div class="code"><pre>
|
||||
%module foo
|
||||
...
|
||||
%nodefault; // Don't create default constructors/destructors
|
||||
%nodefault; // Don't create default constructors
|
||||
... declarations ...
|
||||
%makedefault; // Reenable default constructors/destructors
|
||||
%makedefault; // Reenable default constructors
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -2250,16 +2250,38 @@ definitions. For example:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefault Foo; // No default constructor/destructors for Foo
|
||||
%nodefault Foo; // No default constructor for Foo
|
||||
...
|
||||
struct Foo { // No default generated.
|
||||
struct Foo { // No default constructor generated.
|
||||
};
|
||||
|
||||
struct Bar { // Default constructor/destructor generated.
|
||||
struct Bar { // Default constructor generated.
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
||||
<p>
|
||||
Since ignoring the implicit or default destructors most of the times
|
||||
produce memory leaks, SWIG will always try to generate them. If
|
||||
needed, however, you can selectively disable the generation of the
|
||||
default/implicit destructor by using <tt>%nodefaultdestructor </tt>
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefaultdestructor Foo; // No default/implicit destructor for Foo
|
||||
...
|
||||
struct Foo { // No default destructor is generated.
|
||||
};
|
||||
|
||||
struct Bar { // Default destructor generated.
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<b>Compatibility note:</b> Prior to SWIG-1.3.7, SWIG did not generate default constructors
|
||||
or destructors unless you explicitly turned them on using <tt>-make_default</tt>.
|
||||
|
|
@ -2267,6 +2289,17 @@ However, it appears that most users want to have constructor and destructor func
|
|||
has now been enabled as the default behavior.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<b>Compatibility note:</b> Prior to SWIG-1.3.28, the
|
||||
<tt>-nodefault</tt> option and <tt>%nodefault</tt> directive also
|
||||
disable the default or implicit destructor generation. This had the
|
||||
major side effect of generating memory leaks, and is now disabled. If
|
||||
your interface needs the old behavior, use the
|
||||
<tt>-oldnodefault</tt> option.
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<H3><a name="SWIG_adding_member_functions"></a>5.5.6 Adding member functions to C structures</H3>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@
|
|||
<li><a href="#SWIGPlus_nn6">Simple C++ wrapping</a>
|
||||
<ul>
|
||||
<li><a href="#SWIGPlus_nn7">Constructors and destructors</a>
|
||||
<li><a href="#SWIGPlus_nn8">Default constructors</a>
|
||||
<li><a href="#SWIGPlus_nn8">Default constructors and implicit destructors</a>
|
||||
<li><a href="#SWIGPlus_nn9">When constructor wrappers aren't created</a>
|
||||
<li><a href="#SWIGPlus_nn10">Copy constructors</a>
|
||||
<li><a href="#SWIGPlus_nn11">Member functions</a>
|
||||
|
|
@ -270,13 +270,21 @@ void delete_List(List *l) {
|
|||
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="SWIGPlus_nn8"></a>6.5.2 Default constructors</H3>
|
||||
<H3><a name="SWIGPlus_nn8"></a>6.5.2 Default constructors and implicit destructors</H3>
|
||||
|
||||
|
||||
<p>
|
||||
If a C++ class does not define any public constructors or
|
||||
destructors, SWIG will automatically create a default constructor or
|
||||
destructor. However, there are a few rules that define this behavior:
|
||||
If a C++ class does not define a destructor, SWIG will automatically
|
||||
create one following the implicit destructor rule from C++.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If a C++ class does not define any public constructors, SWIG will
|
||||
automatically create a default constructor.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
There are, however, a few rules that alters the previous behavior:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
|
|
@ -291,45 +299,108 @@ inherit from an abstract class, but don't provide definitions for all of the pur
|
|||
default constructor.
|
||||
</li>
|
||||
|
||||
<li>Default constructors and destructors are not created if a class
|
||||
<li>Default constructors and implicit destructors are not created if a class
|
||||
defines constructors or destructors in a <tt>private</tt> or <tt>protected</tt> section.
|
||||
</li>
|
||||
|
||||
<li>Default constructors and destructors are not created if any base
|
||||
class defines a private default constructor or a private destructor.
|
||||
<li>Default constructors and implicit destructors are not created if any base
|
||||
class defines a non-public default constructor or destructor.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
SWIG should never generate a constructor or destructor for a class in which
|
||||
it is illegal to do so. However, if it is necessary to disable the
|
||||
default constructor/destructor creation, the <tt>%nodefault</tt> directive
|
||||
can be used:
|
||||
SWIG should never generate a default constructor for a class in which
|
||||
it is illegal to do so. In some cases, however, it could be necessary
|
||||
or desired to disable the default constructor. Then the
|
||||
<tt>%nodefault</tt> directive can be used:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefault; // Disable creation of constructor/destructor
|
||||
class Foo {
|
||||
%nodefault Foo; // Disable the default constructor for class Foo.
|
||||
class Foo { // No default constructor is generated, unless is declared
|
||||
...
|
||||
};
|
||||
%makedefault;
|
||||
class Bar { // A default constructor is generated, if possible
|
||||
...
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
<p>
|
||||
The directive <tt>%nodefault</tt> can also be applied "globally", as in:
|
||||
</p>
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefault; // Disable creation of default constructors
|
||||
class Foo { // No default constructor is generated, unless is declared
|
||||
...
|
||||
};
|
||||
class Bar { // No default constructor is generated, unless is declared
|
||||
...
|
||||
};
|
||||
%makedefault; // Enable the creation of default constructors again
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
<tt>%nodefault</tt> can also take a class name. For example:
|
||||
Note that the <tt>%nodefault</tt> has no effect if the default
|
||||
constructor is explicitly declared, as in the following case:
|
||||
</p>
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefault; // Disable creation of default constructors
|
||||
class Foo {
|
||||
public:
|
||||
Foo(); // The default constructor is generated, since is declared
|
||||
};
|
||||
%makedefault; // Enable the creation of default constructors again
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
The correspondig <tt>%nodefaultdtor</tt> directive can be used
|
||||
to disable the generation of the default or implicit destructor, if
|
||||
needed. Be aware, however, that this could lead to memory leaks in the
|
||||
target language. Hence, it is recommended to use this directive only
|
||||
in well known cases. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefault Foo; // Disable for class Foo only.
|
||||
%nodefaultdtor Foo; // Disable the implictit/default destructor for class Foo.
|
||||
class Foo { // No destructor is generated, unless is declared
|
||||
...
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
As in the <tt>%nodefault</tt> case, the <tt>%nodefaultdtor</tt>
|
||||
has no effect over classes that explicitly declare a public
|
||||
destructor:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%nodefaultdtor Foo; // Try to disable the implictit/default destructor for class Foo.
|
||||
class Foo {
|
||||
public:
|
||||
~Foo(); // The destructor is generated, since is declared
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
If you still need to prevent the generation of the default constructor
|
||||
or destructor, even when they are declared in the class, you need to
|
||||
use the <tt>%ignore</tt> directive.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<b>Compatibility Note:</b> The generation of default
|
||||
constructors/destructors was made the default behavior in SWIG
|
||||
constructors/implicit destructors was made the default behavior in SWIG
|
||||
1.3.7. This may break certain older modules, but the old behavior can
|
||||
be easily restored using <tt>%nodefault</tt> or the
|
||||
<tt>-nodefault</tt> command line option. Furthermore, in order for
|
||||
|
|
@ -344,6 +415,16 @@ for classes that define a constructor in those sections. Consider restoring
|
|||
those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<b>Compatibility Note:</b> Prior to 1.3.28, the <tt>%nodefault</tt>
|
||||
directive and the <tt>-nodefault</tt> option also disable the
|
||||
generation of the implicit destructors. This produced memory leaks
|
||||
across the target langauges in an indiscriminated way. If your
|
||||
interface needs the old behavior, use the <tt>-oldnodefault</tt>
|
||||
option.
|
||||
</p>
|
||||
|
||||
|
||||
<H3><a name="SWIGPlus_nn9"></a>6.5.3 When constructor wrappers aren't created</H3>
|
||||
|
||||
|
||||
|
|
|
|||
13
Lib/swig.swg
13
Lib/swig.swg
|
|
@ -47,13 +47,22 @@
|
|||
#define %clearimmutable %feature("immutable","")
|
||||
#define %mutable %clearimmutable
|
||||
|
||||
/* Generation of default constructors/destructors */
|
||||
|
||||
/* Generation of default constructors */
|
||||
#define %nodefault %feature("nodefault","1")
|
||||
#define %default %feature("nodefault","0")
|
||||
#define %clearnodefault %feature("nodefault","")
|
||||
#define %makedefault %cleardefault
|
||||
|
||||
/* Disable the generation of implicit/default destructor */
|
||||
#define %nodefaultdtor %feature("nodefaultdtor","1")
|
||||
#define %defaultdtor %feature("nodefaultdtor","0")
|
||||
#define %clearnodefaultdtor %feature("nodefaultdtor","")
|
||||
|
||||
/* Force the old nodefault behavior */
|
||||
#define %oldnodefault %feature("oldnodefault","1")
|
||||
#define %nooldnodefault %feature("oldnodefault","0")
|
||||
#define %clearoldnodefault %feature("oldnodefault","")
|
||||
|
||||
/* the %exception directive */
|
||||
|
||||
#ifdef SWIGCSHARP
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue