NAME

docs/pdds/embedding.pod - Parrot's Embedding and Extending Interface

ABSTRACT

What we believe people will do when embedding and extending Parrot, why they do it, and how.

{{ NOTE: some of this will later move into pdds 11 & 12, but for now just want to get the stub checked in. }}

VERSION

$Revision: $

DESCRIPTION

Why embed: - access to special features/libraries/languages Parrot provides - need an interpreter for a DSL or existing language - want to run Parrot on another platform or environment (dedicated hardware, in a web server, et cetera)

Why extend: - need something NCI doesn't provide - writing a custom PMC

Philosophical rules: - only ever use opaque pointers - should be able to communicate through PMCs - minimize conversions to and from C data - perhaps macros; Ruby does this fairly well and Perl 5 does this poorly - minimize the number of necessary functions - probably can follow core Parrot code to some extent, but beware the Perl 5 problem - do not expose Parrot internals that may change - probably includes vtable methods on PMCs

Gotchas: - who handles signals? - who owns file descriptors and other Unix resources? - is there an exception boundary? - namespace issues -- especially key related - probably a continuation/control flow boundary - packfiles and compilation units probably too much information for either - do not let MMD and other implementation details escape - okay to require some PBC/PIR/PASM for handling round-trip data - Parrot should not spew errors to STDERR when embedded - const_string() is a real pain, especially with necessary deallocation - should be access to Parrot's event loop when embedded - passing var args to Parrot subs likely painful - perhaps macros/functions to add parameters to call - build up a call signature somehow? - some abstraction for a call frame?

        - compiling code from a string should return the PMC Sub entry point (:main)

DEFINITIONS

Embedding - using libparrot from within another program, likely with a C/NCI/FFI interface

Extending - writing Parrot extensions, likely through C or another language

In practice, there is little difference between the two; mostly in terms of who has control. The necessary interfaces should stay the same.

IMPLEMENTATION

Implementation details.

LANGUAGE NOTES

Notes on application to high-level languages. (optional)

ATTACHMENTS

Any associated documents.

FOOTNOTES

List of footnotes to the text.

REFERENCES

List of references.