NAME

Ouroboros - Perl XS macros re-exported as C functions

DESCRIPTION

libouroboros is a library of C functions wrapping XS macros. This package provides pointers to these functions, so Perl programs can have access to internal Perl methods (e.g. SvIV) at run-time. In combination with a JIT- compiler it allows Perl programs to build XS-like subroutines completely at run-time, without the need for a C compiler or a build environment.

Thread context

All wrappers accept thread context as a first argument, as defined by pTHX XS macro, even if pTHX is not part of the wrapped macro definition.

Two exceptions to this are ouroboros_sys_init3 and ouroboros_sys_term, since they are called in embedded Perl scenario at times when Perl interpreter object does not exist.

The stack

libouroboros encapsulates local stack state kept by XS inside the stack object: ouroboros_stack_t type and a number of method functions. Storage can be allocated on caller's stack or in heap, and should be initialized first by calling ouroboros_stack_init().

Minimum storage size for ouroboros_stack_t is available as $Ouroboros::SIZE_OF{ouroboros_stack_t}. Exact layout is intentionally unspecified, user program should treat this type as an opaque object and only use provided methods to manipulate it.

Type sizes

Sizes for most primitive data types used by Perl are available via Config and supplemented by %Ouroboros::SIZE_OF hash.

EXPORTS

Nothing is exported by default.

:all tag exports all methods and constants.

:consts tag exports constants only.

METHODS

Every sub listed here returns a pointer to a C function with a signature as provided.

ouroboros_stack_init_ptr

void ouroboros_stack_init(pTHX_ ouroboros_stack_t*);

Initialize ouroboros_stack_t object. Must be first thing called by a XS-sub. Equivalent to dXSARGS macro automatically inserted by xsubpp into every XS sub.

ouroboros_stack_items_ptr

int ouroboros_stack_items(pTHX_ ouroboros_stack_t*);

Returns number of arguments on Perl stack. Equivalent to items local variable in XS.

ouroboros_stack_prepush_ptr

void ouroboros_stack_prepush(pTHX_ ouroboros_stack_t*);

Perl macro: XSprePUSH

ouroboros_stack_putback_ptr

void ouroboros_stack_putback(pTHX_ ouroboros_stack_t*);

Perl macro: PUTBACK

ouroboros_stack_fetch_ptr

SV* ouroboros_stack_fetch(pTHX_ ouroboros_stack_t*, SSize_t);

Read a value from the stack. Equivalent of:

return ST(a);

Perl macro: ST(n)

ouroboros_stack_store_ptr

void ouroboros_stack_store(pTHX_ ouroboros_stack_t*, SSize_t, SV*);

Store a value on the stack. Equivalent of:

ST(a) = sv;

Perl macro: ST

ouroboros_stack_extend_ptr

void ouroboros_stack_extend(pTHX_ ouroboros_stack_t*, SSize_t);

Perl macro: EXTEND

ouroboros_stack_pushmark_ptr

void ouroboros_stack_pushmark(pTHX_ ouroboros_stack_t*);

Perl macro: PUSHMARK

ouroboros_stack_spagain_ptr

void ouroboros_stack_spagain(pTHX_ ouroboros_stack_t*);

Perl macro: SPAGAIN

ouroboros_stack_xpush_sv_ptr

void ouroboros_stack_xpush_sv(pTHX_ ouroboros_stack_t*, SV*);

Perl macro: XPUSHs

ouroboros_stack_xpush_sv_mortal_ptr

void ouroboros_stack_xpush_sv_mortal(pTHX_ ouroboros_stack_t*, SV*);

Perl macro: mXPUSHs

ouroboros_stack_xpush_iv_ptr

void ouroboros_stack_xpush_iv(pTHX_ ouroboros_stack_t*, IV);

Perl macro: mXPUSHi

ouroboros_stack_xpush_uv_ptr

void ouroboros_stack_xpush_uv(pTHX_ ouroboros_stack_t*, UV);

