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

Add in pre, post and cshin attributes for the csin typemap

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@9678 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2007-04-17 22:45:17 +00:00
commit 0090cac1d0
2 changed files with 340 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

224
Doc/Manual/CSharp.html
View file

@ -28,6 +28,7 @@
<ul>
<li><a href="#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#csharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
</ul>
</ul>
</div>
@ -195,7 +196,7 @@ $jnicall -&gt; $imcall
<li>
<p>
The intermediary classname has <tt>PINVOKE</tt> appended after the module name instead of <tt>JNI</tt>, for example <tt>modulenamePINVOKE</tt>.
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter. The "csin" typemap supports an additional optional attribute called 'cshin'. It should contain the parameter type and name whenever a <a href="Java.html#java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes. Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> for further understanding.
</p>
</li>
@ -326,6 +327,12 @@ they can be added using the 'csvarin' and 'csvarout' typemaps respectively.
</p>
</li>
<li>
<p>
The intermediary classname has <tt>PINVOKE</tt> appended after the module name instead of <tt>JNI</tt>, for example <tt>modulenamePINVOKE</tt>.
</p>
</li>
<li>
<p>
The <tt>%csmethodmodifiers</tt> feature can also be applied to variables as well as methods.
@ -450,6 +457,7 @@ typedef enum {
SWIG_CSharpArithmeticException,
SWIG_CSharpDivideByZeroException,
SWIG_CSharpIndexOutOfRangeException,
SWIG_CSharpInvalidCastException,
SWIG_CSharpInvalidOperationException,
SWIG_CSharpIOException,
SWIG_CSharpNullReferenceException,
@ -1241,41 +1249,8 @@ void SwigDirector_Base::BaseBoolMethod(Base const &amp;b, bool flag) {
<p>
There are a few gotchas with directors.
The first is that the base class virtual method should not be called directly otherwise a stack overflow will occur due to recursive calls.
This might be fixed in a future version of SWIG, but is likely to slow down virtual methods calls.
For example, given <tt>Base</tt> as a director enabled class:
</p>
<div class="code">
<pre>
class Base {
public:
virtual ~Base();
virtual unsigned int UIntMethod(unsigned int x);
};
</pre>
</div>
<p>
Do not directly call the base method from a C# derived class:
</p>
<div class="code">
<pre>
public class CSharpDerived : Base
{
public override uint UIntMethod(uint x)
{
return base.UIntMethod(x);
}
}
</pre>
</div>
<p>
Secondly, if default parameters are used, it is recommended to follow a pattern of always calling a single method in any C# derived class.
There is a subtle gotcha with directors.
If default parameters are used, it is recommended to follow a pattern of always calling a single method in any C# derived class.
An example will clarify this and the reasoning behind the recommendation. Consider the following C++ class wrapped as a director class:
</p>
@ -1569,6 +1544,183 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
</div>
<H3><a name="csharp_date_marshalling"></a>17.5.3 Date marshalling using the csin typemap and associated attributes</H3>
<p>
The <a href="Java.html#nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
This example demonstrates how a C++ date class, say <tt>CDate</tt>, can be mapped onto the standard .NET date class,
<tt>System.DateTime</tt> by using the 'pre', 'post' and 'pgcppname' attributes of the "csin" typemap (the C# equivalent to the "javain" typemap).
The example is an equivalent to the <a href="Java.html#java_date_marshalling">Java Date marshalling example</a>.
The idea is that the <tt>System.DateTime</tt> is used wherever the C++ API uses a <tt>CDate</tt>.
Let's assume the code being wrapped is as follows:
</p>
<div class="code">
<pre>
class CDate {
public:
CDate(int year, int month, int day);
int getYear();
int getMonth();
int getDay();
...
};
struct Action {
static int doSomething(const CDate &amp;dateIn, CDate &amp;dateOut);
Action(const CDate &amp;date, CDate &amp;dateOut);
};
</pre>
</div>
<p>
Note that <tt>dateIn</tt> is const and therefore read only and <tt>dateOut</tt> is a non-const output type.
</p>
<p>
First let's look at the code that is generated by default, where the C# proxy class <tt>CDate</tt> is used in the proxy interface:
</p>
<div class="code">
<pre>
public class Action : IDisposable {
...
public Action(CDate dateIn, CDate dateOut)
: this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
if (examplePINVOKE.SWIGPendingException.Pending)
throw examplePINVOKE.SWIGPendingException.Retrieve();
}
public int doSomething(CDate dateIn, CDate dateOut) {
int ret = examplePINVOKE.Action_doSomething(swigCPtr,
CDate.getCPtr(dateIn),
CDate.getCPtr(dateOut));
if (examplePINVOKE.SWIGPendingException.Pending)
throw examplePINVOKE.SWIGPendingException.Retrieve();
return ret;
}
}
</pre>
</div>
<p>
The <tt>CDate &amp;</tt> and <tt>const CDate &amp;</tt> C# code is generated from the following two default typemaps:
</p>
<div class="code">
<pre>
%typemap(jstype) SWIGTYPE &amp; "$csclassname"
%typemap(csin) SWIGTYPE &amp; "$csclassname.getCPtr($csinput)"
</pre>
</div>
<p>
where '$csclassname' is translated into the proxy class name, <tt>CDate</tt> and '$csinput' is translated into the name of the parameter, eg <tt>dateIn</tt>.
From C#, the intention is then to call into a modifed API with something like:
</p>
<div class="code">
<pre>
System.DateTime dateIn = new System.DateTime(2011, 4, 13);
System.DateTime dateOut = new System.DateTime();
// Note in calls below, dateIn remains unchanged and dateOut
// is set to a new value by the C++ call
Action action = new Action(dateIn, ref dateOut);
dateIn = new System.DateTime(2012, 7, 14);
</pre>
</div>
<p>
To achieve this mapping, we need to alter the default code generation slightly so that at the C# layer,
a <tt>System.DateTime</tt> is converted into a <tt>CDate</tt>.
The intermediary layer will still take a pointer to the underlying <tt>CDate</tt> class.
The typemaps to achieve this are shown below.
</p>
<div class="code">
<pre>
%typemap(cstype) const CDate&amp; "System.DateTime"
%typemap(csin,
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);")
const CDate &amp;
"$csclassname.getCPtr(temp$csinput)"
%typemap(cstype) CDate&amp; "ref System.DateTime"
%typemap(csin,
pre=" CDate temp$csinput = new CDate();",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
cshin="ref $csinput") CDate &amp;
"$csclassname.getCPtr(temp$csinput)"
</pre>
</div>
<p>
The resulting generated proxy code in the <tt>Action</tt> class follows:
</p>
<div class="code">
<pre>
public class Action : IDisposable {
...
public int doSomething(System.DateTime dateIn, ref System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
CDate tempdateOut = new CDate();
try {
int ret = examplePINVOKE.Action_doSomething(swigCPtr,
CDate.getCPtr(tempdateIn),
CDate.getCPtr(tempdateOut));
if (examplePINVOKE.SWIGPendingException.Pending)
throw examplePINVOKE.SWIGPendingException.Retrieve();
return ret;
} finally {
dateOut = new System.DateTime(tempdateOut.getYear(),
tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
}
}
static private IntPtr SwigConstructAction(System.DateTime dateIn, ref System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
CDate tempdateOut = new CDate();
try {
return examplePINVOKE.new_Action(CDate.getCPtr(tempdateIn), CDate.getCPtr(tempdateOut));
} finally {
dateOut = new System.DateTime(tempdateOut.getYear(),
tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
}
}
public Action(System.DateTime dateIn, ref System.DateTime dateOut)
: this(Action.SwigConstructAction(dateIn, ref dateOut), true) {
if (examplePINVOKE.SWIGPendingException.Pending)
throw examplePINVOKE.SWIGPendingException.Retrieve();
}
}
</pre>
</div>
<p>
A few things to note:
</p>
<ul>
<li> The "cstype" typemap has changed the parameter type to <tt>System.DateTime</tt> instead of the default generated <tt>CDate</tt> proxy.
<li> The non-const <tt>CDate &amp;</tt> type is marshalled as a reference parameter in C# as the date cannot be explicitly set once the object has been created, so a new object is created instead.
<li> The code in the 'pre' attribute appears before the intermediary call (<tt>examplePINVOKE.new_Action</tt> / <tt>examplePINVOKE.Action_doSomething</tt>).
<li> The code in the 'post' attribute appears after the intermediary call.
<li> A try .. finally block is generated with the intermediary call in the try block and 'post' code in the finally block.
The alternative of just using a temporary variable for the return value from the intermediary call and the 'post' code being inserted before the
return statement is not possible given that the intermediary call and method return comes from a single source (the "csout" typemap).
<li> The temporary variables in the "csin" typemaps are called <tt>temp$csin</tt>, where "$csin" is replaced with the parameter name.
"$csin" is used to mangle the variable name so that more than one <tt>CDate &amp;</tt> type can be used as a parameter in a method, otherwise two or
more local variables with the same name would be generated.
<li> The use of the "csin" typemap causes a constructor helper function (<tt>SwigConstructAction</tt>) to be generated.
This allows C# code to be called before the intermediary call made in the constructor initialization list.
<li> The 'cshin' attribute is required for the <tt>SwigConstructAction</tt> constructor helper function so that the 2nd parameter is declared as <tt>ref dateOut</tt> instead of just <tt>dateOut</tt>.
</ul>
</body>
</html>