NAME 
src/extend.c - Parrot extension interface
DESCRIPTION
These are the functions that parrot extensions (i.e. parrot subroutines written in C, or some other compiled language, rather than in parrot bytecode) may access.
There is a deliberate distancing from the internals here. Don't go peeking inside -- you've as much access as bytecode does, but no more, so we can provide backwards compatibility for as long as we possibly can.
Functions
Parrot_STRING Parrot_PMC_get_string(Parrot_INTERP interp, Parrot_PMC pmc)- Return an opaque string that represents the string contained in the PMC.
Parrot_STRING Parrot_PMC_get_string_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return the integer keyed string value of the passed-in PMC
void *Parrot_PMC_get_pointer(Parrot_INTERP interp, Parrot_PMC pmc)- Returns a pointer. Used for PMCs that hold pointers to arbitrary data PMC.
void *Parrot_PMC_get_pointer_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return the keyed, signed integer value of the value in the PMC.
Parrot_PMC Parrot_PMC_get_pmc_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return the integer keyed PMC value of the passed-in PMC
Parrot_Int Parrot_PMC_get_intval(Parrot_INTERP interp, Parrot_PMC pmc)- Return the signed integer value of the value in the PMC.
Parrot_Int Parrot_PMC_get_intval_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return the keyed, signed integer value of the value in the PMC.
Parrot_Float Parrot_PMC_get_numval(Parrot_INTERP interp, Parrot_PMC pmc)- Return the floating-point value of the PMC.
Parrot_Float Parrot_PMC_get_numval_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return the keyed, signed integer value of the value in the PMC.
char *Parrot_PMC_get_cstring_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key)- Return a null-terminated string that represents the string value of the PMC.
char *Parrot_PMC_get_cstring(Parrot_INTERP interp, Parrot_PMC pmc)- Return a null-terminated string that represents the string value of the PMC.
char *Parrot_PMC_get_cstringn(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int *length)- Return a null-terminated string for the PMC, along with the length.
- Yes, right now this is a bit of a cheat. It needs fixing, but without disturbing the interface.
char *Parrot_PMC_get_cstringn_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int *length, Parrot_Int key)- Return a null-terminated string for the PMC, along with the length.
- Yes, right now this is a bit of a cheat. It needs fixing, but without disturbing the interface.
void Parrot_PMC_set_string(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_STRING value)- Assign the passed-in Parrot string to the passed-in PMC.
void Parrot_PMC_set_string_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, Parrot_STRING value)- Assign the passed-in Parrot string to the passed-in PMC.
void Parrot_PMC_set_pointer(Parrot_INTERP interp, Parrot_PMC pmc, void *value)- Assign the passed-in pointer to the passed-in PMC.
void Parrot_PMC_set_pmc_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, Parrot_PMC value)- Assign the passed-in pmc to the passed-in slot of the passed-in PMC.
void Parrot_PMC_set_pointer_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, void *value)- Assign the passed-in pointer to the passed-in PMC.
void Parrot_PMC_set_intval(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int value)- Assign the passed-in Parrot integer to the passed-in PMC.
void Parrot_PMC_set_intval_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, Parrot_Int value)- Assign the passed-in Parrot integer to the passed-in PMC.
void Parrot_PMC_set_numval(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Float value)- Assign the passed-in Parrot number to the passed-in PMC.
void Parrot_PMC_set_numval_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, Parrot_Float value)- Assign the passed-in Parrot number to the passed-in PMC.
void Parrot_PMC_set_cstring(Parrot_INTERP interp, Parrot_PMC pmc, const char *value)- Assign the passed-in null-terminated C string to the passed-in PMC.
void Parrot_PMC_set_cstring_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, const char *value)- Assign the passed-in null-terminated C string to the passed-in PMC.
void Parrot_PMC_set_cstringn(Parrot_INTERP interp, Parrot_PMC pmc, const char *value, Parrot_Int length)- Assign the passed-in length-noted string to the passed-in PMC.
void Parrot_PMC_set_cstringn_intkey(Parrot_INTERP interp, Parrot_PMC pmc, Parrot_Int key, const char *value, Parrot_Int length)- Assign the passed-in length-noted string to the passed-in PMC.
Parrot_PMC Parrot_PMC_new(Parrot_INTERP interp, Parrot_Int type)- Create and return a new PMC.
Parrot_Int Parrot_PMC_typenum(Parrot_INTERP interp, const char *class)- Returns the internal identifier that represents the named class.
Parrot_PMC Parrot_PMC_null()- Returns the special
NULLPMC. void Parrot_free_cstring(char *string)- Deallocate a C string that the interpreter has handed to you.
void *Parrot_call_sub(Parrot_INTERP interpreter, Parrot_PMC sub, const char *signature, ...)- Call a parrot subroutine the given function signature.
The first char in
signaturedenotes the return value. Next chars are arguments. - The return value of this function can be void or a pointer type.
- Signature chars are:
Parrot_IntParrot_call_sub_ret_int(Parrot_INTERP interpreter, Parrot_PMC sub, const char *signature, ...)>Parrot_FloatParrot_call_sub_ret_float(Parrot_INTERP interpreter, Parrot_PMC sub, const char *signature, ...)>- Like above, with Parrot_Int or Parrot_Float return result.
void *Parrot_call_method(Parrot_INTERP interp, Parrot_PMC sub, Parrot_PMC object, Parrot_STRING method, const char *signature, ...)Parrot_Int Parrot_call_method_ret_int(Parrot_INTERP interp, Parrot_PMC sub, Parrot_PMC object, Parrot_STRING method, const char *signature, ...)Parrot_Float Parrot_call_method_ret_float(Parrot_INTERP interp, Parrot_PMC sub, Parrot_PMC object, Parrot_STRING method, const char *signature, ...)- Call a parrot method for the given object.
Parrot_Int Parrot_get_intreg(Parrot_INTERP interpreter, Parrot_Int regnum)- Return the value of an integer register.
Parrot_Float Parrot_get_numreg(Parrot_INTERP interpreter, Parrot_Int regnum)- Return the value of a numeric register.
Parrot_STRING Parrot_get_strreg(Parrot_INTERP interpreter, Parrot_Int regnum)- Return the value of a string register.
Parrot_PMC Parrot_get_pmcreg(Parrot_INTERP interpreter, Parrot_Int regnum)- Return the value of a PMC register.
void Parrot_set_intreg(Parrot_INTERP interpreter, Parrot_Int regnum, Parrot_Int value)- Set the value of an I register.
void Parrot_set_numreg(Parrot_INTERP interpreter, Parrot_Int regnum, Parrot_Float value)- Set the value of an N register.
void Parrot_set_strreg(Parrot_INTERP interpreter, Parrot_Int regnum, Parrot_STRING value)- Set the value of an S register.
void Parrot_set_pmcreg(Parrot_INTERP interpreter, Parrot_Int regnum, Parrot_PMC value)- Set the value of a P register.
Parrot_STRING Parrot_new_string(Parrot_INTERP interpreter, char *buffer, int length, const char *const encoding_name, Parrot_Int flags)- Create a new Parrot string from a passed-in buffer. Pass in a 0 for flags for right now.
- A copy of the buffer is made.
Parrot_Const_Encoding Parrot_find_encoding(Parrot_INTERP interpreter, char *encoding_name)- Find the magic token for an encoding, by name.
Parrot_Language Parrot_find_language(Parrot_INTERP interpreter, char *language)- Find the magic language token for a language, by language name.
void Parrot_register_pmc(Parrot_INTERP interpreter, Parrot_PMC pmc)- Add a reference of the PMC to the interpreters DOD registry. This prevents PMCs only known to extension from getting destroyed during DOD runs.
void Parrot_unregister_pmc(Parrot_INTERP interpreter, Parrot_PMC pmc)- Remove a reference of the PMC from the interpreters DOD registry If the reference count reaches zero, the PMC will be destroyed during the next DOD run.
void Parrot_pmc_set_vtable(Parrot_INTERP interpreter, Parrot_PMC pmc, Parrot_VTABLE vtable)- Replaces the vtable of the PMC.
Parrot_VTABLE Parrot_get_vtable(Parrot_INTERP interpreter, Parrot_Int id)- Returns the vtable corresponding to the given PMC ID.
v ... void return
I ... Parrot_Int
N ... Parrot_Float
S ... Parrot_STRING
P ... Parrot_PMC
SEE ALSO
See include/parrot/extend.h and docs/pdds/pdd11_extending.pod.
HISTORY
Initial version by Dan Sugalski.
