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

Merge branch 'unique_ptr-inputs'

Browse source 
* unique_ptr-inputs:
  std::unique_ptr std::auto_ptr tidyup
  Add support for std::auto_ptr inputs
  Cosmetic formatting and doc updates in std_unique_ptr.i files
  Add Perl support for std::unique_ptr inputs
  Add Ruby support for std::unique_ptr inputs
  Add Python support for std::unique_ptr inputs
  Add C# support std::unique_ptr inputs
  Java unique_ptr test ownership enhancement to test
  Java unique_ptr enhance test for double release
  SWIGTYPE && input typemaps now assume object has been moved
  Add Java support for std::unique<T> for input parameters.

Closes #692

Conflicts:
	CHANGES.current
This commit is contained in:
William S Fulton 2022-07-19 20:26:18 +01:00
commit 8b654afdef
37 changed files with 1291 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

73
Doc/Manual/Library.html
View file

@ -2055,13 +2055,9 @@ equivalent <tt>%shared_ptr(T)</tt> macro covered in the previous section.
</p>
<p>
Note that the support provided is limited to returning this smart pointer from a function.
Any other use of <tt>std::auto_ptr</tt> is not directly provided yet.
Example usage of a <tt>std::unique_ptr</tt> being returned from a function is shown below.
</p>
<p>
Example usage would be
</p>
<div class="code">
<pre>
%include &lt;std_unique_ptr.i&gt;
@ -2113,12 +2109,67 @@ Note that the implementation is quite different to the <tt>std::shared_ptr</tt>
where the proxy class manages the underlying C++ memory as a pointer to a shared_ptr instead of a plain raw pointer.
</p>
<p>
A possibly less common usage of this smart pointer is as a parameter to a function.
When used like this it indicates that memory usage of the object pointed to by the underlying pointer
is transferred to the function being called.
The code that SWIG generates assumes this happens.
First, it is assumed that a proxy class already owns the underlying C++ object and is used to pass the object to the C++ function being called.
Second, the ownership is transferred from the proxy class to the C++ function being called and
lifetime is then controlled by the function.
Finally, it is assumed the lifetime of the object may not last beyond returning from the C++ function
and hence the proxy class can no longer be used.
</p>
<p>
Consider expanding the example above with a function that takes a <tt>std::unique_ptr</tt> as follows:
</p>
<div class="code">
<pre>
void take(std::unique_ptr<Klass>);
</pre>
</div>
<p>
and use from C#:
</p>
<div class="targetlang">
<pre>
Klass k = Klass.Create(17); // create an instance of Klass any way you like
int value = k.getValue(); // ok
example.take(k); // memory ownership passes from C# layer to C++ layer
int v = k.getValue(); // don't do this - invalid use of k
</pre>
</div>
<p>
Attempts to use <tt>k</tt> after the ownership has been passed into the <tt>take</tt> function
should not be attempted.
The implementation sets the proxy class to an invalid state by setting the class's underlying
C++ pointer to null after the return from the <tt>take</tt> function.
Subsequent use of an invalid proxy class instance is very much dependent on the implementation
in the target language and ranges from a segfault to giving a nice error.
Consider implementing additional checks via the 'check' typemap.
</p>
<p>
Attempts to pass ownership from a proxy class to a <tt>std::unique</tt> parameter more than once will result
in a "Cannot release ownership as memory is not owned" exception. For example, if <tt>example.take(k)</tt> in the example above is called twice.
</p>
<p>
<b>Compatibility note:</b> Support for <tt>std::unique_ptr</tt> was added in SWIG-4.1.0.
</p>
<H3><a name="Library_std_auto_ptr">12.4.6 auto_ptr smart pointer</a></H3>
<p>
While <tt>std::auto_ptr</tt> is deprecated in C++11, some existing code may
still be using it, so SWIG provides limited support for this class by some target languages.
still be using it. SWIG provides support for this class which is nearly identical
to <tt>std::unique_ptr</tt>.
</p>
<p>
@ -2133,13 +2184,9 @@ the previous two sections.
</p>
<p>
Note that the support provided is limited to returning this smart pointer from a function.
Any other use of <tt>std::auto_ptr</tt> is not directly provided.
Example usage of a <tt>std::auto_ptr</tt> being returned from a function is shown below.
</p>
<p>
Example usage would be
</p>
<div class="code">
<pre>
%include &lt;std_auto_ptr.i&gt;
@ -2181,6 +2228,10 @@ The implementation simply calls <tt>std::auto_ptr::release()</tt> to obtain the
That is, it works the same way covered in the previous section for <tt>std::unique_ptr</tt>.
</p>
<p>
Input parameters also work the same way as <tt>std::unique_ptr</tt> covered in the previous section.
</p>
<H2><a name="Library_nn16">12.5 Utility Libraries</a></H2>