Perl macro: mXPUSHu

ouroboros_stack_xpush_nv_ptr

void ouroboros_stack_xpush_nv(pTHX_ ouroboros_stack_t*, NV);

Perl macro: mXPUSHn

ouroboros_stack_xpush_pv_ptr

void ouroboros_stack_xpush_pv(pTHX_ ouroboros_stack_t*, const char*, STRLEN);

Perl macro: mXPUSHp

ouroboros_stack_push_sv_ptr

void ouroboros_stack_push_sv(pTHX_ ouroboros_stack_t*, SV*);

Perl macro: PUSHs

ouroboros_stack_push_sv_mortal_ptr

void ouroboros_stack_push_sv_mortal(pTHX_ ouroboros_stack_t*, SV*);

Perl macro: mPUSHs

ouroboros_stack_push_iv_ptr

void ouroboros_stack_push_iv(pTHX_ ouroboros_stack_t*, IV);

Perl macro: mPUSHi

ouroboros_stack_push_uv_ptr

void ouroboros_stack_push_uv(pTHX_ ouroboros_stack_t*, UV);

Perl macro: mPUSHu

ouroboros_stack_push_nv_ptr

void ouroboros_stack_push_nv(pTHX_ ouroboros_stack_t*, NV);

Perl macro: mPUSHn

ouroboros_stack_push_pv_ptr

void ouroboros_stack_push_pv(pTHX_ ouroboros_stack_t*, const char*, STRLEN);

Perl macro: mPUSHp

ouroboros_sv_iv_ptr

IV ouroboros_sv_iv(pTHX_ SV*);

Perl macro: SvIV

ouroboros_sv_uv_ptr

UV ouroboros_sv_uv(pTHX_ SV*);

Perl macro: SvUV

ouroboros_sv_nv_ptr

NV ouroboros_sv_nv(pTHX_ SV*);

Perl macro: SvNV

ouroboros_sv_pv_ptr

const char* ouroboros_sv_pv(pTHX_ SV*, STRLEN*);

Perl macro: SvPV

ouroboros_sv_pv_nolen_ptr

const char* ouroboros_sv_pv_nolen(pTHX_ SV*);

Perl macro: SvPV_nolen

ouroboros_sv_rok_ptr

U32 ouroboros_sv_rok(pTHX_ SV*);

Perl macro: SvROK

ouroboros_sv_rv_ptr

SV* ouroboros_sv_rv(pTHX_ SV*);

Perl macro: SvRV

ouroboros_sv_type_ptr

IV ouroboros_sv_type(pTHX_ SV*);

Perl macro: SvTYPE

ouroboros_gv_sv_ptr

SV* ouroboros_gv_sv(pTHX_ GV*);

Perl macro: GvSV

ouroboros_gv_av_ptr

AV* ouroboros_gv_av(pTHX_ GV*);

Perl macro: GvAV

ouroboros_gv_hv_ptr

HV* ouroboros_gv_hv(pTHX_ GV*);

Perl macro: GvHV

ouroboros_gv_cv_ptr

CV* ouroboros_gv_cv(pTHX_ CV*);

Perl macro: GvCV

ouroboros_sv_refcnt_ptr

U32 ouroboros_sv_refcnt(pTHX_ SV*);

Perl macro: SvREFCNT

ouroboros_sv_refcnt_inc_ptr

SV* ouroboros_sv_refcnt_inc(pTHX_ SV*);

Perl macro: SvREFCNT_inc_simple

ouroboros_sv_refcnt_inc_nn_ptr

SV* ouroboros_sv_refcnt_inc_nn(pTHX_ SV*);

Perl macro: SvREFCNT_inc_simple_NN

ouroboros_sv_refcnt_inc_void_ptr

void ouroboros_sv_refcnt_inc_void(pTHX_ SV*);

Perl macro: SvREFCNT_inc_simple_void

ouroboros_sv_refcnt_inc_void_nn_ptr

