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

NAME

XS::Framework::Manual::SVAPI - XS::Framework C++ typemap API reference

DESCRIPTION

The SVAPI is C++ perl API makes it convenient to write C++ XS-code. Out of the box Perl offers only C API for Perl interpreter, SVAPI tries to fill that gap.

We assume that all SVAPI belongs to xs namespace so we omit xs:: name resolution, i.e.

using namespace xs;

CLASS HIERARCHY & Overview

The type hierarhcy reflects C-type hirerachy defined by Perl. The most generic class is XS::Framework::Manual::SVAPI::Sv, which owns underlying Perl SV*. The direct descedant classes are XS::Framework::Manual::SVAPI::Sub (callable Perl subroutine), XS::Framework::Manual::SVAPI::Array, XS::Framework::Manual::SVAPI::Hash, XS::Framework::Manual::SVAPI::Object and XS::Framework::Manual::SVAPI::Scalar. The XS::Framework::Manual::SVAPI::List is defined as descendant of XS::Framework::Manual::SVAPI::Array; the XS::Framework::Manual::SVAPI::Stash (Perl package names resolver, symbol table) is XS::Framework::Manual::SVAPI::Hash's child.

The XS::Framework::Manual::SVAPI::Scalar is artificial type defined by XS::Framework, which represents a value which can be placed in scalar context, as opposite to all other types above.

The XS::Framework::Manual::SVAPI::Ref is child class of Scalar, which is able to point to any other Perl value (array, hash, object, glob, simple scalar or other reference).

The XS::Framework::Manual::SVAPI::Simple object is intendent to present Perl primitive values, i.e. string or numbers.

XS::Framework::Manual::SVAPI::Glob object holds a GLOB containing a scalar, an array, a hash etc. and usually can be found in Stash'es.

XS::Framework::Manual::SVAPI::Io object holds IO.

XS::Framework::Manual::SVAPI::Scope contains scope utils.

The rule of thumb for wrappers creation (i.e. constructor, assignment): if the incorrect underlying SV* is supplied (e.g. SV* holding a number is supplied for Object), then exception is thrown. If NULL / nullptr is provided, then a wrapper will be empty (no exception is thrown); if an SV* with undef a wrapper also will be empty, unless undef is acceptable value (e.g. for Scalar).

create vs constructor difference: the create methods for appropriate type create underlying SV* in Perl itself and return wrapper for it. The constructors just create an wrapper around already exsisting Perl <SV*>.

See also

XS::Framework::Manual::SVAPI::Sv

XS::Framework::Manual::SVAPI::Sub

XS::Framework::Manual::SVAPI::Array

XS::Framework::Manual::SVAPI::Glob

XS::Framework::Manual::SVAPI::Hash

XS::Framework::Manual::SVAPI::List

XS::Framework::Manual::SVAPI::Object

XS::Framework::Manual::SVAPI::Ref

XS::Framework::Manual::SVAPI::Scalar

XS::Framework::Manual::SVAPI::Simple

XS::Framework::Manual::SVAPI::Stash

XS::Framework::Manual::SVAPI::Io

XS::Framework::Manual::SVAPI::Scope

MISCELLANEOUS

The XS::Framework supports threaded perl .

It is possible to use custom C++ XS::Framework::Manual::SVAPI::exceptions as well as custom exception handler to pass them through into the Perl.

If you need custom C++ hook on Perl destruction, please refer XS::Framework::Manual::SVAPI::perl_destroy.