NAME

XS::Framework::Manual::recipe02 - XS::Framework basics

DESCRIPTION

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.

    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).

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.

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.

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.

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.

    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.

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.