Some target languages have support for handling the widely used <tt>boost::shared_ptr</tt> smart pointer.
This smart pointer is also available as <tt>std::tr1::shared_ptr</tt> before it becomes fully standardized as <tt>std::shared_ptr</tt>.
The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_ptr</tt> and <tt>std_shared_ptr.i</tt> provides support for <tt>std::shared_ptr</tt>, but if the following macro is defined as shown, it can be used for <tt>std::tr1::shared_ptr</tt>:
</p>
<divclass="code">
<pre>
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
%include <std_shared_ptr.i>
</pre>
</div>
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr<T></tt>.
The type <tt>T</tt> must be non-primitive.
A simple example demonstrates usage:
</p>
<divclass="code">
<pre>
%module example
%include <boost_shared_ptr.i>
%shared_ptr(IntValue)
%inline %{
#include <boost/shared_ptr.hpp>
struct IntValue {
int value;
IntValue(int v) : value(v) {}
};
static int extractValue(const IntValue &t) {
return t.value;
}
static int extractValueSmart(boost::shared_ptr<IntValue> t) {
return t->value;
}
%}
</pre>
</div>
<p>
Note that the <tt>%shared_ptr(IntValue)</tt> declaration occurs after the inclusion of the <tt>boost_shared_ptr.i</tt>
library which provides the macro and, very importantly, before any usage or declaration of the type, <tt>IntValue</tt>.
The <tt>%shared_ptr</tt> macro provides, a few things for handling this smart pointer, but mostly a number of
typemaps. These typemaps override the default typemaps so that the underlying proxy class is stored and passed around
as a pointer to a <tt>shared_ptr</tt> instead of a plain pointer to the underlying type.
This approach means that any instantiation of the type can be passed to methods taking the type by value, reference, pointer
or as a smart pointer.
The interested reader might want to look at the generated code, however, usage is simple and no different
handling is required from the target language.
For example, a simple use case of the above code from Java would be:
</p>
<divclass="targetlang">
<pre>
IntValue iv = new IntValue(1234);
int val1 = example.extractValue(iv);
int val2 = example.extractValueSmart(iv);
System.out.println(val1 + " " + val2);
</pre>
</div>
<p>
This shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
The normal proxy class including inheritance relationships is generated as usual.
The only real change introduced by the <tt>%shared_ptr</tt> macro is that the proxy class stores a pointer to the shared_ptr instance instead of a raw pointer to the instance.
A proxy class derived from a base which is being wrapped with shared_ptr can and <b>must</b> be wrapped as a shared_ptr too.
In other words all classes in an inheritance hierarchy must all be used with the <tt>%shared_ptr</tt> macro.
For example the following code can be used with the base class shown earlier:
</p>
<divclass="code">
<pre>
%shared_ptr(DerivedIntValue)
%inline %{
struct DerivedIntValue : IntValue {
DerivedIntValue(int value) : IntValue(value) {}
...
};
%}
</pre>
</div>
<p>
Note that if the <tt>%shared_ptr</tt> macro is omitted for any class in the inheritance hierarchy, it will
result in a C++ compiler error.
For example if the above <tt>%shared_ptr(DerivedIntValue)</tt> is omitted, the following is typical of the compiler error that will result:
</p>
<divclass="shell">
<pre>
example_wrap.cxx: In function ‘void Java_exampleJNI_delete_1DerivedIntValue(JNIEnv*, _jclass*, jlong)’:
example_wrap.cxx:3169: error: ‘smartarg1’ was not declared in this scope
</pre>
</div>
<p>
A shared_ptr of the derived class can now be passed to a method where the base is expected in the target language, just as it can in C++:
William S Fulton