/ 
XS-Framework-1.5.6
River stage two • 24 direct dependents • 30 total dependents
/ XS::Framework::Manual::Cookbook

NAME

XS::Framework::Manual::Cookbook - XS::Framework cookbook / tutorial

DESCRIPTION

The cookbook consists of recipes, showing the XS::Framework how mechanics works, and, most imporant part, the problems which might be encounted in adopting C++ into perl and how to overcome them.

All sources are availalbe in t/cookbook. Please, use the recipes with the reference ( XS::Framework::Manual::Typemap ), where concepts are disclosed.

BASICS

XS::Framework::Manual::recipe01 demonstrates how to adopt the very simple C++ class; it expains TypemapObject usage with LifetimePolicy = ObjectTypePtr, and StoragePolicy = ObjectStorageIV/ObjectStorageMG.

XS::Framework::Manual::recipe02 demonstrates another difference between ObjectStorageIV and ObjectStorageMG storage policies from Perl inheritance and extendability point of view.

XS::Framework::Manual::recipe03 demonstrates how to use ObjectTypeForeignPtr lifetime policy for C++ objects which follows Singleton pattern with ObjectStorageIV, also it inroduces the notion of const typemap.

XS::Framework::Manual::recipe04 demonstrates how to use ObjectTypeSharedPtr lifetime policy when C++ API returns std::shared_ptr.

XS::Framework::Manual::recipe05 demonstrates how to use ObjectTypeRefcntPtr lifetime policy for C++ API classes with ref-counter support.

XS::Framework::Manual::recipe06 demonstrates how to map C++ classes hierarchy to hierarchy of typemaps and hierarhy of xs-adapters.

ADVANCED TOPICS

XS::Framework::Manual::recipe07 shows what is C3-inheritance in Perl, and how to achive the same in xs-adepters using XS::Framework. The underlying unrelated C++ classes are used to provide basic functions.

XS::Framework::Manual::recipe08 demonstrates how to bind unrelated, but similar C++ classes into single Perl class hierarchy.

If underlying C++ class does not gives enough flexibility for Perl developer, the XS::Framework::Manual::recipe09 shows how to use payload magic or inheritance to store additional runtime association between C++ objects and arbitrary perl data.

There might be cases when C++ offers API for it's objects, where lifetime of one object is linked to the lifetime of the other, i.e. it is returned as reference. In Perl script their lifetimes might be different, as it should be never assumed how Perl developer will use Perl objects. XS::Framework::Manual::recipe10 shows how to "decouple" xs-adapter lifetimes using magic payload.

If you have control on C++ classes, the XS::Framework::Manual::recipe11 expains that providing shared ownership on the object is the most friendly way to integrate them into Perl, and probably other scripting languages. The std::shared_ptr and intrusive refcounter approach are explained.

It is not safe to directly port transient C++ classes, i.e. very short living objects which exist only quant of time. The XS::Framework::Manual::recipe12 shows how to make them non-transient and, that way, safe by the cost of copying dependent C++ objects.

In the XS::Framework::Manual::recipe13 it is shown how to maintain Perl objects data and class identity when they are moved into native C++ containers and returned back; the Backrefs capabilities of XS::Framework should be used.