<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Parrot - [DRAFT] PDD 11: Extending</title>
<link rel="stylesheet" type="text/css"
href="../../../../resources/parrot.css"
media="all">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div id="wrapper">
<div id="header">
<a href="http://www.parrot.org">
<img border=0 src="../../../../resources/parrot_logo.png" id="logo" alt="parrot">
</a>
</div> <!-- "header" -->
<div id="divider"></div>
<div id="mainbody">
<div id="breadcrumb">
<a href="../../../../html/index.html">Home</a> » <a href="../../../../html/pdds.html">Parrot Design Documents (PDDs)</a> » [DRAFT] PDD 11: Extending
</div>
<h1><a name="[DRAFT]_PDD_11:_Extending"
>[DRAFT] PDD 11: Extending</a></h1>
<h2><a name="Abstract"
>Abstract</a></h2>
<p>The extension API for Parrot is a simple,
somewhat abstract,
interface to Parrot for code written in C or other compiled languages.
It provides about the same level of access to Parrot that bytecode programs have.</p>
<h2><a name="Description"
>Description</a></h2>
<p>The API presents to C programs roughly the same interface presented to bytecode programs--that is,
a C extension can see everything that a bytecode program can see,
including Parrot's base architecture,
registers,
stacks,
and whatnot.
This view isn't required,
however,
and often extension code won't need or want to know what Parrot's internal structures look like.
For this reason the functions in the extension API are divided into two broad groups,
one that has no particular knowledge of the internals and one that does.</p>
<p>The stability of the two API groups is guaranteed separately.
Group 1,
the internals unaware group,
should be good basically forever.
Group 2,
the internals aware group,
is only guaranteed for the lifetime of the current architecture.
(It's likely that both groups will last equally long; however,
the Group 1 interface could reasonably be emulated on a different engine,
while the Group 2 interface is more closely tied to Parrot).</p>
<p><b>Note:</b> The extension API has not yet been completely specified.
New functions may be added,
and those described below may change or be removed.
You have been warned...</p>
<h2><a name="Implementation"
>Implementation</a></h2>
<h3><a name="API_-_Group_1:_Internals-unaware_functions"
>API - Group 1: Internals-unaware functions</a></h3>
<p>These functions are the ones that are largely unaware of the structure and architecture of Parrot.
They deal mainly in data as abstract entities,
and Parrot itself as a black box that,
at best,
can make subroutine or method calls.
This is sufficient for many extensions which act as black box processing units and in turn treat Parrot itself as a black box.</p>
<h4><a name="PMC_access_functions"
>PMC access functions</a></h4>
<p>The following functions are for storing and retrieving data inside PMCs.
Note that use of the _keyed functions with non-aggregate PMCs will generally just result in Parrot throwing an exception.</p>
<dl>
<dt><a name="Parrot_PMC_get_string(interp,_pmc)"
><b><code>Parrot_PMC_get_string(interp, pmc)</b></code></a></dt>
Returns a Parrot_String that represents the string value of the PMC.
<dt><a name="Parrot_PMC_get_string_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_string_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_get_string</code>.
Returns a Parrot_String representing the string value of whatever is stored at the element of the PMC indexed by <code>key</code>.
<dt><a name="Parrot_PMC_get_pointer(interp,_pmc)"
><b><code>Parrot_PMC_get_pointer(interp, pmc)</b></code></a></dt>
Returns a pointer to some item of data.
The details of what the pointer points to depend on the particular PMC.
This function is useful for dealing with PMCs that hold pointers to arbitrary data.
<dt><a name="Parrot_PMC_get_pointer_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_pointer_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
A keyed version of <code>Parrot_PMC_get_pointer</code>.
Returns the pointer value of whatever is stored at the element of the PMC indexed by <code>key</code>.
<dt><a name="Parrot_PMC_get_intval(interp,_pmc)"
><b><code>Parrot_PMC_get_intval(interp, pmc)</b></code></a></dt>
Returns the integer value of the PMC.
<dt><a name="Parrot_PMC_get_intval_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_intval_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
A keyed version of <code>Parrot_PMC_get_intval</code>.
Returns the integer value of whatever is stored at the element of the PMC indexed by <code>key</code>.
<dt><a name="Parrot_PMC_get_numval(interp,_pmc)"
><b><code>Parrot_PMC_get_numval(interp, pmc)</b></code></a></dt>
Returns the numeric value of the PMC.
<dt><a name="Parrot_PMC_get_numval_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_numval_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
A keyed version of <code>Parrot_PMC_get_numval</code>.
Returns the numeric value of whatever is stored at the element of the PMC indexed by <code>key</code>.
<dt><a name="Parrot_PMC_get_cstring(interp,_pmc)"
><b><code>Parrot_PMC_get_cstring(interp, pmc)</b></code></a></dt>
Returns a C-string (char *) that represents the string value of the PMC.
The memory the char * points to is a copy of the original value,
and changing it will not change the original in any way.This memory will <i>not</i> be reclaimed by garbage collection,
nor may it be returned to the system with <code>free</code>.
It must be returned with <code>Parrot_free_cstring</code>.
<dt><a name="Parrot_PMC_get_cstring_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_cstring_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
A keyed version of <code>Parrot_PMC_get_cstring</code>.
Returns a C-string representing the string value of whatever is stored at the element of the PMC indexed by <code>key</code>.
<dt><a name="Parrot_PMC_get_cstringn(interp,_pmc,_&len)"
><b><code>Parrot_PMC_get_cstringn(interp, pmc, &len)</b></code></a></dt>
Returns a C-string (char *) that represents the string value of the PMC.
The memory the char * points to is a copy of the original value,
and changing it will not change the original in any way.
The <code>len</code> parameter is the address of an integer that will get the length of the string as Parrot knows it.This memory will <i>not</i> be reclaimed by garbage collection,
nor may it be returned to the system with <code>free</code>.
It must be returned with <code>Parrot_free_cstring</code>.
<dt><a name="Parrot_PMC_get_cstringn_intkey(interp,_pmc,_&len,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_cstringn_intkey(interp, pmc, &len, Parrot_Int key)</b></code></a></dt>
A keyed version of <code>Parrot_PMC_get_cstringn</code>.
Returns a C-string representing the string value of whatever is stored at the element of the PMC indexed by <code>key</code>.
Stores the length of the string in <code>len</code>.
<dt><a name="Parrot_PMC_get_pmc_intkey(interp,_pmc,_Parrot_Int_key)"
><b><code>Parrot_PMC_get_pmc_intkey(interp, pmc, Parrot_Int key)</b></code></a></dt>
Returns the PMC stored at the element of the passed-in PMC that is indexed by <code>key</code>.
<dt><a name="Parrot_PMC_set_string(interp,_pmc,_Parrot_String_value)"
><b><code>Parrot_PMC_set_string(interp, pmc, Parrot_String value)</b></code></a></dt>
Assign the passed-in Parrot_String to the passed-in PMC.
<dt><a name="Parrot_PMC_set_string_intkey(interp,_pmc,_Parrot_String_value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_string_intkey(interp, pmc, Parrot_String value, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_string</code>.
Assigns <code>value</code> to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_pointer(interp,_pmc,_void_*value)"
><b><code>Parrot_PMC_set_pointer(interp, pmc, void *value)</b></code></a></dt>
Assign the passed-in pointer to the passed-in PMC.
<dt><a name="Parrot_PMC_set_pointer_intkey(interp,_pmc,_void_*value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_pointer_intkey(interp, pmc, void *value, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_pointer</code>.
Assigns <code>value</code> to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_pmc_intkey(interp,_pmc,_Parrot_PMC_value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value, Parrot_Int key)</b></code></a></dt>
Assigns <code>value</code> to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_intval(interp,_pmc,_Parrot_Int_value)"
><b><code>Parrot_PMC_set_intval(interp, pmc, Parrot_Int value)</b></code></a></dt>
Assign the passed-in Parrot integer to the passed-in PMC.
<dt><a name="Parrot_PMC_set_intval_intkey(interp,_pmc,_Parrot_Int_value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_intval_intkey(interp, pmc, Parrot_Int value, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_intval</code>.
Assigns <code>value</code> to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_numval(interp,_pmc,_Parrot_Float_value)"
><b><code>Parrot_PMC_set_numval(interp, pmc, Parrot_Float value)</b></code></a></dt>
Assign the passed-in Parrot number to the passed-in PMC.
<dt><a name="Parrot_PMC_set_numval_intkey(interp,_pmc,_Parrot_Float_value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_numval_intkey(interp, pmc, Parrot_Float value, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_numval</code>.
Assigns <code>value</code> to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_cstring(interp,_pmc,_const_char_*value)"
><b><code>Parrot_PMC_set_cstring(interp, pmc, const char *value)</b></code></a></dt>
Convert the passed-in null-terminated C string to a Parrot_String and assign it to the passed-in PMC.
<dt><a name="Parrot_PMC_set_cstring_intkey(interp,_pmc,_const_char_*value,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_cstring_intkey(interp, pmc, const char *value, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_cstring</code>.
Converts <code>value</code> to a Parrot_String and assigns it to the PMC stored at element <key> of the passed-in PMC.
<dt><a name="Parrot_PMC_set_cstringn(interp,_pmc,_const_char_*value,_Parrot_Int_length)"
><b><code>Parrot_PMC_set_cstringn(interp, pmc, const char *value, Parrot_Int length)</b></code></a></dt>
Convert the passed-in null-terminated C string to a Parrot_String of length <code>length</code> and assign it to the passed-in PMC.
If <code>value</code> is longer than <code>length</code>,
then only the first <code>length</code> characters will be converted.
If <code>value</code> is shorter than <code>length</code>,
then the extra characters in the Parrot_String should be assumed to contain garbage.
<dt><a name="Parrot_PMC_set_cstringn_intkey(interp,_pmc,_const_char_*value,_Parrot_int_length,_Parrot_Int_key)"
><b><code>Parrot_PMC_set_cstringn_intkey(interp, pmc, const char *value, Parrot_int length, Parrot_Int key)</b></code></a></dt>
Keyed version of <code>Parrot_PMC_set_cstringn</code>.
Converts the first <code>length</code> characters of <code>value</code> to a Parrot_String and assigns the resulting string to the PMC stored at element <key> of the passed-in PMC.</dl>
<h4><a name="Creation_and_destruction"
>Creation and destruction</a></h4>
<p>Functions used to create and destroy PMCs,
Parrot_Strings,
etc.</p>
<dl>
<dt><a name="Parrot_PMC_new(interp,_Parrot_Int_typenum)"
><b><code>Parrot_PMC_new(interp, Parrot_Int typenum)</b></code></a></dt>
Creates and returns a new PMC.
<code>typenum</code> is an integer identifier that specifies the type of PMC required.
The <code>typenum</code> corresponding to a particular PMC class name can be found using <code>Parrot_PMC_typenum</code>.
<dt><a name="Parrot_PMC_typenum(interp,_const_char*_class)"
><b><code>Parrot_PMC_typenum(interp, const char* class)</b></code></a></dt>
Returns the internal integer identifier corresponding to a PMC with class name <code>class</code>.
<dt><a name="Parrot_PMC_null()"
><b><code>Parrot_PMC_null()</b></code></a></dt>
Returns the special <code>NULL</code> PMC.
<dt><a
><b><code>Parrot_new_string(interp, char *buffer, int length, Parrot_Encoding encoding, Parrot_CharType charset, Parrot_Language language, Parrot_Int flags)</b></code></a></dt>
Create a new Parrot string from a passed-in buffer.
If the <code>encoding</code>,
<code>charset</code>,
or <code>language</code> are unspecified (i.e.
if you pass in 0),
then the defaults are used.
Otherwise,
the functions <code>Parrot_find_encoding</code>,
<code>Parrot_find_chartype</code> and <code>Parrot_find_language</code> (all described below) can be used to find the appropriate values for a particular choice of encoding,
chartype or language.Flag values are currently undocumented.Note that a copy of the buffer is made.
<dt><a name="Parrot_find_encoding(interp,_char_*encoding_name)"
><b><code>Parrot_find_encoding(interp, char *encoding_name)</b></code></a></dt>
Find the magic token for an encoding,
by name.
<dt><a name="Parrot_find_chartype(interp,_char_*chartype)"
><b><code>Parrot_find_chartype(interp, char *chartype)</b></code></a></dt>
Find the magic token for a chartype,
by name.
<dt><a name="Parrot_find_language(interp,_char_*language)"
><b><code>Parrot_find_language(interp, char *language)</b></code></a></dt>
Find the magic token for a language,
by language name.
<dt><a name="Parrot_free_cstring(char*_string)"
><b><code>Parrot_free_cstring(char* string)</b></code></a></dt>
Deallocates a C string that the interpreter has handed to you.
This function must be used to free strings produced by <code>Parrot_PMC_get_cstring</code> and <code>Parrot_PMC_get_cstringn</code>,
as these will not be reclaimed by the garbage collector.
It should not be used to deallocate strings that do not come from Parrot.
<dt><a name="Parrot_register_pmc(interp,_pmc)"
><b><code>Parrot_register_pmc(interp, pmc)</b></code></a></dt>
Add a reference to the PMC to the interpreter's GC registry.
This prevents PMCs known only to extensions from getting destroyed during GC runs.
<dt><a name="Parrot_unregister_pmc(interp,_pmc)"
><b><code>Parrot_unregister_pmc(interp, pmc)</b></code></a></dt>
Remove a reference to the PMC from the interpreter's GC registry.
If the reference count reaches zero,
the PMC will be destroyed during the next GC run.</dl>
<h4><a name="Subroutine_and_method_calls"
>Subroutine and method calls</a></h4>
<p>Functions to call Parrot subroutines and methods</p>
<dl>
<dt><a name="Parrot_call_sub(interp,_Parrot_PMC_sub,_Parrot_Int_argcount,_...)"
><b><code>Parrot_call_sub(interp, Parrot_PMC sub, Parrot_Int argcount, ...)</b></code></a></dt>
Calls a Parrot subroutine,
with <code>argcount</code> PMC parameters.
This function sets up Parrot's registers in line with the Parrot calling conventions; see <a href='TODO'>pdd03_calling_conventions.pod</a> for more details.
<dt><a
><b><code>Parrot_call_method(PARROT_INTERP, Parrot_PMC sub, Parrot_PMC obj, Parrot_String method, ARGIN(const char *signature), ...)</b></code></a></dt>
Call the parrot subroutine <code>sub</code> as a method on PMC object <code>obj</code>.
The method should have the name <code>method</code> as a Parrot_string,
and should have a function signature <code>signature</code>.
Any arguments to the method can be passed at the end as a variadic argument list.</dl>
<h3><a name="API_-_Group_2:_Internals_aware"
>API - Group 2: Internals aware</a></h3>
<p>The internals-aware functions are for those extensions that need to query or alter the state of Parrot's internals in some way.</p>
<p>Register access functions</p>
<p>The following functions allow the values stored in Parrot's registers to be accessed.
An attempt to access a non-existent register (e.g.
string register -123) will cause the function to throw an exception (well,
it will once we actually implement some bounds-checking...).
The value stored in an uninitialized register is undefined; it may well be zero (or NULL),
but do not rely on this being the case.</p>
<dl>
<dt><a name="Parrot_get_intreg(interp,_Parrot_Int_regnum)"
><b><code>Parrot_get_intreg(interp, Parrot_Int regnum)</b></code></a></dt>
Return the value of an integer register.
<dt><a name="Parrot_get_numreg(interp,_Parrot_Int_regnum)"
><b><code>Parrot_get_numreg(interp, Parrot_Int regnum)</b></code></a></dt>
Return the value of a numeric register.
<dt><a name="Parrot_get_strreg(interp,_Parrot_Int_regnum)"
><b><code>Parrot_get_strreg(interp, Parrot_Int regnum)</b></code></a></dt>
Return the value of a string register.
<dt><a name="Parrot_get_pmcreg(interp,_Parrot_Int_regnum)"
><b><code>Parrot_get_pmcreg(interp, Parrot_Int regnum)</b></code></a></dt>
Return the value of a PMC register.</dl>
<h2><a name="Attachments"
>Attachments</a></h2>
<p>None.</p>
<h2><a name="Footnotes"
>Footnotes</a></h2>
<p>None.</p>
<h2><a name="References"
>References</a></h2>
<p><em><a href="../../glossary.pod.html">docs/glossary.pod</a></em></p>
<h2><a name="Version"
>Version</a></h2>
<h3><a name="Current"
>Current</a></h3>
<pre> Maintainer:
Class: Internals
PDD Number: 11
Version: 1.0
Status: Developing
Last Modified: February 20, 2004
PDD Format: 1
Language: English</pre>
<h3><a name="History"
>History</a></h3>
<dl>
<dt><a name="Version_1"
>Version 1</a></dt>
None. First version</dl>
<h2><a name="Changes"
>Changes</a></h2>
<dl>
<dt><a name="Version_1.0"
>Version 1.0</a></dt>
None. First version</dl>
</div> <!-- "mainbody" -->
<div id="divider"></div>
<div id="footer">
Copyright © 2002-2009, Parrot Foundation.
</div>
</div> <!-- "wrapper" -->
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
cd14cddf3b3ceaf1193157472227757a
>
files
>
138
