XS::Framework::Manual::recipe02 - XS::Framework basics
This recipe expains difference between ObjectStorageIV and ObjectStorageMG storage policies. The C++ classes, typemaps and XS-adapters are almost the same as in recipe01, i.e.
ObjectStorageIV
ObjectStorageMG
struct DateRecipe02a { DateRecipe02a() { update() ; } void update() { epoch = std::time(nullptr); } int get_epoch() const { return epoch; } private: std::time_t epoch; }; namespace xs { template <> struct Typemap<DateRecipe02a*> : TypemapObject<DateRecipe02a*, DateRecipe02a*, ObjectTypePtr, ObjectStorageIV, StaticCast> { static std::string package () { return "MyTest::Cookbook::DateRecipe02a"; } }; } struct DateRecipe02b { DateRecipe02b() { update() ; } void update() { epoch = std::time(nullptr); } int get_epoch() const { return epoch; } private: std::time_t epoch; }; namespace xs { template <> struct Typemap<DateRecipe02b*> : TypemapObject<DateRecipe02b*, DateRecipe02b*, ObjectTypePtr, ObjectStorageMG, StaticCast> { static std::string package () { return "MyTest::Cookbook::DateRecipe02b"; } }; } MODULE = MyTest PACKAGE = MyTest::Cookbook::DateRecipe02a PROTOTYPES: DISABLE DateRecipe02a* DateRecipe02a::new() { RETVAL = new DateRecipe02a(); } void DateRecipe02a::update() std::time_t DateRecipe02a::get_epoch() BOOT { Stash(__PACKAGE__, GV_ADD).mark_as_loaded(__MODULE__); // (1) } void DateRecipe02a::DESTROY() { } MODULE = MyTest PACKAGE = MyTest::Cookbook::DateRecipe02b PROTOTYPES: DISABLE DateRecipe02b* DateRecipe02a::new() { RETVAL = new DateRecipe02b(); } void DateRecipe02b::update() std::time_t DateRecipe02b::get_epoch() BOOT { Stash(__PACKAGE__, GV_ADD).mark_as_loaded(__MODULE__); // (2) }
The only difference is added BOOT sections (1), and (2). This BOOT sections are added into module BOOT section, i.e. the code will be executed upon xs-module (.so or .dll) being loaded. XS::Framework parser injects special keywords __PACKAGE__ and __MODULE__, which are substituted to string literals of the most recently parsed package and module declarations, i.e. to "MyTest" and "MyTest::Cookbook::DateRecipe02a" of (1).
BOOT
.so
.dll
__PACKAGE__
__MODULE__
The need of use XS::Framework::Manual::SVAPI::Stash method mark_as_loaded is the following: to let Perl think that corresponding perl modules are already loaded, i.e. do not die on use parent qw/MyTest::Cookbook::DateRecipe02b/ below.
mark_as_loaded
use parent qw/MyTest::Cookbook::DateRecipe02b/
Let's create actual instances and see what do they point
my $date_a = MyTest::Cookbook::DateRecipe02a->new(); my $date_b = MyTest::Cookbook::DateRecipe02b->new(); DB<1> x $date_a 0 MyTest::Cookbook::DateRecipe02a=SCALAR(0x25b93a0) -> 13317136 DB<2> x $date_b 0 MyTest::Cookbook::DateRecipe02b=SCALAR(0xcb7ca0) -> undef
The $date_a object uses ObjectStorageIV, i.e. the pointer to C++ DateRecipe02a object is stored in integer field of Perl SV*. So, the number 13317136 is actually pointer to C++ somewhere on a heap.
$date_a
13317136
The $date_b object uses ObjectStorageMG, i.e. pointer to C++ DateRecipe02a object is stored in magic; the Perl SV* itself remains free/undef and it is possible to upgrade it in future.
$date_b
undef
Let's extend class behaviour in Perl, i.e. let's created child class with additional method to_string, which will print human-readable date. That's possible to do for both DateRecipe02a and DateRecipe02b, but we'll do that only for former.
to_string
DateRecipe02a
DateRecipe02b
package MyPerlDateA { use MyTest; use parent qw/MyTest::Cookbook::DateRecipe02a/; sub to_string { return scalar(localtime(shift->get_epoch)); } }; my $date_A = MyPerlDateA->new; my $s_date_A = $date_A->to_string; note "date a = ", $s_date_A, ", ref = ", ref($date_A); # date a = Thu Dec 20 18:45:17 2018, ref = MyPerlDateA
That's works perfectly fine. Let's try something different: let's assume that our date objects are immutable, and create string description in intercepted constructor, then cache that property and always return in to_string method. So, we need to store the cached property somewhere in object.
Now we have a problem with ObjectStorageIV: in Perl SV* there is no space left to store hash or any other data. The storage policy ObjectStorageMG does not suffers that constraint:
package MyPerlDateB { use MyTest; use parent qw/MyTest::Cookbook::DateRecipe02b/; sub new { my $class = shift; my $obj = $class->SUPER::new(); # (3) XS::Framework::obj2hv($obj); # (4) $obj->{_date} = localtime($obj->get_epoch); return $obj; } sub to_string { return shift->{_date} } }; my $date_B = MyPerlDateB->new; my $s_date_B = $date_B->to_string; note "date b = ", $s_date_B, ", ref = ", ref($date_B); # date b = Thu Dec 20 18:45:17 2018, ref = MyPerlDateB
To do that, we should override new method, create the Perl wrapper for parent class via (3), and then upgrade the Perl SV* wrapper to hash reference. Once we have blessed hash reference, we have enough space to store additional data in object. So, the issue is solved.
new
Take away: use ObjectStorageMG storage policy by default, as it allows users of your XS-classes to extend them with additional data they need. ObjectStorageIV does not allow you to do that.
To install XS::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XS::Framework
CPAN shell
perl -MCPAN -e shell install XS::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.