1Inline::CPP(3) User Contributed Perl Documentation Inline::CPP(3)
2
6 Inline::CPP - Write Perl subroutines and classes in C++.
7
9 use Inline CPP;
10 print "9 + 16 = ", add(9, 16), "\n";
12 print "9 - 16 = ", subtract(9, 16), "\n";
13 __END__
15 __CPP__
16 int add(int x, int y) {
18 return x + y;
19 }
20 int subtract(int x, int y) {
22 return x - y;
23 }
24
26 The Inline::CPP module allows you to put C++ source code directly
27 "inline" in a Perl script or module. You code classes or functions in
28 C++, and you can use them as if they were written in Perl.
29
31 "We should forget about small efficiencies, say about 97% of the time:
32 premature optimization is the root of all evil. Yet we should not pass
33 up our opportunities in that critical 3%. A good programmer will not be
34 lulled into complacency by such reasoning, he will be wise to look
35 carefully at the critical code; but only after that code has been
36 identified" -- Donald Knuth
37 Inline::CPP is about that critical 3%.
39 Tom "Duff's Device" Duff once wrote the following: "The alternative to
41 genuflecting before the god of code-bumming is finding a better
42 algorithm... ...If your code is too slow, you must make it faster. If
43 no better algorithm is available, you must trim cycles."
44 Often, well written Perl is fast enough. But when one comes across a
46 situation where performance isn't fast enough, and no better algorithm
47 exists, getting closer to the metal is one way to trim cycles, assuming
48 it's done well. Inline::CPP minimizes the pain in binding C++ code to
49 Perl via XS.
50 Performance can also be evaluated in terms of memory requirements.
52 Perlish datastructures are beautifully simple to use, and quite
53 powerful. But this beauty and power comes at the cost of memory and
54 speed. If you are finding that it is too memory-expensive to hold your
55 data in a Perl array, and a disk-based solution is, for whatever
56 reason, not an option, the memory burden can be aleviated to some
57 degree by holding the data in a C++ data type.
58 This can only go so far. But the common saying is that if you consider
60 a reasonable amount of memory to hold a data structure, double it, and
61 then multiply by ten, you'll have a pretty good feel for how much
62 memory Perl needs to hold it. Inline::CPP can facilitate a leaner
63 alternative.
64 "The standard library saves programmers from having to reinvent the
66 wheel." -- Bjarne Stroustrup
67 Inline::CPP is also about not reinventing the wheel.
69 There are many C and C++ libraries already in existence that provide
71 functionality that is well tested, well debuged, and well understood.
72 There is often no great benefit aside from portability in rewriting
73 such libraries in pure Perl. Even re-writing them in XS is cumbersome
74 and prone to bugs. Inline::CPP can be used to quickly develop Perl
75 bindings to existing C++ libraries.
76 "Brian Ingerson got fed up with writing XS and ended up writing a very
78 clever Perl module called Inline to do it for him."
79 Face it, XS has a big fat learning curve, lots of boilerplate, and is
81 easy to botch it up in difficult to find ways. Inline::CPP exists to
82 make that process easier. By lightening the cognative load and
83 boilerplate drudgery associated with pure XS, Inline::CPP can aid the
84 developer in producing less buggy extension code. It won't shield you
85 entirely from "perlguts", but it will take the edge off of it.
86
88 Inline::CPP just parses the subroutine and class signatures within your
89 C++ code and creates bindings to them. Like Inline::C, you will need a
90 suitable compiler the first time you run the script.
91 If you're one of the fortunate majority, you will accept the defaults
93 as you install Inline::CPP; the correct C++ compiler and standard
94 libraries will be configured for you. If you're one of the unfortunate
95 (and shrinking) minority, read on.
96 Here's the rule: use a C++ compiler that's compatible with the compiler
98 which built "perl". For instance, if "perl" was built with "gcc", use
99 "g++". If you're on a Sun or an IRIX box and the system C compiler
100 "cc" built "perl", then use the system C++ compiler, "CC".
101 Some compilers actually compile both C and C++ with the same compiler.
103 Microsoft's "cl.exe" is one such compiler -- you pass it the <-TP> flag
104 to convince it that you want C++ mode. Hopefully this will be deduced
105 by default at install time.
106 If you're using the GNU C++ compiler, make sure that you have the g++
108 front end installed (some Linux distros don't install it by default,
109 but provide it via their package management utilities).
110
112 Inline::CPP is very similar to Inline::C, and in most cases can be used
113 in place of Inline::C without changing a single line of Perl or C code.
114 If you haven't done so already, you should stop reading right now and
115 read the documentation for Inline::C, including the Inline::C-Cookbook.
116 This module uses a grammar to parse your C++ code, and binds to
118 functions or classes which are recognized. If a function is recognized,
119 it will be available from Perl space. If the function's signature is
120 not recognized, it will not be available from Perl, but will be
121 available from other functions or classes within the C++ code.
122 For more information about the grammar used to parse C++ code, see the
124 section called "Grammar".
125 The following example shows how C++ snippets map to Perl:
127 Example 1:
129 use Inline CPP => <<'END';
131 using namespace std;
133 int doodle() { }
135 class Foo {
137 public:
138 Foo();
139 ~Foo();
140 int get_data() { return data; }
142 void set_data(int a) { data = a; }
143 private:
144 int data;
145 };
146 Foo::Foo() { cout << "creating a Foo()" << endl; }
148 Foo::~Foo() { cout << "deleting a Foo()" << endl; }
149 END
151 After running the code above, your Perl runtime would look similar to
153 if following code had been run:
154 sub main::doodle { }
156 package main::Foo;
158 sub new { print "creating a Foo()\n"; bless {}, shift }
160 sub DESTROY { print "deleting a Foo()\n" }
161 sub get_data { my $o=shift; $o->{data} }
163 sub set_data { my $o=shift; $o->{data} = shift }
164 The difference, of course, is that in the latter, Perl does the work.
166 In the Inline::CPP example, all function calls get sent off to your C++
167 code. That means that things like this won't work:
168 my $obj = new Foo;
170 $obj->{extrafield} = 10;
171 It doesn't work because $obj is not a blessed hash. It's a blessed
173 reference to a C++ object.
174
176 The first time you run a program that uses Inline::CPP, the C++ code
177 will be compiled into an "_Inline/" or ".Inline/" folder within the
178 working directory. The first run will incur a startup time penalty
179 associated with compiling C++ code. However, the compiled code is
180 cached, and assuming it's not modified, subsequent runs will skip the
181 C++ compilation, and startup time will be fast.
182
184 Inline C++ code can reside just about anywhere you want within your
185 Perl code. Much of this is documented more fully in the Inline POD,
186 but here are some basics:
187 use Inline CPP => 'DATA';
189 # Perl code here
191 __DATA__
193 __CPP__
194 // C++ code here.
196 Or....
198 use Inline CPP => <<'END_CPP';
200 // C++ code here.
201 END_CPP
202 Structurally where does it belong? For simple one-off scripts, just
204 put it anywhere you want. But in the spirit of code reusability, it's
205 often better to simply create a module that houses the functionality
206 build upon C++ code:
207 # Foo/Bar.pm
209 package Foo::Bar;
210 use Inline CPP => 'DATA';
211 # Perl code here, including Exporter mantra, if needed.
213 __DATA__
215 __CPP__
216 // C++ here.....
217 Where you place your module's file(s) follows the same rules as plain
219 old Perl, which is beyond the scope of this POD, but fortunatly no
220 different from what you're used to (assuming you're used to writing
221 Perl modules).
222 Of course, modules can be shared by multiple scripts while only
224 incurring that compilation startup penalty one time, ever.
225
227 Taking the concept of code-reuse one step further, it is entirely
228 possible to package a distribution with an Inline::CPP dependency.
229 When the user installs the distribution (aka, the module), the C++ code
230 will be compiled during module build time, and never again (unless the
231 user upgrades the module). So the user will never see the startup lag
232 associated with C++ code compilation.
233 An example and proof-of-concept for this approach can be found in the
235 CPAN module Math::Prime::FastSieve.
236 This approach involves using Inline::MakeMaker, and is well documented
238 in the Inline POD under the heading Writing Modules with Inline
239 <http://search.cpan.org/perldoc?Inline#Writing_Modules_with_Inline>
240 However, you may wish to remove the Inline::CPP dependency altogether
242 from the code that you bundle into a distribution. This can be done
243 using InlineX::CPP2XS, which converts the Inline::CPP generated code to
244 Perl XS code, fit for distribution without the Inline::CPP dependency.
245 InlineX::CPP2XS includes an example/ directory that actually converts
246 Math::Prime::FastSieve to pure XS.
247 Some extension authors choose to implement first in Inline::CPP, and
249 then manually tweak, then copy and paste the resulting XS file into
250 their own distribution, with similar effect (and possibly a little
251 finer-grained control) to the CPP2XS approach.
252 Perl Namespaces
254 Let's say you use Inline::CPP like this:
255 package Some::Foo;
257 use Inline CPP => <<'END_CPP';
258 #include <iostream>
260 using namespace std;
261 class Foo {
263 private:
264 int data;
265 public:
266 Foo() { cout << "creating a Foo()" << endl; }
267 ~Foo() { cout << "deleting a Foo()" << endl; }
268 };
269 END_CPP
271 1;
272 The issue is that the C++ class, ""Foo"" will be mapped to Perl below
274 the "Some::Foo" namespace, as "Some::Foo::Foo", and would need to be
275 instantiated like this: "my $foo = Some::Foo::Foo->new()". This
276 probably isn't what the user intended. Use the namespace configuration
277 option to set your base namespace:
278 use Inline CPP => config => namespace => 'Some';
280 Now, "Foo" falls under the "Some" heirarchy: "Some::Foo", and can be
282 instantiated as "my $foo = Some::Foo->new()". This probably is what
283 the user intended.
284
286 For information on how to specify Inline configuration options, see
287 Inline. This section describes each of the configuration options
288 available for C/C++. Most of the options correspond either to the
289 MakeMaker or XS options of the same name. See ExtUtils::MakeMaker and
290 perlxs.
291 All configuration options, including the word "config" are case
293 insensitive. "CPP", and "DATA" are not configuration options, and are
294 not insensitive to case.
295 altlibs
297 Adds a new entry to the end of the list of alternative libraries to
298 bind with. MakeMaker will search through this list and use the first
299 entry where all the libraries are found.
300 use Inline CPP => config => altlibs => '-L/my/other/lib -lfoo';
302 See also the "libs" config option, which appends to the last entry in
304 the list.
305 auto_include
307 Specifies extra statements to be automatically included. They will be
308 added on to the defaults. A newline char will automatically be added.
309 use Inline CPP => config => auto_include => '#include "something.h"';
311 boot
313 Specifies code to be run when your code is loaded. May not contain any
314 blank lines. See perlxs for more information.
315 use Inline CPP => config => boot => 'foo();';
317 cc
319 Specifies which compiler to use. In most cases the configuration
320 default is adequate.
321 use Inline CPP => config => cc => '/usr/bin/g++-4.6';
323 ccflags
325 Specifies extra compiler flags. Corresponds to the MakeMaker option.
326 use Inline CPP => config => ccflags => '-std=c++11';
328 classes
330 use Inline CPP => config =>
331 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' };
332 use Inline CPP => config =>
334 namespace => 'Qux' =>
335 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' };
336 use Inline CPP => config =>
338 classes => sub {
339 my $cpp_class = shift;
340 ...
341 return($perl_package);
342 };
343 Override C++ class name.
345 Under default behavior, a C++ class naming conflict will arise by
347 attempting to implement the C++ classes "Foo::Bar::MyClass" and
348 "Foo::Qux::MyClass" which depend upon one another in some way, because
349 C++ sees both classes as named only "MyClass". We are unable to solve
350 this C++ conflict by using just the "namespace" config option, because
351 "namespace" is only applied to the Perl package name, not the C++ class
352 name.
353 In the future, this issue may be solved via Inline::CPP suport for the
355 native C++ "namespace" operator and/or C++ class names which contain
356 the "::" double-colon scope token.
357 For now, this issue is solved by using the "classes" config option,
359 which accepts either a hash reference or a code reference. When a hash
360 reference is provided, each hash key is a C++ class name, and each hash
361 value is a corresponding Perl class name. This hash reference serves
362 as a C++-to-Perl class name mapping mechanism, and may be used in
363 combination with the "namespace" config option to exercise full control
364 over class and package naming.
365 When a code reference is provided, it must accept as its sole argument
367 the C++ class name, and return a single string value containing the
368 generated Perl package name. When a code reference is provided for the
369 "classes" config option, the value of the "namespace" config option is
370 ignored.
371 The hash reference may be considered a manual mapping method, and the
373 code reference an automatic mapping method.
374 Example file "/tmp/Foo__Bar__MyClass.c":
376 class MyClass {
378 private:
379 int a;
380 public:
381 MyClass() :a(10) {}
382 int fetch () { return a; }
383 };
384 Example file "/tmp/Foo__Qux__MyClass.c":
386 #include "/tmp/Foo__Bar__MyClass.c"
388 class MyClass {
389 private:
390 int a;
391 public:
392 MyClass() :a(20) {}
393 int fetch () { return a; }
394 int other_fetch () { MyClass mybar; return mybar.fetch(); }
395 };
396 We encounter the C++ class naming conflict when we
398 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' => namespace => 'Foo::Qux';
400 The C++ compiler sees two "MyClass" classes and gives a redefinition
402 error:
403 _08conflict_encounter_t_9d68.xs:25:7: error: redefinition of ‘class MyClass’
405 class MyClass {
406 ^
407 In file included from _08conflict_encounter_t_9d68.xs:24:0:
408 /tmp/Foo__Bar__MyClass.c:1:7: error: previous definition of ‘class MyClass’
409 class MyClass {
410 ^
411 The solution is to rename each "MyClass" to utilize unique class names,
413 such as "Foo__Bar__MyClass" and "Foo__Qux__MyClass", and use the
414 "classes" config option.
415 Updated example file "/tmp/Foo__Bar__MyClass.c":
417 class Foo__Bar__MyClass {
419 private:
420 int a;
421 public:
422 Foo__Bar__MyClass() :a(10) {}
423 int fetch () { return a; }
424 };
425 Updated example file "/tmp/Foo__Qux__MyClass.c":
427 #include "/tmp/Foo__Bar__MyClass.c"
429 class Foo__Qux__MyClass {
430 private:
431 int a;
432 public:
433 Foo__Qux__MyClass() :a(20) {}
434 int fetch () { return a; }
435 int other_fetch () { Foo__Bar__MyClass mybar; return mybar.fetch(); }
436 };
437 First, consider the following updated call to Inline using the hash
439 reference method to manually map the namespace and class names. This
440 example does not give any C++ errors, and runs correctly in both C++
441 and Perl:
442 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' =>
444 namespace => 'Foo' =>
445 classes => { 'Foo__Bar__MyClass' => 'Bar::MyClass',
446 'Foo__Qux__MyClass' => 'Qux::MyClass' };
447 Next, consider another updated call to Inline using the code reference
449 method to automatically map the namespace and class names, which may be
450 deployed across more complex codebases. This example automates the
451 mapping of the '__' double- underscore to the '::' double-colon scope
452 token.
453 use Inline CPP => config =>
455 classes => sub { join('::', split('__', shift)); };
456 For more information, please see the runnable examples:
458 "t/classes/07conflict_avoid.t" "t/classes/08auto.t"
459 "t/classes/09auto_mixed.t"
460 filters
462 Specifies one (or more, in an array ref) filter which is to be applied
463 to the code just prior to parsing. The filters are executed one after
464 another, each operating on the output of the previous one. You can pass
465 in a code reference or the name of a prepackaged filter.
466 use Inline CPP => config => filters => [Strip_POD => \&myfilter];
468 use Inline CPP => config => filters => 'Preprocess'; # Inline::Filters
469 The filter may do anything. The code is passed as the first argument,
471 and it returns the filtered code. For a set of prefabricated filters,
472 consider using Inline::Filters.
473 inc
475 Specifies extra include directories. Corresponds to the MakeMaker
476 parameter.
477 use Inline CPP => config => inc => '-I/my/path';
479 ld
481 Specifies the linker to use.
482 lddlflags
484 Specifies which linker flags to use.
485 NOTE: These flags will completely override the existing flags, instead
487 of just adding to them. So if you need to use those too, you must
488 respecify them here.
489 libs
491 Specifies external libraries that should be linked into your code.
492 Corresponds to the MakeMaker parameter.
493 use Inline CPP => config => libs => '-L/your/path -lyourlib';
495 Unlike the "libs" configuration parameter used in Inline::C, successive
497 calls to "libs" append to the previous calls. For example,
498 use Inline CPP => config => libs => '-L/my/path', libs => '-lyourlib';
500 will work correctly, if correct is for both "libs" to be in effect. If
502 you want to add a new element to the list of possible libraries to link
503 with, use the Inline::CPP configuration "altlibs".
504 make
506 Specifies the name of the '"make"' utility to use.
507 myextlib
509 Specifies a user compiled object that should be linked in. Corresponds
510 to the MakeMaker parameter.
511 use Inline CPP => config => myextlib => '/your/path/something.o';
513 namespace
515 use Inline CPP => config => namespace => 'Foo';
516 use Inline CPP => config => namespace => 'main';
517 use Inline CPP => config => namespace => q{};
518 Override default base namespace.
520 Under default behavior, a C++ class "Foo" created by invoking
522 Inline::CPP from "package Bar" will result in the C++ "Foo" class being
523 accessible from Perl as "Bar::Foo". While this default behavior may be
524 desirable in some cases, it might be undesirable in others. An example
525 would be creating a "Foo" class while invoking Inline::CPP from package
526 "Foo". The resulting class will bind to Perl as "Foo::Foo", which is
527 probably not what was intended.
528 This default behavior can be overridden by specifying an alternate base
530 "namespace". Examples are probably the best way to explain this:
531 package Foo;
533 use Inline CPP => config => namespace => 'Bar';
534 use Inline CPP => <<'EOCPP';
535 class Baz {
537 private:
538 int a;
539 public:
540 Baz() :a(20) {}
541 int fetch () { return a; }
542 };
543 EOCPP
544 package main;
546 my $b = Bar::Baz->new();
547 print $b->fetch, "\n"; # 20.
548 As demonstrated here, the namespace in which "Baz" resides can now be
550 made independent of the package from which Inline::CPP has been
551 invoked. Consider instead the default behavior:
552 package Foo;
554 use Inline CPP => <<'EOCPP';
555 class Foo {
556 private:
557 int a;
558 public:
559 Baz() :a(20) {}
560 int fetch () { return a; }
561 };
562 EOCPP
563 package main;
565 my $b = Foo::Foo->new();
566 print $b->fetch, "\n"; # 20.
567 It is probably, in this case, undesirable for the C++ class "Foo" to
569 reside in the Perl "Foo::Foo" namespace. We can fix this by adding our
570 own namespace configuration:
571 package Foo;
573 use Inline CPP => config => namespace => q{}; # Disassociate from
574 # calling package.
575 use Inline CPP => <<'EOCPP';
576 class Baz {
578 private:
579 int a;
580 public:
581 Baz() :a(20) {}
582 int fetch () { return a; }
583 };
584 EOCPP
585 package main;
587 my $b = Foo->new();
588 print $b->fetch, "\n"; # 20.
589 prefix
591 Specifies a prefix that will automatically be stripped from C++
592 functions when they are bound to Perl. Less useful than in C, because
593 C++ mangles its function names to facilitate function overloading.
594 use Inline CPP config => prefix => 'ZLIB_';
596 This only affects C++ function names, not C++ class names or methods.
598 preserve_ellipsis
600 By default, Inline::CPP replaces "..." in bound functions with three
601 spaces, since the arguments are always passed on the Perl Stack, not on
602 the C stack. This is usually desired, since it allows functions with no
603 fixed arguments (most compilers require at least one fixed argument).
604 use Inline CPP config => preserve_ellipsis => 1;
606 or
607 use Inline CPP config => enable => 'preserve_ellipsis';
608 For an example of why "preserve_ellipsis" is normally not needed, see
610 the examples section, below.
611 std_iostream
613 By default, Inline::CPP includes the standard iostream header at the
614 top of your code. Inline::CPP will try to make the proper selection
615 between "iostream.h" (for older compilers) and "iostream" (for newer
616 "Standard compliant" compilers).
617 This option assures that "iostream" (with no ".h") is included, which
619 is the ANSI-compliant version of the header. For most compilers the use
620 of this configuration option should no longer be necessary, as
621 detection is done at module install time. The configuration option is
622 still included only to maintain backward compatibility with code that
623 used to need it.
624 use Inline CPP => config => enable => 'std_iostream';
626 structs
628 Specifies whether to bind C structs into Perl using Inline::Struct.
629 NOTE: Support for this option is experimental. Inline::CPP already
630 binds to structs defined in your code. In C++, structs and classes are
631 treated the same, except that a struct's initial scope is public, not
632 private. Inline::Struct provides autogenerated get/set methods, an
633 overloaded constructor, and several other features not available in
634 Inline::CPP.
635 You can invoke "structs" in several ways:
637 use Inline CPP config => structs => 'Foo';
639 or
640 use Inline CPP config => structs => ['Bar', 'Baz'];
641 Binds the named structs to Perl. Emits warnings if a struct was
643 requested but could not be bound for some reason.
644 use Inline CPP config => enable => 'structs';
646 or
647 use Inline CPP config => structs => 1;
648 Enables binding structs to Perl. All structs which can be bound, will.
650 This parameter overrides all requests for particular structs.
651 use Inline CPP config => disable => 'structs';
653 or
654 use Inline CPP config => structs => 0;
655 Disables binding structs to Perl. Overrides any other settings.
657 See Inline::Struct for more details about how "Inline::Struct" binds C
659 structs to Perl.
660 typemaps
662 Specifies extra typemap files to use. These types will modify the
663 behaviour of C++ parsing. Corresponds to the MakeMaker parameter.
664 use Inline CPP config => typemaps => '/your/path/typemap';
666
668 This section describes how the "Perl" variables get mapped to "C++"
669 variables and back again.
670 Perl uses a stack to pass arguments back and forth to subroutines. When
672 a sub is called, it pops off all its arguments from the stack; when
673 it's done, it pushes its return values back onto the stack.
674 XS (Perl's language for creating C or C++ extensions for Perl) uses
676 "typemaps" to turn SVs into C types and back again. This is done
677 through various XS macro calls, casts, and the Perl API. XS also allows
678 you to define your own mappings.
679 "Inline::CPP" uses a much simpler approach. It parses the system's
681 typemap files and only binds to functions with supported types. You can
682 tell "Inline::CPP" about custom typemap files too.
683 If you have non-trivial data structures in either C++ or Perl, you
685 should probably just pass them as an SV* and do the conversion yourself
686 in your C++ function.
687 In C++, a struct is a class whose default scope is public, not private.
689 Inline::CPP binds to structs with this in mind -- get/set methods are
690 not yet auto-generated (although this feature may be added to an
691 upcoming release).
692 If you have a C struct, you can use Inline::Struct to allow Perl
694 complete access to the internals of the struct. You can create and
695 modify structs from inside Perl, as well as pass structs into C++
696 functions and return them from functions. Please note that
697 Inline::Struct does not understand any C++ features, so constructors
698 and member functions are not supported. See Inline::Struct for more
699 details.
700
702 Inline::CPP automatically includes <iostream>, or <iostream.h>,
703 depending on the preference of the target compiler. This distinction
704 illustrates a potential problem when trying to write portable code in
705 C++. Legacy C++ (pre-ANSI-Standard) used headers named, for example,
706 <iostream.h>. As legacy C++ didn't support namespaces, these standard
707 tools were not segregated into a separate namespace.
708 ANSI Standard C++ changed that. Headers were renamed without the '.h'
710 suffix, and standard tools were placed in the '"std"' namespace. The
711 "using namespace std" and "using std::string" constructs were also
712 added to facilitate working with namespaces.
713 So pre-Standard (Legacy) C++ code might look like this:
715 #include <iostream.h>
717 int main() {
718 cout << "Hello world.\n";
719 return 0;
720 }
721 Modern "ANSI Standard C++" compilers would require code like this:
723 #include <iostream>
725 using namespace std;
726 int main() {
727 cout << "Hello world.\n";
728 return 0;
729 }
730 ... or ...
732 #include <iostream>
734 int main() {
735 std::cout << "Hello world.\n";
736 return 0;
737 }
738 ... or even ...
740 #include <iostream>
742 int main() {
743 using std::cout;
744 cout << "Hello world.\n";
745 return 0;
746 }
747 The first snippet is going to be completely incompabible with the
749 second, third or fourth snippets. This is no problem for a C++
750 developer who knows his target compiler. But Perl runs just about
751 everywhere. If similar portability (including backward compatibility)
752 is a design goal, Inline::CPP helps by providing two "#define"
753 constants that may be checked to ascertain which style of headers are
754 being used. The constants are:
755 __INLINE_CPP_STANDARD_HEADERS
757 __INLINE_CPP_NAMESPACE_STD
758 "__INLINE_CPP_STANDARD_HEADERS" will be defined if the target compiler
760 accepts ANSI Standard headers, such as <iostream>.
761 "__INLINE_CPP_NAMESPACE_STD" will be defined if the target compiler
762 supports namespaces. Realistically the two are synonymous; ANSI
763 Standard C++ uses namespaces, places standard library tools in the
764 "std" namespace, and invokes headers with the modern (no '.h' suffix)
765 naming convention. So if one is defined they both should be.
766 They can be used as follows:
768 use Inline CPP => 'DATA';
770 greet();
772 __DATA__
774 __CPP__
775 #ifdef __INLINE_CPP_STANDARD_HEADERS
777 #include <string>
778 #else
779 #include <string.h>
780 #endif
781 #ifdef __INLINE_CPP_NAMESPACE_STD
783 using namespace std;
784 #endif
785 void greet() {
787 string mygreeting = "Hello world!\n";
788 cout << mygreeting;
789 }
790 You may decide that you don't care about maintaining portability with
792 compilers that lock you in to pre-Standadr C++ -- more than a decade
793 behind us. But if you do care (maybe you're basing a CPAN module on
794 Inline::CPP), use these preprocessor definitions as a tool in building
795 a widely portable solution.
796 If you wish, you may "#undef" either of those defs. The definitions
798 are defined before any "auto_include"s -- even <iostream>.
799 Consequently, you may even list "#undef __INLINE_CPP_...." within an
800 "auto_include" configuration directive. I'm not sure why it would be
801 necessary, but could be useful in testing.
802 Regardless of the header type, Inline::CPP will create the following
804 definition in all code it generates:
805 #define __INLINE_CPP 1
807 This can be useful in constructing preprocessor logic that behaves
809 differently under Inline::CPP than under a non-Inline::CPP environment.
810
812 Here are some examples.
813 Example 1 - Farmer Bob
815 This example illustrates how to use a simple class ("Farmer") from
816 Perl. One of the new features in Inline::CPP is binding to classes with
817 inline method definitions:
818 use Inline CPP;
820 my $farmer = new Farmer("Ingy", 42);
822 my $slavedriver = 1;
823 while($farmer->how_tired < 420) {
824 $farmer->do_chores($slavedriver);
825 $slavedriver <<= 1;
826 }
827 print "Wow! The farmer worked ", $farmer->how_long, " hours!\n";
829 __END__
831 __CPP__
832 class Farmer {
834 public:
835 Farmer(char *name, int age);
836 ~Farmer();
837 int how_tired() { return tiredness; }
839 int how_long() { return howlong; }
840 void do_chores(int howlong);
841 private:
843 char *name;
844 int age;
845 int tiredness;
846 int howlong;
847 };
848 Farmer::Farmer(char *name, int age) {
850 this->name = strdup(name);
851 this->age = age;
852 tiredness = 0;
853 howlong = 0;
854 }
855 Farmer::~Farmer() {
857 free(name);
858 }
859 void Farmer::do_chores(int hl) {
861 howlong += hl;
862 tiredness += (age * hl);
863 }
864 Example 2 - Plane and Simple
866 This example demonstrates some new features of Inline::CPP: support for
867 inheritance and abstract classes. The defined methods of the abstract
868 class "Object" are bound to Perl, but there is no constructor or
869 destructor, meaning you cannot instantiate an "Object".
870 The "Airplane" is a fully-bound class which can be created and
872 manipulated from Perl.
873 use Inline 'CPP';
875 my $plane = new Airplane;
877 $plane->print;
878 if ($plane->isa("Object")) { print "Plane is an Object!\n"; }
879 unless ($plane->can("fly")) { print "This plane sucks!\n"; }
880 __END__
882 __CPP__
883 using namespace std;
885 /* Abstract class (interface) */
887 class Object {
888 public:
889 virtual void print() { cout << "Object (" << this << ")" << endl; }
890 virtual void info() = 0;
891 virtual bool isa(char *klass) = 0;
892 virtual bool can(char *method) = 0;
893 };
894 class Airplane : public Object {
896 public:
897 Airplane() {}
898 ~Airplane() {}
899 virtual void info() { print(); }
901 virtual bool isa(char *klass) { return strcmp(klass, "Object")==0; }
902 virtual bool can(char *method) {
903 bool yes = false;
904 yes |= strcmp(method, "print")==0;
905 yes |= strcmp(method, "info")==0;
906 yes |= strcmp(method, "isa")==0;
907 yes |= strcmp(method, "can")==0;
908 return yes;
909 }
910 };
911 Example 3 - The Ellipsis Abridged
913 One of the big advantages of Perl over C or C++ is the ability to pass
914 an arbitrary number of arguments to a subroutine. You can do it in C,
915 but it's messy and difficult to get it right. All of this mess is
916 necessary because C doesn't give the programmer access to the stack.
917 Perl, on the other hand, gives you access to everything.
918 Here's a useful function written in Perl that is relatively slow:
920 sub average {
922 my $average = 0;
923 for (my $i=0; $i<@_; $i++) {
924 $average *= $i;
925 $average += $_[$i];
926 $average /= $i + 1;
927 }
928 return $average;
929 }
930 Here's the same function written in C:
932 double average() {
934 Inline_Stack_Vars;
935 double avg = 0.0;
936 for (int i=0; i<Inline_Stack_Items; i++) {
937 avg *= i;
938 avg += SvNV(Inline_Stack_Item(i));
939 avg /= i + 1;
940 }
941 return avg;
942 }
943 Here's a benchmark program that tests which is faster:
945 use Inline 'CPP';
947 my @numbers = map { rand } (1 .. 10000);
948 my ($a, $stop);
949 $stop = 200;
950 if (@ARGV) {
951 $a = avg(@numbers) while $stop--;
952 }
953 else {
954 $a = average(@numbers) while $stop--;
955 }
956 print "The average of 10000 random numbers is: ", $a, "\n";
957 sub average {
959 my $average = 0;
960 for (my $i=0; $i<@_; $i++) {
961 $average *= $i;
962 $average += $_[$i];
963 $average /= $i + 1;
964 }
965 return $average;
966 }
967 __END__
969 __CPP__
970 double avg(...) {
972 Inline_Stack_Vars;
973 double avg = 0.0;
974 for (int i=0; i<items; i++) {
975 avg *= i;
976 avg += SvNV(ST(i));
977 avg /= i + 1;
978 }
979 return avg;
980 }
981 Look at the function declaration:
983 double avg(...)
985 Why didn't we need to use varargs macros to get at the arguments? Why
987 didn't the compiler complain that there were no required arguments?
988 Because Inline::C++ actually compiled this:
989 double avg( )
991 When it bound to the function, it noticed the ellipsis and decided to
993 get rid of it. Any function bound to Perl that has an ellipsis in it
994 will have its arguments passed via the Perl stack, not the C stack.
995 That means if you write a function like this:
996 void myprintf(char *format, ...);
998 then you'd better be reading things from the Perl stack. If you aren't,
1000 then specify the PRESERVE_ELLIPSIS option in your script. That will
1001 leave the ellipsis in the code for the compiler to whine about. :)
1002 Example 4 - Stacks and Queues
1004 Everyone who learns to program with C++ writes a stack and queue class
1005 sooner or later. I might as well try it from Inline. But why reinvent
1006 the wheel? Perl has a perfectly good Array type, which can easily
1007 implement both a Queue and a Stack.
1008 This example implements a Queue and a Stack class, and shows off just a
1010 few more new features of Inline::CPP: default values to arguments,
1011 use Inline 'CPP';
1013 my $q = new Queue;
1015 $q->q(50);
1016 $q->q("Where am I?");
1017 $q->q("In a queue.");
1018 print "There are ", $q->size, " items in the queue\n";
1019 while($q->size) {
1020 print "About to dequeue: ", $q->peek, "\n";
1021 print "Actually dequeued: ", $q->dq, "\n";
1022 }
1023 my $s = new Stack;
1025 $s->push(42);
1026 $s->push("What?");
1027 print "There are ", $s->size, " items on the stack\n";
1028 while($s->size) {
1029 print "About to pop: ", $s->peek, "\n";
1030 print "Actually popped: ", $s->pop, "\n";
1031 }
1032 __END__
1034 __CPP__
1035 class Queue {
1037 public:
1038 Queue(int sz=0) { q = newAV(); if (sz) av_extend(q, sz-1); }
1039 ~Queue() { av_undef(q); }
1040 int size() {return av_len(q) + 1; }
1042 int q(SV *item) { av_push(q, SvREFCNT_inc(item)); return av_len(q)+1; }
1044 SV *dq() { return av_shift(q); }
1045 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(q,0,0)): &PL_sv_undef;}
1046 private:
1048 AV *q;
1049 };
1050 class Stack {
1052 public:
1053 Stack(int sz=0) { s = newAV(); if (sz) av_extend(s, sz-1); }
1054 ~Stack() { av_undef(s); }
1055 int size() { return av_len(s) + 1; }
1057 int push(SV *i) { av_push(s, SvREFCNT_inc(i)); return av_len(s)+1; }
1059 SV *pop() { return av_pop(s); }
1060 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(s,size()-1,0)) : &PL_sv_undef; }
1061 private:
1063 AV *s;
1064 };
1065 Example 5 - Elipses Revisited (and Overloading or Templates)
1067 This example of how to use elipses is adapted from a discussion on Perl
1068 Monks. The issue was that someone wanted to call overloaded functions.
1069 Perl doesn't understand C++'s overloading rules, and C++ has no idea
1070 how Perl intends to call the functions here. So we write a wrapper to
1071 take control ourselves:
1072 use Inline CPP => 'DATA';
1074 say multiadd( 1 ); # No dispatch; just return the value.
1076 say multiadd( 1, 2 ); # Dispatch add( int, int ).
1077 say multiadd( 1, 2, 3 ); # Dispatch add( int, int, int ).
1078 say multiadd( 1, 2, 3, 4 ); # No dispatch; throw an exception.
1079 __DATA__
1080 __CPP__
1081 #include <stdexcept>
1083 // Inline::CPP won't create predictable bindings to overloaded functions.
1085 int add ( int a, int b ) {
1087 return a + b;
1088 }
1089 int add ( int a, int b, int c ) {
1091 return a + b + c;
1092 }
1093 // But a function call with elipses can dispatch to overloaded functions since
1095 // no Perl binding is required in reaching those functions.
1096 int multiadd ( SV * a, ... ) {
1097 dXSARGS; // Creates a variable 'items' that contains a paramater count.
1098 try{
1099 switch ( items ) {
1100 case 1: return SvIV(ST(0));
1101 case 2: return add( SvIV(ST(0)), SvIV(ST(1)) );
1102 case 3: return add( SvIV(ST(0)), SvIV(ST(1)), SvIV(ST(2)) );
1103 default: throw std::runtime_error(
1104 "multiadd() - Too many args in function call"
1105 );
1106 }
1107 }
1108 catch ( std::runtime_error msg ) {
1109 croak( msg.what() ); // Perl likes croak for exceptions.
1110 }
1111 }
1112 Technically one of the versions of add() will bind to Perl, but it's
1114 fragile to use it, as the rules for which one binds are undefined.
1115 This example overcomes the issue of Perl/XS not understanding
1116 overloading by simply wrapping the calls to overloaded functions in a
1117 function that does understand. And we use elipses to deal with a
1118 variable number of arguments. This same approach can be applied to
1119 calling template-generated code as well.
1120
1122 As Inline currently requires Perl 5.8.1 or later. Since Inline::CPP
1123 depends on Inline, Perl 5.8.1 is also required for Inline::CPP. It's
1124 hard to imagine anyone still using a Perl older than 5.8.1 wanting to
1125 interface with C++, but if you're in that camp, you'll need to roll
1126 back Inline and Inline::CPP to older versions through the magic of
1127 backpan. Inline::CPP version 0.25 was still compatible with Perl
1128 5.005_03. Review the Changes file from the Inline distribution to
1129 decide which Inline version is appropriate for your pre-5.8.1 Perl.
1130
1132 Is Inline::CPP is ready for the C++11 standard? The short answer to
1133 that question is "Mostly, to the extent that your compiler is C++11
1134 standard compliant." There are two issues to consider. First, what is
1135 your compiler capable of (and how to you enable those capabilities),
1136 and second, what does Perl need to care about.
1137 Taking the first question first (because it's the easiest): Use the
1139 "ccflags" option shown above to pass the proper flag to your compiler
1140 to enable C++11 features. Most of what your compiler will support,
1141 "Inline::CPP" will deal with.
1142 You also may need to use the "cc" flag to specify a newer version of
1144 the compiler, if you happen to have more than one installed -- one that
1145 handles C++11 and one that doesn't.
1146 Now for the question of what Perl needs to care about: Inline::CPP
1148 doesn't look inside of functions or methods. That code is treated as a
1149 black box that passes directly through to your compiler. So inside of
1150 your functions and methods, feel free to use whatever C++11 features
1151 you want.
1152 The critical areas are function headers, class definitions, and code
1154 that falls outside of functions or classes. Take Enums for example:
1155 enum Colors { RED, GREEN, BLUE };
1157 How should this map to Perl? There's no clear answer. C++11 adds the
1159 concept of scope to enums:
1160 enum class Colors { RED, GREEN, BLUE };
1162 How this should bind to Perl becomes even more difficult. The fact is
1164 that Inline::CPP won't bind either to Perl. And you're probably better
1165 off with that approach than suddenly having $Colors::RED = 0; showing
1166 up in your Perl code. Do keep in mind, however, the construct is passed
1167 directly through to your C++ compiler, so feel free to use it within
1168 the C++ code. It just won't leak out into your Perl namespaces.
1169 At the moment the most glaring omission from Inline::CPP of valid C++11
1171 syntax is the new "late return type" syntax. C++11 introduced the
1172 following legal syntax:
1173 auto add ( int x, int y ) -> int { return x + y; }
1175 This omission is only going to be a factor for functions that you want
1177 to bind to Perl. If you don't need the function to bind to Perl, the
1178 syntax is fine; Inline::CPP just ignores the function. It's important
1179 to note that the most common uses of this syntax involve templates and
1180 lambdas. Templates don't make sense to Inline::CPP anyway. And lambdas
1181 are still fine, because they take place inside of functions, so
1182 Inline::CPP doesn't see them anyway. For now, just don't use the late
1183 return type syntax in the header of functions that need to bind to
1184 Perl. This may get fixed in future revisions to the grammar.
1185 Another issue is "constexpr":
1187 constexpr int multiply ( int x, int y ) { return x * y; }
1189 "constexpr" isn't recognized by Inline::CPP, so this function won't
1191 bind to Perl. I don't think that "constexpr" functions can even
1192 generate external bindings, because they're resolved to a constant at
1193 compile-time. They really don't make sense for external use (the
1194 compiler can't know how you will call them). Consequently, they'll be
1195 ignored by Inline::CPP (and will pass through to your compiler, so they
1196 will work within your C++ code).
1197 And finally, Rvalue references:
1199 Inline::CPP doesn't (yet) understand this:
1201 int x = 100;
1203 int getInt ()
1205 {
1206 return x;
1207 }
1208 int && getRvalueInt ()
1210 {
1211 return std::move( x );
1212 }
1213 The "getInt()" function will bind to Perl, but the "&&" syntax isn't
1215 recognized by Inline::CPP, and won't result in a binding being
1216 generated. So "getRvalueInt()" will be invisible to Perl. However, it
1217 is perfectly legal to use within your C++ code as long as you don't
1218 need it to bind to Perl.
1219 Aside from that (as far as I know), you're good to go! Go ahead and
1221 use the new version of "for( auto it: x ) {...}", or even...
1222 for_each( v.begin(), v.end(), [] (int val) { std::cout << val; } );
1224 The beauty of Inline::CPP is that what goes on inside the black boxes
1226 of functions or methods is irrelevant to the binding process. These
1227 examples will "just work", assuming your C++ compiler understands them.
1228
1230 There are bound to be bugs in code this uncivilized. If you find one,
1231 please file a bug report. Patches are even better. Patches
1232 accompanied by tests are like the holy grail.
1233 When reporting a bug, please do the following:
1235 - If possible, create a brief stand-alone snippet of code that
1237 demonstrates the issue.
1238 - Use L<Github Issues|https://github.com/daoswald/Inline-CPP/issues> to file
1239 your bug report.
1240 - Patches are always welcome, as are tests that tickle a newfound bug.
1241 - Pull requests should avoid touching irrelevant sections of code/POD, and
1243 tests are required before they can be considered for merge.
1244 ...or...
1246 - Put "use Inline REPORTBUG;" at the top of your code, or
1248 use the command line option "perl -MInline=REPORTBUG ...".
1249 - Run your code.
1250 - Follow the printed instructions.
1251 Get involved! Module development is being tracked on a github
1253 repository: <https://github.com/daoswald/Inline-CPP>.
1254 The master branch should always be buildable and usable.
1256 Official releases have version numbers in the following format: 'x.xx',
1258 and are usually tagged with the CPAN release number.
1259 Various development branches will hold a combination of minor commits
1261 and CPAN "Developer" releases (these may have a version number
1262 formatted as: 'x.xx_xxx' to designate a developer-only CPAN release).
1263 Most discussion relating to this module (user or developer) occurs on
1265 the Inline mailing list, inline.perl.org, and in "#inline" on
1266 "irc.perl.org". See <http://lists.perl.org/list/inline.html> for
1267 details on subscribing.
1268 Here are some things to watch out for:
1270 The grammar used for parsing C++ is still quite simple, and does not
1272 allow several features of C++:
1273 Templates: You may use template libraries in your code, but Inline::CPP
1275 won't know how to parse and bind template definitions. The core
1276 problem is that the C++ compiler has no idea how a dynamic language
1277 like Perl intends to invoke template-generated code, and thus, cannot
1278 know what code to generate from the templates. Keep the templates
1279 encapsulated away from the interface that will be exposed to Perl by
1280 wrapping calls in functions that will give the compiler a type to work
1281 with.
1282 Operator overloading
1283 Function overloading -- This is a similar issue to the template
1284 problem. Perl doesn't know about C++'s function overload resolution
1285 rules. And C++ doesn't know about Perl. XS was never designed to deal
1286 with this sort of mismatch. This prevents implementing the Rule of
1287 Three for code that is intended to bind with Perl, but because Perl
1288 handles your bindings, that's probably not an issue.
1289 These three issues (Templates, Operator Overloading, and Function
1290 Overloading) are situations where the C++ language and the Perl
1291 language simply do not map well to one another. The sooner you get
1292 used to this disconnect, the sooner you'll get a feel for what is
1293 going to work and what isn't. Templates are how a static language
1294 like C++ deals with the concept of generic programming. Perl is
1295 such a dynamic language, that templates (which are resolved
1296 entirely at compile time) cannot be resolved when called by Perl.
1297 Perl's concept of parameter passing is so dynamic that function
1298 signatures (which C++ uses in resolving overloads) also can't be
1299 mapped meaningfully. There will be other features of C++ don't map
1300 into Perl, and vice versa. Consider C++ enums. Should Perl treat
1301 them as constants by mapping them via the constant pragma? The
1302 answer is unclear, and the fact is they won't be bound into Perl at
1303 all.
1304 Multiple inheritance doesn't work right (yet).
1306 Multi-dimensional arrays as member data aren't implemented (yet).
1307 Declaring a paramater type of void isn't implemented. Just use "int
1308 myfunc();" instead of "int myfunc(void);". This is C++, not C. It's
1309 ok, really.
1310 Exceptions: While it's ok to throw an exception using 'throw', Perl
1311 won't know how to recover from it, and you'll get a core-dump instead
1312 of a Perlish death. The solution is simple, "croak("Message")". Perl
1313 will treat that as a call to "die". The fifth example above
1314 demonstrates how to get the best of both worlds: C++'s rich exception
1315 handling, and Perl's "die".
1316 The gist of it is this: Catch your throws. And anything that can't
1317 be dealt with gracefully, re-throw back to Perl using "croak".
1318 Other grammar problems will probably be discovered. This is Perl, C++,
1320 and XS all sealed into one can of worms. But it can be fun, which is a
1321 description never applicable to raw XS.
1322
1324 For general information about how "Inline" binds code to Perl, see
1325 Inline.
1326 For information on using C with Perl, see Inline::C and
1328 Inline::C-Cookbook. For WMTYEWTK, see perlguts, perlxs, perlxstut,
1329 perlapi, and perlcall. The literature for Inline::C (including the
1330 cookbook) is relevant and useful in learning Inline::CPP too; just
1331 about everything that works for Inline::C will work for Inline::CPP.
1332 Rather than reiterate all those great examples here, it's better to
1333 just refer the reader to Inline::C and Inline::C-Cookbook's
1334 documentation.
1335 For converting an Inline::CPP module to pure XS (for simpler
1337 distribution), see InlineX::CPP2XS. This method is usually preferable
1338 to distributing with an Inline::CPP dependency, however, if you want to
1339 do that, read on...
1340 Math::Prime::FastSieve is a module based on Inline::CPP (using
1342 Inline::CPP and Inline::MakeMaker as dependencies). It serves as a
1343 proof of concept, another example of Inline::CPP at work, and a working
1344 example of basing a CPAN distribution on Inline::CPP.
1345 User and development discussion for Inline modules, including
1347 Inline::CPP occurs on the inline.perl.org mailing list. See
1348 <http://lists.perl.org/list/inline.html> to learn how to subscribe.
1349 The maintainer has found Advanced Perl Programming, 2nd Edition
1351 (O'Reilly) helpful, although its discussion is focused on Inline::C.
1352
1354 Neil Watkiss <NEILW@cpan.org> was the original author.
1355 David Oswald <DAVIDO@cpan.org> is the current maintainer. David
1357 Oswald's Inline::CPP GitHub repo is:
1358 <https://github.com/daoswald/Inline-CPP>
1359 Ingy döt Net <INGY@cpan.org> is the author of "Inline", and
1361 "Inline::C".
1362
1364 Issues are tracked, and may be reported at the distribution's GitHub
1365 issue tracker <https://github.com/daoswald/Inline-CPP/issues>.
1366 Contributors may also fork the repo and issue a pull requests. Tests
1368 should accompany pull requests, and effort should be made to minimize
1369 the scope of any single pull request.
1370 Pull requests should not add author names. Non-trivial contributions
1372 generally warrant attribution in the log maintained in the "Changes"
1373 file, though the decision to do at the discretion of the maintainers.
1374 Please refer to the Artistic 2.0 license, contained in the "LICENSE"
1376 file, included with this distribution for further explanation.
1377
1379 Copyright (c) 2000 - 2003 Neil Watkiss. Copyright (c) 2011 - 2014
1380 David Oswald.
1381 All Rights Reserved. This module is free software, licensed under the
1383 Artistic license, version 2.0.
1384 See http://www.perlfoundation.org/artistic_license_2_0
1386perl v5.28.0 2018-09-16 Inline::CPP(3)