void ouroboros_sv_refcnt_inc_void_nn(pTHX_ SV*);

Perl macro: SvREFCNT_inc_simple_void_NN

ouroboros_sv_refcnt_dec_ptr

void ouroboros_sv_refcnt_dec(pTHX_ SV*);

Perl macro: SvREFCNT_dec

ouroboros_sv_refcnt_dec_nn_ptr

void ouroboros_sv_refcnt_dec_nn(pTHX_ SV*);

Perl macro: SvREFCNT_dec_NN

ouroboros_enter_ptr

void ouroboros_enter(pTHX);

Perl macro: ENTER

ouroboros_leave_ptr

void ouroboros_leave(pTHX);

Perl macro: LEAVE

ouroboros_savetmps_ptr

void ouroboros_savetmps(pTHX);

Perl macro: SAVETMPS

ouroboros_freetmps_ptr

void ouroboros_freetmps(pTHX);

Perl macro: FREETMPS

ouroboros_sys_init3_ptr

void ouroboros_sys_init3(int*, char***, char***);

Perl macro: PERL_SYS_INIT3

ouroboros_sys_term_ptr

void ouroboros_sys_term();

Perl macro: PERL_SYS_TERM

CONSTANTS

This package also provides a number of consants from XS API. Some constants may not be available, depending on the Perl version used.

@Ouroboros::CONSTS contains names of all constants provided by this package.

SVt_NULL

SVt_IV

SVt_NV

SVt_PV

SVt_PVIV

SVt_PVNV

SVt_PVMG

SVt_REGEXP

SVt_PVGV

SVt_PVLV

SVt_PVAV

SVt_PVHV

SVt_PVCV

SVt_PVFM

SVt_PVIO

SVt_LAST

SV_IMMEDIATE_UNREF

SV_GMAGIC

SV_COW_DROP_PV

SV_UTF8_NO_ENCODING

SV_NOSTEAL

SV_CONST_RETURN

SV_MUTABLE_RETURN

SV_SMAGIC

SV_HAS_TRAILING_NUL

SV_COW_SHARED_HASH_KEYS

SV_COW_OTHER_PVS

SV_UNDEF_RETURNS_NULL

SV_FORCE_UTF8_UPGRADE

SV_SKIP_OVERLOAD

SV_CATBYTES

SV_CATUTF8

SV_CONST_TIESCALAR

SV_CONST_TIEARRAY

SV_CONST_TIEHASH

SV_CONST_TIEHANDLE

SV_CONST_FETCH

SV_CONST_FETCHSIZE

SV_CONST_STORE

SV_CONST_STORESIZE

SV_CONST_EXISTS

SV_CONST_PUSH

SV_CONST_POP

SV_CONST_SHIFT

SV_CONST_UNSHIFT

SV_CONST_SPLICE

SV_CONST_EXTEND

SV_CONST_FIRSTKEY

SV_CONST_NEXTKEY

SV_CONST_SCALAR

SV_CONST_OPEN

SV_CONST_WRITE

SV_CONST_PRINT

SV_CONST_PRINTF

SV_CONST_READ

SV_CONST_READLINE

SV_CONST_GETC

SV_CONST_SEEK

SV_CONST_TELL

SV_CONST_EOF

SV_CONST_BINMODE

SV_CONST_FILENO

SV_CONST_CLOSE

SV_CONST_DELETE

SV_CONST_CLEAR

SV_CONST_UNTIE

SV_CONST_DESTROY

THE REST

Most of the XS API consists of normal functions and their addresses can be discovered via DynaLoader at run-time with little effort. See "Internal Functions" in perlguts for more information.

SEE MORE

Perl extensive XS documentation: perlxs, perlapi, perlguts.

JIT-compiler libraries for Perl: LibJIT, GCCJIT.

AUTHOR

Vickenty Fesunov, <cpan-ouroboros@setattr.net>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Vickenty Fesunov.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm Ouroboros

perl -MCPAN -e shell
install Ouroboros