/tags/rel-1.3.35/Doc/Manual/Octave.html
HTML | 836 lines | 699 code | 135 blank | 2 comment | 0 complexity | 10719596199e0702b15018fd284e68a6 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<title>SWIG and Octave</title>
5<link rel="stylesheet" type="text/css" href="style.css">
6</head>
7
8
9<body bgcolor="#ffffff">
10
11<H1><a name="Octave"></a>26 SWIG and Octave</H1>
12<!-- INDEX -->
13<div class="sectiontoc">
14<ul>
15<li><a href="#Octave_nn2">Preliminaries</a>
16<li><a href="#Octave_nn3">Running SWIG</a>
17<ul>
18<li><a href="#Octave_nn5">Compiling a dynamic module</a>
19<li><a href="#Octave_nn6">Using your module</a>
20</ul>
21<li><a href="#Octave_nn7">A tour of basic C/C++ wrapping</a>
22<ul>
23<li><a href="#Octave_nn8">Modules</a>
24<li><a href="#Octave_nn9">Functions</a>
25<li><a href="#Octave_nn10">Global variables</a>
26<li><a href="#Octave_nn11">Constants and enums</a>
27<li><a href="#Octave_nn12">Pointers</a>
28<li><a href="#Octave_nn13">Structures and C++ classes</a>
29<li><a href="#Octave_nn15">C++ inheritance</a>
30<li><a href="#Octave_nn17">C++ overloaded functions</a>
31<li><a href="#Octave_nn18">C++ operators</a>
32<li><a href="#Octave_nn19">Class extension with %extend</a>
33<li><a href="#Octave_nn20">C++ templates</a>
34<li><a href="#Octave_nn21">C++ Smart Pointers</a>
35<li><a href="#Octave_nn22">Directors (calling Octave from C++ code)</a>
36<li><a href="#Octave_nn23">Threads</a>
37<li><a href="#Octave_nn24">Memory management</a>
38<li><a href="#Octave_nn25">STL support</a>
39<li><a href="#Octave_nn26">Matrix typemaps</a>
40</ul>
41</ul>
42</div>
43<!-- INDEX -->
44
45
46
47<p>
48 Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
49More information can be found at <a href="http://www.octave.org">www.octave.org</a>.
50</p>
51
52<p>
53 This chapter is intended to give an introduction to using the module. You should also read the SWIG documentation that is not specific to Octave.
54Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
55</p>
56
57<H2><a name="Octave_nn2"></a>26.1 Preliminaries</H2>
58
59
60<p>
61The current SWIG implemention is based on Octave 2.9.12. Support for other versions (in particular the recent 3.0) has not been tested, nor has support for any OS other than Linux.
62</p>
63
64<H2><a name="Octave_nn3"></a>26.2 Running SWIG</H2>
65
66
67<p>
68Let's start with a very simple SWIG interface file:
69</p>
70
71<div class="code"><pre>%module example
72%{
73#include "example.h"
74%}
75int gcd(int x, int y);
76extern double Foo; </pre></div>
77
78<p>
79To build an Octave module, run SWIG using the <tt>-octave</tt> option. The <tt>-c++</tt> option is required (for now) as Octave itself is written in C++ and thus the wrapper code must also be.
80</p>
81
82<div class="shell"><pre>$ swig -octave -c++ example.i </pre></div>
83
84<p>
85This creates a C/C++ source file <tt>example_wrap.cxx</tt>. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
86</p>
87
88<p>
89The swig command line has a number of options you can use, like to redirect it's output. Use <tt>swig --help</tt> to learn about these.
90</p>
91
92<H3><a name="Octave_nn5"></a>26.2.1 Compiling a dynamic module</H3>
93
94
95<p>
96Octave modules are DLLs/shared objects having the ".oct" suffix.
97Building an oct file is usually done with the mkoctfile command (either within Octave itself, or from the shell). For example,
98</p>
99
100<div class="shell"><pre>
101$ swig -octave -c++ example.i -o example_wrap.cxx
102$ mkoctfile example_wrap.cxx example.c
103</pre></div>
104
105<p>
106 where example.c is the file containing the gcd() implementation.
107</p>
108
109<p>
110 mkoctfile can also be used to extract the build parameters required to invoke the compiler and linker yourself. See the Octave manual and mkoctfile man page.
111</p>
112
113<p>
114 mkoctfile will produce example.oct, which contains the compiled extension module. Loading it into Octave is then a matter of invoking
115</p>
116
117 <div class="targetlang"><pre>octave:1> example</pre></div>
118
119<H3><a name="Octave_nn6"></a>26.2.2 Using your module</H3>
120
121
122<p>
123Assuming all goes well, you will be able to do this:
124 <br>
125</p>
126
127 <div class="targetlang"><pre>$ octave -q
128octave:1> example
129octave:2> example.gcd(4,6)
130ans = 2
131octave:3> example.cvar.Foo
132ans = 3
133octave:4> example.cvar.Foo=4;
134octave:5> example.cvar.Foo
135ans = 4 </pre></div>
136
137<H2><a name="Octave_nn7"></a>26.3 A tour of basic C/C++ wrapping</H2>
138
139
140<H3><a name="Octave_nn8"></a>26.3.1 Modules</H3>
141
142
143<p>
144The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
145</p>
146
147<p>
148When Octave is asked to invoke <tt>example</tt>, it will try to find the .m or .oct file that defines the function "example". It will thusly find example.oct, that upon loading will register all of the module's symbols.
149</p>
150
151<p>
152Giving this function a parameter "global" will cause it to load all symbols into the global namespace in addition to the <tt>example</tt> namespace. For example:
153</p>
154
155 <div class="targetlang"><pre>$ octave -q
156octave:1> example("global")
157octave:2> gcd(4,6)
158ans = 2
159octave:3> cvar.Foo
160ans = 3
161octave:4> cvar.Foo=4;
162octave:5> cvar.Foo
163ans = 4
164</pre></div>
165<p>
166 It is also possible to rename the module namespace with an assignment, as in: <br>
167 <div class="targetlang"><pre>octave:1> example;
168octave:2> c=example;
169octave:3> c.gcd(10,4)
170ans = 2 </pre></div>
171
172<p>
173All global variables are put into the cvar namespace object. This is accessible either as <tt>my_module.cvar</tt>, or just <tt>cvar</tt> (if the module is imported into the global namespace).
174</p>
175<p>
176One can also rename it by simple assignment, e.g.,
177</p>
178<div class="targetlang"><pre>
179octave:1> some_vars = cvar;
180</pre></div>
181
182<H3><a name="Octave_nn9"></a>26.3.2 Functions</H3>
183
184
185<p>
186Global functions are wrapped as new Octave built-in functions. For example,
187</p>
188
189 <div class="code"><pre>%module example
190int fact(int n); </pre></div>
191
192<p>
193 creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
194</p>
195
196 <div class="targetlang"><pre>octave:1> example.fact(4)
19724 </pre></div>
198
199<H3><a name="Octave_nn10"></a>26.3.3 Global variables</H3>
200
201
202<p>
203 Global variables are a little special in Octave. Given a global variable:
204</p>
205
206 <div class="code"><pre>%module example
207extern double Foo;
208 </pre></div>
209
210<p>
211 To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
212</p>
213
214 <div class="targetlang"><pre>octave:1> example;
215octave:2> c=example.cvar.Foo
216c = 3
217octave:3> example.cvar.Foo=4;
218octave:4> c
219c = 3
220octave:5> example.cvar.Foo
221ans = 4</pre></div>
222
223<p>
224If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable:
225</p>
226
227 <div class="code"><pre>%module example
228%immutable;
229extern double Foo;
230%mutable;
231</pre></div>
232
233<p>
234 SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
235</p>
236
237 <div class="targetlang"><pre>octave:1> example
238octave:2> example.Foo=4
239error: attempt to set immutable member variable
240error: assignment failed, or no method for `swig_type = scalar'
241error: evaluating assignment expression near line 2, column 12 </pre></div>
242
243<p>
244 It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
245</p>
246
247 <div class="targetlang"><pre>octave:1> example;
248octave:2> example.PI=3.142;
249octave:3> example.PI
250ans = 3.1420 </pre></div>
251
252<H3><a name="Octave_nn11"></a>26.3.4 Constants and enums</H3>
253
254
255<p>
256 Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
257</p>
258
259 <div class="code"><pre>%module example
260%constant int ICONST=42;
261#define SCONST "Hello World"
262enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
263</pre></div>
264
265<p>
266 This is 'effectively' converted into the following Octave code:
267</p>
268
269 <div class="targetlang"><pre>example.ICONST=42
270example.SCONST="Hello World"
271example.SUNDAY=0
272.... </pre></div>
273
274<H3><a name="Octave_nn12"></a>26.3.5 Pointers</H3>
275
276
277<p>
278 C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
279 C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
280</p>
281
282<div class="code"><pre>%module example
283FILE *fopen(const char *filename, const char *mode);
284int fputs(const char *, FILE *);
285int fclose(FILE *);
286</pre></div>
287
288<p>
289When wrapped, you will be able to use the functions in a natural way from Octave. For example:
290</p>
291
292<div class="targetlang"><pre>
293octave:1> example;
294octave:2> f=example.fopen("w","junk");
295octave:3> example.fputs("Hello world",f);
296octave:4> example.fclose(f);
297</pre></div>
298
299<p>
300 Simply printing the value of a wrapped C++ type will print it's typename. E.g.,
301</p>
302
303 <div class="targetlang"><pre>octave:1> example;
304octave:2> f=example.fopen("junk","w");
305octave:3> f
306f =
307
308{
309 _p_FILE, ptr = 0x9b0cd00
310} </pre></div>
311
312<p>
313 As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below).
314</p>
315
316 <div class="targetlang"><pre>octave:1> example;
317octave:2> f=example.fopen("not there","r");
318error: value on right hand side of assignment is undefined
319error: evaluating assignment expression near line 2, column 2 </pre></div>
320
321<H3><a name="Octave_nn13"></a>26.3.6 Structures and C++ classes</H3>
322
323
324<p>
325 SWIG wraps C structures and C++ classes by using a special Octave type called a <tt>swig_ref</tt>. A <tt>swig_ref</tt> contains a reference to one or more instances of C/C++ objects, or just the type information for an object.
326For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that has the name of the type. When invoked as a function, it creates a new object of its type and returns a <tt>swig_ref</tt> that points to that instance. This provides a very natural interface. For example,
327</p>
328
329 <div class="code"><pre>struct Point{
330 int x,y;
331};
332</pre></div>
333
334<p>
335 is used as follows:
336</p>
337
338 <div class="targetlang">
339 <pre>octave:1> example;
340octave:2> p=example.Point();
341octave:3> p.x=3;
342octave:4> p.y=5;
343octave:5> p.x, p.y
344ans = 3
345ans = 5
346</pre></div>
347<p>
348In C++, invoking the type object in this way calls the object's constructor.
349<tt>swig_ref</tt> objects can also be acquired by having a wrapped function return a pointer, reference, or value of a non-primitive type.
350</p>
351<p>
352The swig_ref type handles indexing operations such that usage maps closely to what you would have in C/C++.
353Structure members are accessed as in the above example, by calling set and get methods for C++ variables.
354
355Methods also work as expected. For example, code wrapped in the following way
356</p>
357
358 <div class="code"><pre>class Point{
359public:
360 int x,y;
361 Point(int _x,int _y) : x(_x),y(_y) {}
362 double distance(const Point& rhs) {
363 return sqrt(pow(x-rhs.x,2)+pow(y-rhs.y,2));
364 }
365 void set(int _x,int _y) {
366 x=_x; y=_y;
367 }
368};
369</pre></div>
370<p>
371can be used from Octave like this
372</p>
373 <div class="targetlang">
374 <pre>octave:1> example;
375octave:2> p1=example.Point(3,5);
376octave:3> p2=example.Point(1,2);
377octave:4> p1.distance(p2)
378ans = 3.6056
379</pre></div>
380<p>
381By using the <tt>swig_this()</tt> and <tt>swig_type()</tt> functions, one can discover the pointers to and types of the underlying C/C++ object.
382</p>
383
384 <div class="targetlang">
385 <pre>
386octave:5> swig_this(p1)
387ans = 162504808
388octave:6> swig_type(p1)
389ans = Point
390</pre></div>
391<p>
392Note that <tt>swig_ref</tt> is a reference-counted pointer to a C/C++ object/type, and as such has pass-by-reference semantics. For example if one has a allocated a single object but has two <tt>swig_ref</tt>'s pointing to it, modifying the object through either of them will change the single allocated object.
393This differs from the usual pass-by-value (copy-on-write) semantics that Octave maintains for built-in types. For example, in the following snippet, modifying <tt>b</tt> does not modify <tt>a</tt>,
394</p>
395
396 <div class="targetlang">
397 <pre>
398octave:7> a=struct('x',4)
399a =
400{
401 x = 4
402}
403
404octave:8> b=a
405b =
406{
407 x = 4
408}
409
410octave:9> b.y=4
411b =
412{
413 x = 4
414 y = 4
415}
416
417octave:10> a
418a =
419{
420 x = 4
421}
422</pre></div>
423<p>
424However, when dealing with wrapped objects, one gets the behavior
425</p>
426
427 <div class="targetlang">
428 <pre>
429octave:2> a=Point(3,5)
430a =
431
432{
433 Point, ptr = 0x9afbbb0
434}
435
436octave:3> b=a
437b =
438
439{
440 Point, ptr = 0x9afbbb0
441}
442
443octave:4> b.set(2,1);
444octave:5> b.x, b.y
445ans = 2
446ans = 1
447octave:6> a.x, a.y
448ans = 2
449ans = 1
450</pre></div>
451
452<p>
453Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
454</p>
455
456<H3><a name="Octave_nn15"></a>26.3.7 C++ inheritance</H3>
457
458
459<p>
460Single and multiple inheritance are fully supported. The <tt>swig_ref</tt> type carries type information along with any C++ object pointer it holds.
461This information contains the full class hierarchy. When an indexing operation (such as a method invocation) occurs,
462the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
463</p>
464
465<H3><a name="Octave_nn17"></a>26.3.8 C++ overloaded functions</H3>
466
467
468<p>
469Overloaded functions are supported, and handled as in other modules. That is,
470each overload is wrapped separately (under internal names), and a dispatch function is also emitted under the external/visible name.
471The dispatch function selects which overload to call (if any) based on the passed arguments.
472<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
473</p>
474
475<H3><a name="Octave_nn18"></a>26.3.9 C++ operators</H3>
476
477
478<p>
479C++ operator overloading is supported, in a way similar to other modules.
480The <tt>swig_ref</tt> type supports all unary and binary operators between itself and all other types that exist in the system at module load time. When an operator is used (where one of the operands is a <tt>swig_ref</tt>), the runtime routes the call to either a member function of the given object, or to a global function whose named is derived from the types of the operands (either both or just the lhs or rhs).
481</p>
482<p>
483For example, if <tt>a</tt> and <tt>b</tt> are SWIG variables in Octave, <tt>a+b</tt> becomes <tt>a.__add(b)</tt>. The wrapper is then free to implement __add to do whatever it wants. A wrapper may define the <tt>__add</tt> function manually, %rename some other function to it, or %rename a C++ operator to it.
484</p>
485<p>
486By default the C++ operators are renamed to their corresponding Octave operators. So without doing any work, the following interface
487</p>
488<div class="code"><pre>
489%inline {
490struct A {
491 int value;
492 A(int _value) : value(_value) {}
493 A operator+ (const A& x) {
494 return A(value+x.value);
495 }
496};
497}
498</pre></div>
499<p>
500is usable from Octave like this:
501</p>
502<div class="targetlang"><pre>
503a=A(2), b=A(3), c=a+b
504assert(c.value==5);
505</pre></div>
506<p>
507Octave operators are mapped in the following way:
508</p>
509<div class="code"><pre>
510__brace a{args}
511__brace_asgn a{args} = rhs
512__paren a(args)
513__paren_asgn a(args) = rhs
514__str generates string rep
515__not !a
516__uplus +a
517__uminus -a
518__transpose a.'
519__hermitian a'
520__incr a++
521__decr a--
522__add a + b
523__sub a - b
524__mul a * b
525__div a / b
526__pow a ^ b
527__ldiv a \ b
528__lshift a << b
529__rshift a >> b
530__lt a < b
531__le a <= b
532__eq a == b
533__ge a >= b
534__gt a > b
535__ne a != b
536__el_mul a .* b
537__el_div a ./ b
538__el_pow a .^ b
539__el_ldiv a .\ b
540__el_and a & b
541__el_or a | b
542</pre></div>
543<p>
544On the C++ side, the default mappings are as follows:
545</p>
546<div class="code"><pre>
547%rename(__add) *::operator+;
548%rename(__add) *::operator+();
549%rename(__add) *::operator+() const;
550%rename(__sub) *::operator-;
551%rename(__uminus) *::operator-();
552%rename(__uminus) *::operator-() const;
553%rename(__mul) *::operator*;
554%rename(__div) *::operator/;
555%rename(__mod) *::operator%;
556%rename(__lshift) *::operator<<;
557%rename(__rshift) *::operator>>;
558%rename(__el_and) *::operator&&;
559%rename(__el_or) *::operator||;
560%rename(__xor) *::operator^;
561%rename(__invert) *::operator~;
562%rename(__lt) *::operator<;
563%rename(__le) *::operator<=;
564%rename(__gt) *::operator>;
565%rename(__ge) *::operator>=;
566%rename(__eq) *::operator==;
567%rename(__ne) *::operator!=;
568%rename(__not) *::operator!;
569%rename(__incr) *::operator++;
570%rename(__decr) *::operator--;
571%rename(__paren) *::operator();
572%rename(__brace) *::operator[];
573</pre></div>
574
575<H3><a name="Octave_nn19"></a>26.3.10 Class extension with %extend</H3>
576
577
578<p>
579The %extend directive works the same as in other modules.
580</p>
581<p>
582You can use it to define special behavior, like for example defining Octave operators not mapped to C++ operators, or defining certain Octave mechanisms such as how an object prints. For example, the <tt>octave_value::{is_string,string_value,print}</tt> functions are routed to a special method <tt>__str</tt> that can be defined inside an %extend.
583</p>
584<div class="code"><pre>
585%extend A {
586string __str() {
587 stringstream sout;
588 sout<<$self->value;
589 return sout.str();
590}
591}
592</pre></div>
593<p>
594Then in Octave one gets,
595</p>
596<div class="targetlang"><pre>
597octave:1> a=A(4);
598octave:2> a
599a = 4
600octave:3> printf("%s\n",a);
6014
602octave:4> a.__str()
6034
604</pre></div>
605<H3><a name="Octave_nn20"></a>26.3.11 C++ templates</H3>
606
607
608<p>
609C++ class and function templates are fully supported as in other modules, in that the %template directive may used to create explicit instantiations of templated types.
610For example, function templates can be instantiated as follows:
611</p>
612
613<div class="code"><pre>%module example
614%inline {
615 template<class __scalar>
616 __scalar mul(__scalar a,__scalar b) {
617 return a*b;
618 }
619}
620%include <std_complex.i>
621%template(mul) mul<std::complex<double> >
622%template(mul) mul<double>
623</pre></div>
624<p>
625and then used from Octave
626</p>
627
628<div class="targetlang"><pre>
629octave:1> mul(4,3)
630ans = 12
631octave:2> mul(4.2,3.6)
632ans = 15.120
633octave:3> mul(3+4i,10+2i)
634ans = 22 + 46i
635</pre></div>
636
637<p>
638Similarly, class templates can be instantiated as in the following example,
639</p>
640
641<div class="code"><pre>%module example
642%include <std_complex.i>
643%include <std_string.i>
644%inline {
645 #include <sstream>
646 template<class __scalar> class sum {
647 __scalar s;
648 public:
649 sum(__scalar _s=0) : s(_s) {}
650 sum& add(__scalar _s) {
651 s+=_s;
652 return *this;
653 }
654 std::string __str() const {
655 std::stringstream sout;
656 sout<<s;
657 return sout.str();
658 }
659 };
660}
661%template(sum_complex) sum<std::complex<double> >;
662%template(sum_double) sum<double>;
663</pre></div>
664
665<p>
666and then used from Octave
667</p>
668
669<div class="targetlang"><pre>
670octave:2> a=sum_complex(2+3i);
671octave:3> a.add(2)
672ans =
673
674(4,3)
675octave:4> a.add(3+i)
676ans =
677
678(7,4)
679</pre></div>
680
681
682<H3><a name="Octave_nn21"></a>26.3.12 C++ Smart Pointers</H3>
683
684
685<p>
686C++ smart pointers are fully supported as in other modules.
687</p>
688
689<H3><a name="Octave_nn22"></a>26.3.13 Directors (calling Octave from C++ code)</H3>
690
691
692<p>
693There is full support for SWIG Directors, which permits Octave code to subclass C++ classes, and implement their virtual methods.
694</p>
695<p>
696Octave has no direct support for object oriented programming, however the <tt>swig_ref</tt> type provides some of this support. You can manufacture a <tt>swig_ref</tt> using the <tt>subclass</tt> function (provided by the SWIG/Octave runtime).
697</p>
698<p>
699For example,
700</p>
701<div class="targetlang"><pre>
702octave:1> a=subclass();
703octave:2> a.my_var = 4;
704octave:3> a.my_method = @(self) printf("my_var = ",self.my_var);
705octave:4> a.my_method();
706my_var = 4
707</pre></div>
708<p>
709<tt>subclass()</tt> can also be used to subclass one or more C++ types. Suppose you have an interface defined by
710</p>
711<div class="code"><pre>
712%inline {
713class A {
714public:
715 virtual my_method() {
716 printf("c-side routine called\n");
717 }
718};
719void call_your_method(A& a) {
720 a.my_method();
721}
722}
723</pre></div>
724<p>
725Then from Octave you can say:
726</p>
727<div class="targetlang"><pre>
728octave:1> B=@() subclass(A(),@my_method);
729octave:2> function my_method(self)
730octave:3> printf("octave-side routine called\n");
731octave:4> end
732octave:5> call_your_method(B());
733octave-side routine called
734</pre></div>
735<p>
736or more concisely,
737</p>
738<div class="targetlang"><pre>
739octave:1> B=@() subclass(A(),'my_method',@(self) printf("octave-side routine called\n"));
740octave:2> call_your_method(B());
741octave-side routine called
742</pre></div>
743<p>
744Note that you have to enable directors via the %feature directive (see other modules for this).
745</p>
746<p>
747<tt>subclass()</tt> will accept any number of C++ bases or other <tt>subclass()</tt>'ed objects, <tt>(string,octave_value)</tt> pairs, and <tt>function_handles</tt>. In the first case, these are taken as base classes; in the second case, as named members (either variables or functions, depending on whether the given value is a function handle); in the third case, as member functions whose name is taken from the given function handle. E.g.,
748</p>
749<div class="targetlang"><pre>
750octave:1> B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',@(self) do_stuff())
751</pre></div>
752<p>
753You can also assign non-C++ member variables and functions after construct time. There is no support for non-C++ static members.
754</p>
755<p>
756There is limited support for explicitly referencing C++ bases. So, in the example above, we could have
757</p>
758<div class="targetlang"><pre>
759octave:1> B=@() subclass(A(),@my_method);
760octave:2> function my_method(self)
761octave:3> self.A.my_method();
762octave:4> printf("octave-side routine called\n");
763octave:5> end
764octave:6> call_your_method(B());
765c-side routine called
766octave-side routine called
767</pre></div>
768
769<H3><a name="Octave_nn23"></a>26.3.14 Threads</H3>
770
771
772<p>
773The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
774</p>
775
776<H3><a name="Octave_nn24"></a>26.3.15 Memory management</H3>
777
778
779<p>
780As noted above, <tt>swig_ref</tt> represents a reference counted pointer to a C/C++-side object. It also contains a flag indicating whether Octave or the C/C++ code owns the object. If Octave owns it, any destructors will be called when the reference count reaches zero. If the C/C++ side owns the object, then destructors will not be called when the reference count goes to zero.
781</p>
782<p>
783For example,
784<div class="code"><pre>
785%inline {
786class A {
787public:
788 A() { printf("A constructing\n"); }
789 ~A() { printf("A destructing\n"); }
790};
791}
792</pre></div>
793<p>
794Would produce this behavior in Octave:
795</p>
796<div class="targetlang"><pre>
797octave:1> a=A();
798A constructing
799octave:2> b=a;
800octave:3> clear a;
801octave:4> b=4;
802A destructing
803</pre></div>
804<p>
805The %newobject directive may be used to control this behavior for pointers returned from functions.
806<p>
807In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
808</p>
809
810<H3><a name="Octave_nn25"></a>26.3.16 STL support</H3>
811
812
813<p>
814This is some skeleton support for various STL containers.
815</p>
816
817<H3><a name="Octave_nn26"></a>26.3.17 Matrix typemaps</H3>
818
819
820<p>
821Octave provides a rich set of classes for dealing with matrices. Currently there are no built-in typemaps to deal with those. However, these are relatively straight forward for users to add themselves (see the docs on typemaps). Without much work (a single typemap decl-- say, 5 lines of code in the interface file), it would be possible to have a function
822</p>
823<div class="code"><pre>
824double my_det(const double* mat,int m,int n);
825</pre></div>
826<p>
827that is accessed from Octave as,
828</p>
829<div class="targetlang"><pre>
830octave:1> my_det(rand(4));
831ans = -0.18388
832</pre></div>
833
834 <tt><br></tt>
835 </body>
836</html>