=head1 TITLE

extend.pod - Parrot extension system

=head1 SYNOPSIS

This is a rough version of the extension documentation for Parrot. It
should be cleaned up and made into a PDD before final release.

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 equivalent access to Parrot that
bytecode programs have.

=head1 DESCRIPTION 

The API presents to C programs about 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.

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).

=head1 API

=head2 Group 1: Internals-unaware

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.

=over 4

=item Parrot_PMC_get_string(interp, pmc)

Returns a Parrot_STRING that represents the string value of the PMC. 

=item Parrot_PMC_get_intval(interp, pmc)

Returns the integer value of the PMC.

=item Parrot_PMC_get_numval(interp, pmc)

Returns the numeric value of the PMC.

=item Parrot_PMC_get_cstring(interp, pmc)

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> be reclaimed by garbage collection, nor may it
be returned to the system with C<free>. It must be returned with
C<Parrot_free_cstring>.

=item Parrot_PMC_get_cstringn(interp, pmc, &len)

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 C<len>
parameter is the address of an integer that will get the length of the
string as Parrot knows it.

This memory will I<not> be reclaimed by garbage collection, nor may it
be returned to the system with C<free>. It must be returned with
C<Parrot_free_cstring>.

=back

=head2 Group 2: Internals aware

The internals-aware functions are for those extensions that need to
query or alter the state of Parrot's internals in some way. 

=head1 SEE ALSO

L<docs/glossary.pod>