src/nci/framebuilder.pod - Parrot Native Call Frame Builder API
Parrot's frame builder is fully pluggable at runtime. That is to say, a new implementation of the frame builder can be installed at any time.
Parrot has 2 slots for the frame builder function - a callback PMC and a user data PMC.
The callback PMC is expected to return a valid
nci_fb_func_t native function from its
The callback for a framebuilder should be registerd in parrot's
iglobals array under
The user data is likewise registered in
nci_fb_func_t functions receive an interpreter,
the registered frame builder user data,
and a signature string.
They are expected to produce a thunk PMC,
and throw an exception or return
NULL on failure.
IMPORTANT: frame builders should not parse the signature string themselves but delegate to
Parrot_nci_parse_signature to ensure consistency between implementations.
produced by the frame builder callback,
are expected to return a valid
nci_thunk_t native function from their
nci_thunk_t functions receive an interpreter,
an NCI PMC,
and a thunk PMC.
They are expected to unpack Parrot's PCC arguments and pass them to the native function pointer in the NCI PMC using the appropriate native function calling conventions and to do the reverse with return values.
The exact details of what operations to perform are specified in the signature supplied to the frame builder when the thunk is created.
Thunks are generated lazily on demand and cached.
only one thunk will exist for a given NCI signature.
The cache is held in
This cache can be operated on directly,
clearing the cache is possible by running the following PIR code:
.include 'iglobals.pasm' .sub 'clear-nci-cache' $P0 = getinterp $P0 = $P0[.IGLOBALS_NCI_FUNCS] $P1 = iter $P0 loop: unless $P1 goto end_loop $S0 = shift $P1 delete $P0[$S0] goto loop end_loop: .end
Note however, that this will not remove thunks from NCI PMCs which have already been invoked (these cache their Thunk PMC locally).
Another use of direct manipulation of the
NCI_FUNCS cache is nci thunk dynext libraries, generated by
nci_thunk_gen, which add additional statically compiled thunks to parrot at runtime.
The frame builder API is currently in a state of flux. Expected improvements are to isolate frame builders further from the signature strings and also to reduce the C-bias in the API.