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 The following example shows how C++ snippets map to Perl:
124 Example 1:
126 use Inline CPP => <<'END';
128 using namespace std;
130 int doodle() { }
132 class Foo {
134 public:
135 Foo();
136 ~Foo();
137 int get_data() { return data; }
139 void set_data(int a) { data = a; }
140 private:
141 int data;
142 };
143 Foo::Foo() { cout << "creating a Foo()" << endl; }
145 Foo::~Foo() { cout << "deleting a Foo()" << endl; }
146 END
148 After running the code above, your Perl runtime would look similar to
150 if following code had been run:
151 sub main::doodle { }
153 package main::Foo;
155 sub new { print "creating a Foo()\n"; bless {}, shift }
157 sub DESTROY { print "deleting a Foo()\n" }
158 sub get_data { my $o=shift; $o->{data} }
160 sub set_data { my $o=shift; $o->{data} = shift }
161 The difference, of course, is that in the latter, Perl does the work.
163 In the Inline::CPP example, all function calls get sent off to your C++
164 code. That means that things like this won't work:
165 my $obj = new Foo;
167 $obj->{extrafield} = 10;
168 It doesn't work because $obj is not a blessed hash. It's a blessed
170 reference to a C++ object.
171
173 The first time you run a program that uses Inline::CPP, the C++ code
174 will be compiled into an "_Inline/" or ".Inline/" folder within the
175 working directory. The first run will incur a startup time penalty
176 associated with compiling C++ code. However, the compiled code is
177 cached, and assuming it's not modified, subsequent runs will skip the
178 C++ compilation, and startup time will be fast.
179
181 Inline C++ code can reside just about anywhere you want within your
182 Perl code. Much of this is documented more fully in the Inline POD,
183 but here are some basics:
184 use Inline CPP => 'DATA';
186 # Perl code here
188 __DATA__
190 __CPP__
191 // C++ code here.
193 Or....
195 use Inline CPP => <<'END_CPP';
197 // C++ code here.
198 END_CPP
199 Structurally where does it belong? For simple one-off scripts, just
201 put it anywhere you want. But in the spirit of code reusability, it's
202 often better to simply create a module that houses the functionality
203 build upon C++ code:
204 # Foo/Bar.pm
206 package Foo::Bar;
207 use Inline CPP => 'DATA';
208 # Perl code here, including Exporter mantra, if needed.
210 __DATA__
212 __CPP__
213 // C++ here.....
214 Where you place your module's file(s) follows the same rules as plain
216 old Perl, which is beyond the scope of this POD, but fortunatly no
217 different from what you're used to (assuming you're used to writing
218 Perl modules).
219 Of course, modules can be shared by multiple scripts while only
221 incurring that compilation startup penalty one time, ever.
222
224 Taking the concept of code-reuse one step further, it is entirely
225 possible to package a distribution with an Inline::CPP dependency.
226 When the user installs the distribution (aka, the module), the C++ code
227 will be compiled during module build time, and never again (unless the
228 user upgrades the module). So the user will never see the startup lag
229 associated with C++ code compilation.
230 An example and proof-of-concept for this approach can be found in the
232 CPAN module Math::Prime::FastSieve.
233 This approach involves using Inline::MakeMaker, and is well documented
235 in the Inline POD under the heading Writing Modules with Inline
236 <http://search.cpan.org/perldoc?Inline#Writing_Modules_with_Inline>
237 However, you may wish to remove the Inline::CPP dependency altogether
239 from the code that you bundle into a distribution. This can be done
240 using InlineX::CPP2XS, which converts the Inline::CPP generated code to
241 Perl XS code, fit for distribution without the Inline::CPP dependency.
242 InlineX::CPP2XS includes an example/ directory that actually converts
243 Math::Prime::FastSieve to pure XS.
244 Some extension authors choose to implement first in Inline::CPP, and
246 then manually tweak, then copy and paste the resulting XS file into
247 their own distribution, with similar effect (and possibly a little
248 finer-grained control) to the CPP2XS approach.
249 Perl Namespaces
251 Let's say you use Inline::CPP like this:
252 package Some::Foo;
254 use Inline CPP => <<'END_CPP';
255 #include <iostream>
257 using namespace std;
258 class Foo {
260 private:
261 int data;
262 public:
263 Foo() { cout << "creating a Foo()" << endl; }
264 ~Foo() { cout << "deleting a Foo()" << endl; }
265 };
266 END_CPP
268 1;
269 The issue is that the C++ class, ""Foo"" will be mapped to Perl below
271 the "Some::Foo" namespace, as "Some::Foo::Foo", and would need to be
272 instantiated like this: "my $foo = Some::Foo::Foo->new()". This
273 probably isn't what the user intended. Use the namespace configuration
274 option to set your base namespace:
275 use Inline CPP => config => namespace => 'Some';
277 Now, "Foo" falls under the "Some" heirarchy: "Some::Foo", and can be
279 instantiated as "my $foo = Some::Foo->new()". This probably is what
280 the user intended.
281
283 For information on how to specify Inline configuration options, see
284 Inline. This section describes each of the configuration options
285 available for C/C++. Most of the options correspond either to the
286 MakeMaker or XS options of the same name. See ExtUtils::MakeMaker and
287 perlxs.
288 All configuration options, including the word "config" are case
290 insensitive. "CPP", and "DATA" are not configuration options, and are
291 not insensitive to case.
292 altlibs
294 Adds a new entry to the end of the list of alternative libraries to
295 bind with. MakeMaker will search through this list and use the first
296 entry where all the libraries are found.
297 use Inline CPP => config => altlibs => '-L/my/other/lib -lfoo';
299 See also the "libs" config option, which appends to the last entry in
301 the list.
302 auto_include
304 Specifies extra statements to be automatically included. They will be
305 added on to the defaults. A newline char will automatically be added.
306 use Inline CPP => config => auto_include => '#include "something.h"';
308 boot
310 Specifies code to be run when your code is loaded. May not contain any
311 blank lines. See perlxs for more information.
312 use Inline CPP => config => boot => 'foo();';
314 cc
316 Specifies which compiler to use. In most cases the configuration
317 default is adequate.
318 use Inline CPP => config => cc => '/usr/bin/g++-4.6';
320 ccflags
322 Specifies extra compiler flags. Corresponds to the MakeMaker option.
323 use Inline CPP => config => ccflags => '-std=c++11';
325 classes
327 use Inline CPP => config =>
328 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' };
329 use Inline CPP => config =>
331 namespace => 'Qux' =>
332 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' };
333 use Inline CPP => config =>
335 classes => sub {
336 my $cpp_class = shift;
337 ...
338 return($perl_package);
339 };
340 Override C++ class name.
342 Under default behavior, a C++ class naming conflict will arise by
344 attempting to implement the C++ classes "Foo::Bar::MyClass" and
345 "Foo::Qux::MyClass" which depend upon one another in some way, because
346 C++ sees both classes as named only "MyClass". We are unable to solve
347 this C++ conflict by using just the "namespace" config option, because
348 "namespace" is only applied to the Perl package name, not the C++ class
349 name.
350 In the future, this issue may be solved via Inline::CPP suport for the
352 native C++ "namespace" operator and/or C++ class names which contain
353 the "::" double-colon scope token.
354 For now, this issue is solved by using the "classes" config option,
356 which accepts either a hash reference or a code reference. When a hash
357 reference is provided, each hash key is a C++ class name, and each hash
358 value is a corresponding Perl class name. This hash reference serves
359 as a C++-to-Perl class name mapping mechanism, and may be used in
360 combination with the "namespace" config option to exercise full control
361 over class and package naming.
362 When a code reference is provided, it must accept as its sole argument
364 the C++ class name, and return a single string value containing the
365 generated Perl package name. When a code reference is provided for the
366 "classes" config option, the value of the "namespace" config option is
367 ignored.
368 The hash reference may be considered a manual mapping method, and the
370 code reference an automatic mapping method.
371 Example file "/tmp/Foo__Bar__MyClass.c":
373 class MyClass {
375 private:
376 int a;
377 public:
378 MyClass() :a(10) {}
379 int fetch () { return a; }
380 };
381 Example file "/tmp/Foo__Qux__MyClass.c":
383 #include "/tmp/Foo__Bar__MyClass.c"
385 class MyClass {
386 private:
387 int a;
388 public:
389 MyClass() :a(20) {}
390 int fetch () { return a; }
391 int other_fetch () { MyClass mybar; return mybar.fetch(); }
392 };
393 We encounter the C++ class naming conflict when we
395 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' => namespace => 'Foo::Qux';
397 The C++ compiler sees two "MyClass" classes and gives a redefinition
399 error:
400 _08conflict_encounter_t_9d68.xs:25:7: error: redefinition of ‘class MyClass’
402 class MyClass {
403 ^
404 In file included from _08conflict_encounter_t_9d68.xs:24:0:
405 /tmp/Foo__Bar__MyClass.c:1:7: error: previous definition of ‘class MyClass’
406 class MyClass {
407 ^
408 The solution is to rename each "MyClass" to utilize unique class names,
410 such as "Foo__Bar__MyClass" and "Foo__Qux__MyClass", and use the
411 "classes" config option.
412 Updated example file "/tmp/Foo__Bar__MyClass.c":
414 class Foo__Bar__MyClass {
416 private:
417 int a;
418 public:
419 Foo__Bar__MyClass() :a(10) {}
420 int fetch () { return a; }
421 };
422 Updated example file "/tmp/Foo__Qux__MyClass.c":
424 #include "/tmp/Foo__Bar__MyClass.c"
426 class Foo__Qux__MyClass {
427 private:
428 int a;
429 public:
430 Foo__Qux__MyClass() :a(20) {}
431 int fetch () { return a; }
432 int other_fetch () { Foo__Bar__MyClass mybar; return mybar.fetch(); }
433 };
434 First, consider the following updated call to Inline using the hash
436 reference method to manually map the namespace and class names. This
437 example does not give any C++ errors, and runs correctly in both C++
438 and Perl:
439 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' =>
441 namespace => 'Foo' =>
442 classes => { 'Foo__Bar__MyClass' => 'Bar::MyClass',
443 'Foo__Qux__MyClass' => 'Qux::MyClass' };
444 Next, consider another updated call to Inline using the code reference
446 method to automatically map the namespace and class names, which may be
447 deployed across more complex codebases. This example automates the
448 mapping of the '__' double- underscore to the '::' double-colon scope
449 token.
450 use Inline CPP => config =>
452 classes => sub { join('::', split('__', shift)); };
453 For more information, please see the runnable examples:
455 "t/classes/07conflict_avoid.t" "t/classes/08auto.t"
456 "t/classes/09auto_mixed.t"
457 filters
459 Specifies one (or more, in an array ref) filter which is to be applied
460 to the code just prior to parsing. The filters are executed one after
461 another, each operating on the output of the previous one. You can pass
462 in a code reference or the name of a prepackaged filter.
463 use Inline CPP => config => filters => [Strip_POD => \&myfilter];
465 use Inline CPP => config => filters => 'Preprocess'; # Inline::Filters
466 The filter may do anything. The code is passed as the first argument,
468 and it returns the filtered code. For a set of prefabricated filters,
469 consider using Inline::Filters.
470 inc
472 Specifies extra include directories. Corresponds to the MakeMaker
473 parameter.
474 use Inline CPP => config => inc => '-I/my/path';
476 ld
478 Specifies the linker to use.
479 lddlflags
481 Specifies which linker flags to use.
482 NOTE: These flags will completely override the existing flags, instead
484 of just adding to them. So if you need to use those too, you must
485 respecify them here.
486 libs
488 Specifies external libraries that should be linked into your code.
489 Corresponds to the MakeMaker parameter.
490 use Inline CPP => config => libs => '-L/your/path -lyourlib';
492 Unlike the "libs" configuration parameter used in Inline::C, successive
494 calls to "libs" append to the previous calls. For example,
495 use Inline CPP => config => libs => '-L/my/path', libs => '-lyourlib';
497 will work correctly, if correct is for both "libs" to be in effect. If
499 you want to add a new element to the list of possible libraries to link
500 with, use the Inline::CPP configuration "altlibs".
501 make
503 Specifies the name of the '"make"' utility to use.
504 myextlib
506 Specifies a user compiled object that should be linked in. Corresponds
507 to the MakeMaker parameter.
508 use Inline CPP => config => myextlib => '/your/path/something.o';
510 namespace
512 use Inline CPP => config => namespace => 'Foo';
513 use Inline CPP => config => namespace => 'main';
514 use Inline CPP => config => namespace => q{};
515 Override default base namespace.
517 Under default behavior, a C++ class "Foo" created by invoking
519 Inline::CPP from "package Bar" will result in the C++ "Foo" class being
520 accessible from Perl as "Bar::Foo". While this default behavior may be
521 desirable in some cases, it might be undesirable in others. An example
522 would be creating a "Foo" class while invoking Inline::CPP from package
523 "Foo". The resulting class will bind to Perl as "Foo::Foo", which is
524 probably not what was intended.
525 This default behavior can be overridden by specifying an alternate base
527 "namespace". Examples are probably the best way to explain this:
528 package Foo;
530 use Inline CPP => config => namespace => 'Bar';
531 use Inline CPP => <<'EOCPP';
532 class Baz {
534 private:
535 int a;
536 public:
537 Baz() :a(20) {}
538 int fetch () { return a; }
539 };
540 EOCPP
541 package main;
543 my $b = Bar::Baz->new();
544 print $b->fetch, "\n"; # 20.
545 As demonstrated here, the namespace in which "Baz" resides can now be
547 made independent of the package from which Inline::CPP has been
548 invoked. Consider instead the default behavior:
549 package Foo;
551 use Inline CPP => <<'EOCPP';
552 class Foo {
553 private:
554 int a;
555 public:
556 Baz() :a(20) {}
557 int fetch () { return a; }
558 };
559 EOCPP
560 package main;
562 my $b = Foo::Foo->new();
563 print $b->fetch, "\n"; # 20.
564 It is probably, in this case, undesirable for the C++ class "Foo" to
566 reside in the Perl "Foo::Foo" namespace. We can fix this by adding our
567 own namespace configuration:
568 package Foo;
570 use Inline CPP => config => namespace => q{}; # Disassociate from
571 # calling package.
572 use Inline CPP => <<'EOCPP';
573 class Baz {
575 private:
576 int a;
577 public:
578 Baz() :a(20) {}
579 int fetch () { return a; }
580 };
581 EOCPP
582 package main;
584 my $b = Foo->new();
585 print $b->fetch, "\n"; # 20.
586 prefix
588 Specifies a prefix that will automatically be stripped from C++
589 functions when they are bound to Perl. Less useful than in C, because
590 C++ mangles its function names to facilitate function overloading.
591 use Inline CPP config => prefix => 'ZLIB_';
593 This only affects C++ function names, not C++ class names or methods.
595 preserve_ellipsis
597 By default, Inline::CPP replaces "..." in bound functions with three
598 spaces, since the arguments are always passed on the Perl Stack, not on
599 the C stack. This is usually desired, since it allows functions with no
600 fixed arguments (most compilers require at least one fixed argument).
601 use Inline CPP config => preserve_ellipsis => 1;
603 or
604 use Inline CPP config => enable => 'preserve_ellipsis';
605 For an example of why "preserve_ellipsis" is normally not needed, see
607 the examples section, below.
608 std_iostream
610 By default, Inline::CPP includes the standard iostream header at the
611 top of your code. Inline::CPP will try to make the proper selection
612 between "iostream.h" (for older compilers) and "iostream" (for newer
613 "Standard compliant" compilers).
614 This option assures that "iostream" (with no ".h") is included, which
616 is the ANSI-compliant version of the header. For most compilers the use
617 of this configuration option should no longer be necessary, as
618 detection is done at module install time. The configuration option is
619 still included only to maintain backward compatibility with code that
620 used to need it.
621 use Inline CPP => config => enable => 'std_iostream';
623 structs
625 Specifies whether to bind C structs into Perl using Inline::Struct.
626 NOTE: Support for this option is experimental. Inline::CPP already
627 binds to structs defined in your code. In C++, structs and classes are
628 treated the same, except that a struct's initial scope is public, not
629 private. Inline::Struct provides autogenerated get/set methods, an
630 overloaded constructor, and several other features not available in
631 Inline::CPP.
632 You can invoke "structs" in several ways:
634 use Inline CPP config => structs => 'Foo';
636 or
637 use Inline CPP config => structs => ['Bar', 'Baz'];
638 Binds the named structs to Perl. Emits warnings if a struct was
640 requested but could not be bound for some reason.
641 use Inline CPP config => enable => 'structs';
643 or
644 use Inline CPP config => structs => 1;
645 Enables binding structs to Perl. All structs which can be bound, will.
647 This parameter overrides all requests for particular structs.
648 use Inline CPP config => disable => 'structs';
650 or
651 use Inline CPP config => structs => 0;
652 Disables binding structs to Perl. Overrides any other settings.
654 See Inline::Struct for more details about how "Inline::Struct" binds C
656 structs to Perl.
657 typemaps
659 Specifies extra typemap files to use. These types will modify the
660 behaviour of C++ parsing. Corresponds to the MakeMaker parameter.
661 use Inline CPP config => typemaps => '/your/path/typemap';
663
665 This section describes how the "Perl" variables get mapped to "C++"
666 variables and back again.
667 Perl uses a stack to pass arguments back and forth to subroutines. When
669 a sub is called, it pops off all its arguments from the stack; when
670 it's done, it pushes its return values back onto the stack.
671 XS (Perl's language for creating C or C++ extensions for Perl) uses
673 "typemaps" to turn SVs into C types and back again. This is done
674 through various XS macro calls, casts, and the Perl API. XS also allows
675 you to define your own mappings.
676 "Inline::CPP" uses a much simpler approach. It parses the system's
678 typemap files and only binds to functions with supported types. You can
679 tell "Inline::CPP" about custom typemap files too.
680 If you have non-trivial data structures in either C++ or Perl, you
682 should probably just pass them as an SV* and do the conversion yourself
683 in your C++ function.
684 In C++, a struct is a class whose default scope is public, not private.
686 Inline::CPP binds to structs with this in mind -- get/set methods are
687 not yet auto-generated (although this feature may be added to an
688 upcoming release).
689 If you have a C struct, you can use Inline::Struct to allow Perl
691 complete access to the internals of the struct. You can create and
692 modify structs from inside Perl, as well as pass structs into C++
693 functions and return them from functions. Please note that
694 Inline::Struct does not understand any C++ features, so constructors
695 and member functions are not supported. See Inline::Struct for more
696 details.
697 Example
699 Say you want to use a C++ standard "string" type. A C++ method that
700 takes or returns such will be ignored unless you tell Perl how to map
701 it to and from Perl data types.
702 Put this in a file called typemap:
704 TYPEMAP
706 string T_CPPSTRING
707 INPUT
709 T_CPPSTRING
711 $var = ($type)SvPV_nolen($arg)
712 OUTPUT
714 T_CPPSTRING
716 sv_setpv((SV*)$arg, $var.c_str());
717 Then this script will work:
719 use Inline CPP => config => typemaps => "typemap";
721 use Inline CPP => <<'END';
722 #ifdef __INLINE_CPP_STANDARD_HEADERS
724 #include <string>
725 #else
726 #include <string.h>
727 #endif
728 #ifdef __INLINE_CPP_NAMESPACE_STD
730 using namespace std;
731 #endif
732 class Abstract {
734 public:
735 virtual string greet2() {
736 string retval = "yo";
737 return retval;
738 }
739 };
740 class Impl : public Abstract {
742 public:
743 Impl() {}
744 ~Impl() {}
745 };
746 END
747 my $o = Impl->new;
749 print $o->greet2, "\n";
750 See t/grammar/09purevt.t for this within the test suite.
752
754 Inline::CPP automatically includes <iostream>, or <iostream.h>,
755 depending on the preference of the target compiler. This distinction
756 illustrates a potential problem when trying to write portable code in
757 C++. Legacy C++ (pre-ANSI-Standard) used headers named, for example,
758 <iostream.h>. As legacy C++ didn't support namespaces, these standard
759 tools were not segregated into a separate namespace.
760 ANSI Standard C++ changed that. Headers were renamed without the '.h'
762 suffix, and standard tools were placed in the '"std"' namespace. The
763 "using namespace std" and "using std::string" constructs were also
764 added to facilitate working with namespaces.
765 So pre-Standard (Legacy) C++ code might look like this:
767 #include <iostream.h>
769 int main() {
770 cout << "Hello world.\n";
771 return 0;
772 }
773 Modern "ANSI Standard C++" compilers would require code like this:
775 #include <iostream>
777 using namespace std;
778 int main() {
779 cout << "Hello world.\n";
780 return 0;
781 }
782 ... or ...
784 #include <iostream>
786 int main() {
787 std::cout << "Hello world.\n";
788 return 0;
789 }
790 ... or even ...
792 #include <iostream>
794 int main() {
795 using std::cout;
796 cout << "Hello world.\n";
797 return 0;
798 }
799 The first snippet is going to be completely incompabible with the
801 second, third or fourth snippets. This is no problem for a C++
802 developer who knows his target compiler. But Perl runs just about
803 everywhere. If similar portability (including backward compatibility)
804 is a design goal, Inline::CPP helps by providing two "#define"
805 constants that may be checked to ascertain which style of headers are
806 being used. The constants are:
807 __INLINE_CPP_STANDARD_HEADERS
809 __INLINE_CPP_NAMESPACE_STD
810 "__INLINE_CPP_STANDARD_HEADERS" will be defined if the target compiler
812 accepts ANSI Standard headers, such as <iostream>.
813 "__INLINE_CPP_NAMESPACE_STD" will be defined if the target compiler
814 supports namespaces. Realistically the two are synonymous; ANSI
815 Standard C++ uses namespaces, places standard library tools in the
816 "std" namespace, and invokes headers with the modern (no '.h' suffix)
817 naming convention. So if one is defined they both should be.
818 They can be used as follows:
820 use Inline CPP => 'DATA';
822 greet();
824 __DATA__
826 __CPP__
827 #ifdef __INLINE_CPP_STANDARD_HEADERS
829 #include <string>
830 #else
831 #include <string.h>
832 #endif
833 #ifdef __INLINE_CPP_NAMESPACE_STD
835 using namespace std;
836 #endif
837 void greet() {
839 string mygreeting = "Hello world!\n";
840 cout << mygreeting;
841 }
842 You may decide that you don't care about maintaining portability with
844 compilers that lock you in to pre-Standadr C++ -- more than a decade
845 behind us. But if you do care (maybe you're basing a CPAN module on
846 Inline::CPP), use these preprocessor definitions as a tool in building
847 a widely portable solution.
848 If you wish, you may "#undef" either of those defs. The definitions
850 are defined before any "auto_include"s -- even <iostream>.
851 Consequently, you may even list "#undef __INLINE_CPP_...." within an
852 "auto_include" configuration directive. I'm not sure why it would be
853 necessary, but could be useful in testing.
854 Regardless of the header type, Inline::CPP will create the following
856 definition in all code it generates:
857 #define __INLINE_CPP 1
859 This can be useful in constructing preprocessor logic that behaves
861 differently under Inline::CPP than under a non-Inline::CPP environment.
862
864 Here are some examples.
865 Example 1 - Farmer Bob
867 This example illustrates how to use a simple class ("Farmer") from
868 Perl. One of the new features in Inline::CPP is binding to classes with
869 inline method definitions:
870 use Inline CPP;
872 my $farmer = new Farmer("Ingy", 42);
874 my $slavedriver = 1;
875 while($farmer->how_tired < 420) {
876 $farmer->do_chores($slavedriver);
877 $slavedriver <<= 1;
878 }
879 print "Wow! The farmer worked ", $farmer->how_long, " hours!\n";
881 __END__
883 __CPP__
884 class Farmer {
886 public:
887 Farmer(char *name, int age);
888 ~Farmer();
889 int how_tired() { return tiredness; }
891 int how_long() { return howlong; }
892 void do_chores(int howlong);
893 private:
895 char *name;
896 int age;
897 int tiredness;
898 int howlong;
899 };
900 Farmer::Farmer(char *name, int age) {
902 this->name = strdup(name);
903 this->age = age;
904 tiredness = 0;
905 howlong = 0;
906 }
907 Farmer::~Farmer() {
909 free(name);
910 }
911 void Farmer::do_chores(int hl) {
913 howlong += hl;
914 tiredness += (age * hl);
915 }
916 Example 2 - Plane and Simple
918 This example demonstrates some new features of Inline::CPP: support for
919 inheritance and abstract classes. The defined methods of the abstract
920 class "Object" are bound to Perl, but there is no constructor or
921 destructor, meaning you cannot instantiate an "Object".
922 The "Airplane" is a fully-bound class which can be created and
924 manipulated from Perl.
925 use Inline 'CPP';
927 my $plane = new Airplane;
929 $plane->print;
930 if ($plane->isa("Object")) { print "Plane is an Object!\n"; }
931 unless ($plane->can("fly")) { print "This plane sucks!\n"; }
932 __END__
934 __CPP__
935 using namespace std;
937 /* Abstract class (interface) */
939 class Object {
940 public:
941 virtual void print() { cout << "Object (" << this << ")" << endl; }
942 virtual void info() = 0;
943 virtual bool isa(char *klass) = 0;
944 virtual bool can(char *method) = 0;
945 };
946 class Airplane : public Object {
948 public:
949 Airplane() {}
950 ~Airplane() {}
951 virtual void info() { print(); }
953 virtual bool isa(char *klass) { return strcmp(klass, "Object")==0; }
954 virtual bool can(char *method) {
955 bool yes = false;
956 yes |= strcmp(method, "print")==0;
957 yes |= strcmp(method, "info")==0;
958 yes |= strcmp(method, "isa")==0;
959 yes |= strcmp(method, "can")==0;
960 return yes;
961 }
962 };
963 Example 3 - The Ellipsis Abridged
965 One of the big advantages of Perl over C or C++ is the ability to pass
966 an arbitrary number of arguments to a subroutine. You can do it in C,
967 but it's messy and difficult to get it right. All of this mess is
968 necessary because C doesn't give the programmer access to the stack.
969 Perl, on the other hand, gives you access to everything.
970 Here's a useful function written in Perl that is relatively slow:
972 sub average {
974 my $average = 0;
975 for (my $i=0; $i<@_; $i++) {
976 $average *= $i;
977 $average += $_[$i];
978 $average /= $i + 1;
979 }
980 return $average;
981 }
982 Here's the same function written in C:
984 double average() {
986 Inline_Stack_Vars;
987 double avg = 0.0;
988 for (int i=0; i<Inline_Stack_Items; i++) {
989 avg *= i;
990 avg += SvNV(Inline_Stack_Item(i));
991 avg /= i + 1;
992 }
993 return avg;
994 }
995 Here's a benchmark program that tests which is faster:
997 use Inline 'CPP';
999 my @numbers = map { rand } (1 .. 10000);
1000 my ($a, $stop);
1001 $stop = 200;
1002 if (@ARGV) {
1003 $a = avg(@numbers) while $stop--;
1004 }
1005 else {
1006 $a = average(@numbers) while $stop--;
1007 }
1008 print "The average of 10000 random numbers is: ", $a, "\n";
1009 sub average {
1011 my $average = 0;
1012 for (my $i=0; $i<@_; $i++) {
1013 $average *= $i;
1014 $average += $_[$i];
1015 $average /= $i + 1;
1016 }
1017 return $average;
1018 }
1019 __END__
1021 __CPP__
1022 double avg(...) {
1024 Inline_Stack_Vars;
1025 double avg = 0.0;
1026 for (int i=0; i<items; i++) {
1027 avg *= i;
1028 avg += SvNV(ST(i));
1029 avg /= i + 1;
1030 }
1031 return avg;
1032 }
1033 Look at the function declaration:
1035 double avg(...)
1037 Why didn't we need to use varargs macros to get at the arguments? Why
1039 didn't the compiler complain that there were no required arguments?
1040 Because Inline::C++ actually compiled this:
1041 double avg( )
1043 When it bound to the function, it noticed the ellipsis and decided to
1045 get rid of it. Any function bound to Perl that has an ellipsis in it
1046 will have its arguments passed via the Perl stack, not the C stack.
1047 That means if you write a function like this:
1048 void myprintf(char *format, ...);
1050 then you'd better be reading things from the Perl stack. If you aren't,
1052 then specify the PRESERVE_ELLIPSIS option in your script. That will
1053 leave the ellipsis in the code for the compiler to whine about. :)
1054 Example 4 - Stacks and Queues
1056 Everyone who learns to program with C++ writes a stack and queue class
1057 sooner or later. I might as well try it from Inline. But why reinvent
1058 the wheel? Perl has a perfectly good Array type, which can easily
1059 implement both a Queue and a Stack.
1060 This example implements a Queue and a Stack class, and shows off just a
1062 few more new features of Inline::CPP: default values to arguments,
1063 use Inline 'CPP';
1065 my $q = new Queue;
1067 $q->q(50);
1068 $q->q("Where am I?");
1069 $q->q("In a queue.");
1070 print "There are ", $q->size, " items in the queue\n";
1071 while($q->size) {
1072 print "About to dequeue: ", $q->peek, "\n";
1073 print "Actually dequeued: ", $q->dq, "\n";
1074 }
1075 my $s = new Stack;
1077 $s->push(42);
1078 $s->push("What?");
1079 print "There are ", $s->size, " items on the stack\n";
1080 while($s->size) {
1081 print "About to pop: ", $s->peek, "\n";
1082 print "Actually popped: ", $s->pop, "\n";
1083 }
1084 __END__
1086 __CPP__
1087 class Queue {
1089 public:
1090 Queue(int sz=0) { q = newAV(); if (sz) av_extend(q, sz-1); }
1091 ~Queue() { av_undef(q); }
1092 int size() {return av_len(q) + 1; }
1094 int q(SV *item) { av_push(q, SvREFCNT_inc(item)); return av_len(q)+1; }
1096 SV *dq() { return av_shift(q); }
1097 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(q,0,0)): &PL_sv_undef;}
1098 private:
1100 AV *q;
1101 };
1102 class Stack {
1104 public:
1105 Stack(int sz=0) { s = newAV(); if (sz) av_extend(s, sz-1); }
1106 ~Stack() { av_undef(s); }
1107 int size() { return av_len(s) + 1; }
1109 int push(SV *i) { av_push(s, SvREFCNT_inc(i)); return av_len(s)+1; }
1111 SV *pop() { return av_pop(s); }
1112 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(s,size()-1,0)) : &PL_sv_undef; }
1113 private:
1115 AV *s;
1116 };
1117 Example 5 - Elipses Revisited (and Overloading or Templates)
1119 This example of how to use elipses is adapted from a discussion on Perl
1120 Monks. The issue was that someone wanted to call overloaded functions.
1121 Perl doesn't understand C++'s overloading rules, and C++ has no idea
1122 how Perl intends to call the functions here. So we write a wrapper to
1123 take control ourselves:
1124 use Inline CPP => 'DATA';
1126 say multiadd( 1 ); # No dispatch; just return the value.
1128 say multiadd( 1, 2 ); # Dispatch add( int, int ).
1129 say multiadd( 1, 2, 3 ); # Dispatch add( int, int, int ).
1130 say multiadd( 1, 2, 3, 4 ); # No dispatch; throw an exception.
1131 __DATA__
1132 __CPP__
1133 #include <stdexcept>
1135 // Inline::CPP won't create predictable bindings to overloaded functions.
1137 int add ( int a, int b ) {
1139 return a + b;
1140 }
1141 int add ( int a, int b, int c ) {
1143 return a + b + c;
1144 }
1145 // But a function call with elipses can dispatch to overloaded functions since
1147 // no Perl binding is required in reaching those functions.
1148 int multiadd ( SV * a, ... ) {
1149 dXSARGS; // Creates a variable 'items' that contains a paramater count.
1150 try{
1151 switch ( items ) {
1152 case 1: return SvIV(ST(0));
1153 case 2: return add( SvIV(ST(0)), SvIV(ST(1)) );
1154 case 3: return add( SvIV(ST(0)), SvIV(ST(1)), SvIV(ST(2)) );
1155 default: throw std::runtime_error(
1156 "multiadd() - Too many args in function call"
1157 );
1158 }
1159 }
1160 catch ( std::runtime_error msg ) {
1161 croak( msg.what() ); // Perl likes croak for exceptions.
1162 }
1163 }
1164 Technically one of the versions of add() will bind to Perl, but it's
1166 fragile to use it, as the rules for which one binds are undefined.
1167 This example overcomes the issue of Perl/XS not understanding
1168 overloading by simply wrapping the calls to overloaded functions in a
1169 function that does understand. And we use elipses to deal with a
1170 variable number of arguments. This same approach can be applied to
1171 calling template-generated code as well.
1172
1174 As Inline currently requires Perl 5.8.1 or later. Since Inline::CPP
1175 depends on Inline, Perl 5.8.1 is also required for Inline::CPP. It's
1176 hard to imagine anyone still using a Perl older than 5.8.1 wanting to
1177 interface with C++, but if you're in that camp, you'll need to roll
1178 back Inline and Inline::CPP to older versions through the magic of
1179 backpan. Inline::CPP version 0.25 was still compatible with Perl
1180 5.005_03. Review the Changes file from the Inline distribution to
1181 decide which Inline version is appropriate for your pre-5.8.1 Perl.
1182
1184 Is Inline::CPP is ready for the C++11 standard? The short answer to
1185 that question is "Mostly, to the extent that your compiler is C++11
1186 standard compliant." There are two issues to consider. First, what is
1187 your compiler capable of (and how to you enable those capabilities),
1188 and second, what does Perl need to care about.
1189 Taking the first question first (because it's the easiest): Use the
1191 "ccflags" option shown above to pass the proper flag to your compiler
1192 to enable C++11 features. Most of what your compiler will support,
1193 "Inline::CPP" will deal with.
1194 You also may need to use the "cc" flag to specify a newer version of
1196 the compiler, if you happen to have more than one installed -- one that
1197 handles C++11 and one that doesn't.
1198 Now for the question of what Perl needs to care about: Inline::CPP
1200 doesn't look inside of functions or methods. That code is treated as a
1201 black box that passes directly through to your compiler. So inside of
1202 your functions and methods, feel free to use whatever C++11 features
1203 you want.
1204 The critical areas are function headers, class definitions, and code
1206 that falls outside of functions or classes. Take Enums for example:
1207 enum Colors { RED, GREEN, BLUE };
1209 How should this map to Perl? There's no clear answer. C++11 adds the
1211 concept of scope to enums:
1212 enum class Colors { RED, GREEN, BLUE };
1214 How this should bind to Perl becomes even more difficult. The fact is
1216 that Inline::CPP won't bind either to Perl. And you're probably better
1217 off with that approach than suddenly having $Colors::RED = 0; showing
1218 up in your Perl code. Do keep in mind, however, the construct is passed
1219 directly through to your C++ compiler, so feel free to use it within
1220 the C++ code. It just won't leak out into your Perl namespaces.
1221 At the moment the most glaring omission from Inline::CPP of valid C++11
1223 syntax is the new "late return type" syntax. C++11 introduced the
1224 following legal syntax:
1225 auto add ( int x, int y ) -> int { return x + y; }
1227 This omission is only going to be a factor for functions that you want
1229 to bind to Perl. If you don't need the function to bind to Perl, the
1230 syntax is fine; Inline::CPP just ignores the function. It's important
1231 to note that the most common uses of this syntax involve templates and
1232 lambdas. Templates don't make sense to Inline::CPP anyway. And lambdas
1233 are still fine, because they take place inside of functions, so
1234 Inline::CPP doesn't see them anyway. For now, just don't use the late
1235 return type syntax in the header of functions that need to bind to
1236 Perl. This may get fixed in future revisions to the grammar.
1237 Another issue is "constexpr":
1239 constexpr int multiply ( int x, int y ) { return x * y; }
1241 "constexpr" isn't recognized by Inline::CPP, so this function won't
1243 bind to Perl. I don't think that "constexpr" functions can even
1244 generate external bindings, because they're resolved to a constant at
1245 compile-time. They really don't make sense for external use (the
1246 compiler can't know how you will call them). Consequently, they'll be
1247 ignored by Inline::CPP (and will pass through to your compiler, so they
1248 will work within your C++ code).
1249 And finally, Rvalue references:
1251 Inline::CPP doesn't (yet) understand this:
1253 int x = 100;
1255 int getInt ()
1257 {
1258 return x;
1259 }
1260 int && getRvalueInt ()
1262 {
1263 return std::move( x );
1264 }
1265 The getInt() function will bind to Perl, but the "&&" syntax isn't
1267 recognized by Inline::CPP, and won't result in a binding being
1268 generated. So getRvalueInt() will be invisible to Perl. However, it
1269 is perfectly legal to use within your C++ code as long as you don't
1270 need it to bind to Perl.
1271 Aside from that (as far as I know), you're good to go! Go ahead and
1273 use the new version of "for( auto it: x ) {...}", or even...
1274 for_each( v.begin(), v.end(), [] (int val) { std::cout << val; } );
1276 The beauty of Inline::CPP is that what goes on inside the black boxes
1278 of functions or methods is irrelevant to the binding process. These
1279 examples will "just work", assuming your C++ compiler understands them.
1280
1282 There are bound to be bugs in code this uncivilized. If you find one,
1283 please file a bug report. Patches are even better. Patches
1284 accompanied by tests are like the holy grail.
1285 When reporting a bug, please do the following:
1287 - If possible, create a brief stand-alone snippet of code that
1289 demonstrates the issue.
1290 - Use L<Github Issues|https://github.com/daoswald/Inline-CPP/issues> to file
1291 your bug report.
1292 - Patches are always welcome, as are tests that tickle a newfound bug.
1293 - Pull requests should avoid touching irrelevant sections of code/POD, and
1295 tests are required before they can be considered for merge.
1296 ...or...
1298 - Put "use Inline REPORTBUG;" at the top of your code, or
1300 use the command line option "perl -MInline=REPORTBUG ...".
1301 - Run your code.
1302 - Follow the printed instructions.
1303 Get involved! Module development is being tracked on a github
1305 repository: <https://github.com/daoswald/Inline-CPP>.
1306 The master branch should always be buildable and usable.
1308 Official releases have version numbers in the following format: 'x.xx',
1310 and are usually tagged with the CPAN release number.
1311 Various development branches will hold a combination of minor commits
1313 and CPAN "Developer" releases (these may have a version number
1314 formatted as: 'x.xx_xxx' to designate a developer-only CPAN release).
1315 Most discussion relating to this module (user or developer) occurs on
1317 the Inline mailing list, inline.perl.org, and in "#inline" on
1318 "irc.perl.org". See <http://lists.perl.org/list/inline.html> for
1319 details on subscribing.
1320 Here are some things to watch out for:
1322 The grammar used for parsing C++ is still quite simple, and does not
1324 allow several features of C++:
1325 Templates: You may use template libraries in your code, but Inline::CPP
1327 won't know how to parse and bind template definitions. The core
1328 problem is that the C++ compiler has no idea how a dynamic language
1329 like Perl intends to invoke template-generated code, and thus, cannot
1330 know what code to generate from the templates. Keep the templates
1331 encapsulated away from the interface that will be exposed to Perl by
1332 wrapping calls in functions that will give the compiler a type to work
1333 with.
1334 Operator overloading
1335 Function overloading -- This is a similar issue to the template
1336 problem. Perl doesn't know about C++'s function overload resolution
1337 rules. And C++ doesn't know about Perl. XS was never designed to deal
1338 with this sort of mismatch. This prevents implementing the Rule of
1339 Three for code that is intended to bind with Perl, but because Perl
1340 handles your bindings, that's probably not an issue.
1341 These three issues (Templates, Operator Overloading, and Function
1342 Overloading) are situations where the C++ language and the Perl
1343 language simply do not map well to one another. The sooner you get
1344 used to this disconnect, the sooner you'll get a feel for what is
1345 going to work and what isn't. Templates are how a static language
1346 like C++ deals with the concept of generic programming. Perl is
1347 such a dynamic language, that templates (which are resolved
1348 entirely at compile time) cannot be resolved when called by Perl.
1349 Perl's concept of parameter passing is so dynamic that function
1350 signatures (which C++ uses in resolving overloads) also can't be
1351 mapped meaningfully. There will be other features of C++ don't map
1352 into Perl, and vice versa. Consider C++ enums. Should Perl treat
1353 them as constants by mapping them via the constant pragma? The
1354 answer is unclear, and the fact is they won't be bound into Perl at
1355 all.
1356 Multiple inheritance doesn't work right (yet).
1358 Multi-dimensional arrays as member data aren't implemented (yet).
1359 Declaring a paramater type of void isn't implemented. Just use "int
1360 myfunc();" instead of "int myfunc(void);". This is C++, not C. It's
1361 ok, really.
1362 Exceptions: While it's ok to throw an exception using 'throw', Perl
1363 won't know how to recover from it, and you'll get a core-dump instead
1364 of a Perlish death. The solution is simple, croak("Message"). Perl
1365 will treat that as a call to "die". The fifth example above
1366 demonstrates how to get the best of both worlds: C++'s rich exception
1367 handling, and Perl's "die".
1368 The gist of it is this: Catch your throws. And anything that can't
1369 be dealt with gracefully, re-throw back to Perl using "croak".
1370 Other grammar problems will probably be discovered. This is Perl, C++,
1372 and XS all sealed into one can of worms. But it can be fun, which is a
1373 description never applicable to raw XS.
1374
1376 For general information about how "Inline" binds code to Perl, see
1377 Inline.
1378 For information on using C with Perl, see Inline::C and
1380 Inline::C-Cookbook. For WMTYEWTK, see perlguts, perlxs, perlxstut,
1381 perlapi, and perlcall. The literature for Inline::C (including the
1382 cookbook) is relevant and useful in learning Inline::CPP too; just
1383 about everything that works for Inline::C will work for Inline::CPP.
1384 Rather than reiterate all those great examples here, it's better to
1385 just refer the reader to Inline::C and Inline::C-Cookbook's
1386 documentation.
1387 For converting an Inline::CPP module to pure XS (for simpler
1389 distribution), see InlineX::CPP2XS. This method is usually preferable
1390 to distributing with an Inline::CPP dependency, however, if you want to
1391 do that, read on...
1392 Math::Prime::FastSieve is a module based on Inline::CPP (using
1394 Inline::CPP and Inline::MakeMaker as dependencies). It serves as a
1395 proof of concept, another example of Inline::CPP at work, and a working
1396 example of basing a CPAN distribution on Inline::CPP.
1397 User and development discussion for Inline modules, including
1399 Inline::CPP occurs on the inline.perl.org mailing list. See
1400 <http://lists.perl.org/list/inline.html> to learn how to subscribe.
1401 The maintainer has found Advanced Perl Programming, 2nd Edition
1403 (O'Reilly) helpful, although its discussion is focused on Inline::C.
1404
1406 Neil Watkiss <NEILW@cpan.org> was the original author.
1407 David Oswald <DAVIDO@cpan.org> is the current maintainer. David
1409 Oswald's Inline::CPP GitHub repo is:
1410 <https://github.com/daoswald/Inline-CPP>
1411 Ingy döt Net <INGY@cpan.org> is the author of "Inline", and
1413 "Inline::C".
1414
1416 Issues are tracked, and may be reported at the distribution's GitHub
1417 issue tracker <https://github.com/daoswald/Inline-CPP/issues>.
1418 Contributors may also fork the repo and issue a pull requests. Tests
1420 should accompany pull requests, and effort should be made to minimize
1421 the scope of any single pull request.
1422 Pull requests should not add author names. Non-trivial contributions
1424 generally warrant attribution in the log maintained in the "Changes"
1425 file, though the decision to do at the discretion of the maintainers.
1426 Please refer to the Artistic 2.0 license, contained in the "LICENSE"
1428 file, included with this distribution for further explanation.
1429
1431 Copyright (c) 2000 - 2003 Neil Watkiss. Copyright (c) 2011 - 2014
1432 David Oswald.
1433 All Rights Reserved. This module is free software, licensed under the
1435 Artistic license, version 2.0.
1436 See http://www.perlfoundation.org/artistic_license_2_0
1438perl v5.36.0 2023-01-20 Inline::CPP(3)