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 ^

int Parrot_vfprintf

Writes a C string format with a varargs list to a PIO.

int Parrot_fprintf

Writes a C string format with varargs to a PIO.

int Parrot_printf

Writes a C string format with varargs to stdout.

int Parrot_eprintf

Writes a C string format with varargs to stderr.

*/

PARROT_API int Parrot_vfprintf(PARROT_INTERP, ARGIN(Parrot_PMC pio), ARGIN(const char *s), va_list args) { STRING * str; INTVAL retval;

    PARROT_CALLIN_START(interp);
    str = Parrot_vsprintf_c(interp, s, args);
    retval = PIO_putps(interp, pio, str);
    PARROT_CALLIN_END(interp);

    return retval;
}
PARROT_API int Parrot_fprintf(PARROT_INTERP, ARGIN(Parrot_PMC pio), ARGIN(const char *s), ...) { va_list args; INTVAL retval;

    va_start(args, s);
    retval = Parrot_vfprintf(interp, pio, s, args);
    va_end(args);

    return retval;
}
PARROT_API int Parrot_printf(NULLOK_INTERP, ARGIN(const char *s), ...) { va_list args; INTVAL retval; va_start(args, s);

    if (interp) {
        retval = Parrot_vfprintf(interp, PIO_STDOUT(interp), s, args);
    }
    else {
        /* Be nice about this...
         **   XXX BD Should this use the default PIO_STDOUT or something?
         */
        retval = vfprintf(stdout, s, args);
    }
    va_end(args);

    return retval;
}
PARROT_API int Parrot_eprintf(NULLOK_INTERP, ARGIN(const char *s), ...) { va_list args; INTVAL retval;

    va_start(args, s);

    if (interp) {
        retval = Parrot_vfprintf(interp, PIO_STDERR(interp), s, args);
    }
    else {
        /* Be nice about this...
         **   XXX BD Should this use the default PIO_STDOUT or something?
         */
        retval=vfprintf(stderr, s, args);
    }

    va_end(args);

    return retval;
}
/*

Parrot_String Parrot_PMC_get_string_intkey

Return the integer keyed string value of the passed-in PMC

void *Parrot_PMC_get_pointer_intkey

Return a pointer to the PMC indicated by an integer key.

Parrot_PMC Parrot_PMC_get_pmc_intkey

Return the integer keyed PMC value of the passed-in PMC

Parrot_Int Parrot_PMC_get_intval

Return the signed integer value of the value in the PMC.

Parrot_Int Parrot_PMC_get_intval_intkey

Return the keyed, signed integer value of the value in the PMC.

Parrot_Int Parrot_PMC_get_intval_pmckey

Return the keyed, signed integer value of the value in the PMC.

Parrot_Float Parrot_PMC_get_numval

Return the floating-point value of the PMC.

Parrot_Float Parrot_PMC_get_numval_intkey

Return the keyed, signed integer value of the value in the PMC.

char *Parrot_PMC_get_cstring_intkey

Return a null-terminated string that represents the string value of the PMC.

Note that you must free this string with string_cstring_free()!

char *Parrot_PMC_get_cstring

Return a null-terminated string that represents the string value of the PMC.

Note that you must free this string with string_cstring_free()!

char *Parrot_PMC_get_cstringn

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.

Note that you must free the string with string_cstring_free().

char *Parrot_PMC_get_cstringn_intkey

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.

Note that you must free this string with string_cstring_free().

void Parrot_PMC_set_string

Assign the passed-in Parrot string to the passed-in PMC.

void Parrot_PMC_set_string_intkey

Assign the passed-in Parrot string to the passed-in PMC.

void Parrot_PMC_set_pmc_intkey

Assign the passed-in pmc to the passed-in slot of the passed-in PMC.

void Parrot_PMC_set_pmc_pmckey

Assign the passed-in pmc to the passed-in slot of the passed-in PMC.

void Parrot_PMC_set_pointer_intkey

Assign the passed-in pointer to the passed-in PMC.

void Parrot_PMC_set_intval

Assign the passed-in Parrot integer to the passed-in PMC.

void Parrot_PMC_set_intval_intkey

Assign the passed-in Parrot integer to the passed-in PMC.

void Parrot_PMC_set_numval

Assign the passed-in Parrot number to the passed-in PMC.

void Parrot_PMC_set_numval_intkey

Assign the passed-in Parrot number to the passed-in PMC.

void Parrot_PMC_set_cstring

Assign the passed-in null-terminated C string to the passed-in PMC.

void Parrot_PMC_set_cstring_intkey

Assign the passed-in null-terminated C string to the passed-in PMC.

void Parrot_PMC_set_cstringn

Assign the passed-in length-noted string to the passed-in PMC.

void Parrot_PMC_push_intval

Push the passed-in Parrot integer onto the passed in PMC

void Parrot_PMC_push_numval

Push the passed-in Parrot number onto the passed in PMC

void Parrot_PMC_delete_pmckey

Deletes the value associated with the passed-in PMC from the PMC.

void Parrot_PMC_set_cstringn_intkey

Assign the passed-in length-noted string to the passed-in PMC.

Parrot_PMC Parrot_PMC_new

Create and return a new PMC.

Parrot_Int Parrot_PMC_typenum

Returns the internal identifier that represents the named class.

Parrot_PMC Parrot_PMC_null

Returns the special NULL PMC.

void Parrot_free_cstring

Deallocate a C string that the interpreter has handed to you.

void *Parrot_call_sub

Call a parrot subroutine with 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

Like Parrot_call_sub, with Parrot_Int return result.

Parrot_Float Parrot_call_sub_ret_float

Like Parrot_call_sub, with Parrot_Float return result.

void *Parrot_call_method

Call a parrot method for the given object.

Parrot_Int Parrot_call_method_ret_int

Call a parrot method for the given object.

Parrot_Float Parrot_call_method_ret_float

Call a parrot method for the given object.

Parrot_Int Parrot_get_intreg

Return the value of an integer register.

Parrot_Float Parrot_get_numreg

Return the value of a numeric register.

Parrot_String Parrot_get_strreg

Return the value of a string register.

Parrot_PMC Parrot_get_pmcreg

Return the value of a PMC register.

void Parrot_set_intreg

Set the value of an I register.

void Parrot_set_numreg

Set the value of an N register.

void Parrot_set_strreg

Set the value of an S register.

*/

PARROT_API void Parrot_set_strreg(PARROT_INTERP, Parrot_Int regnum, Parrot_String value) { REG_STR(interp, regnum) = value; }

/*

void Parrot_set_pmcreg

Set the value of a P register.

Parrot_String Parrot_new_string

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_Language Parrot_find_language

Find the magic language token for a language, by language name.

void Parrot_register_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

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

Replaces the vtable of the PMC.

Parrot_VTABLE Parrot_get_vtable

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