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 NULL PMC.

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 signature denotes the return value. Next chars are arguments.

The return value of this function can be void or a pointer type.

Signature chars are:

    v ... void return
    I ... Parrot_Int
    N ... Parrot_Float
    S ... Parrot_STRING
    P ... Parrot_PMC
Parrot_Int Parrot_call_sub_ret_int(Parrot_INTERP interpreter, Parrot_PMC sub, const char *signature, ...)>

Parrot_Float Parrot_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.

SEE ALSO ^

See include/parrot/extend.h and docs/pdds/pdd11_extending.pod.

HISTORY ^

Initial version by Dan Sugalski.


parrot