Author: allison
Date: Wed Aug 2 23:08:19 2006
New Revision: 13766
Modified:
trunk/docs/pdds/clip/pdd10_embedding.pod
Changes in other areas also in this revision:
Modified:
trunk/ (props changed)
Log:
[pdd10] An initial stub of the embedding PDD. (Thanks chromatic!)
Modified: trunk/docs/pdds/clip/pdd10_embedding.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd10_embedding.pod (original)
+++ trunk/docs/pdds/clip/pdd10_embedding.pod Wed Aug 2 23:08:19 2006
@@ -1,5 +1,97 @@
-=pod
+# Copyright (c) 2001-2006, The Perl Foundation.
+# $Id: $
-Placeholder - real PDD will appear after consultation
+=head1 NAME
+
+docs/pdds/embedding.pod - Parrot's Embedding and Extending Interface
+
+=head1 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. }}
+
+=head1 VERSION
+
+$Revision: $
+
+=head1 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)
+
+=head1 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.
+
+=head1 IMPLEMENTATION
+
+Implementation details.
+
+=head1 LANGUAGE NOTES
+
+Notes on application to high-level languages. (optional)
+
+=head1 ATTACHMENTS
+
+Any associated documents.
+
+=head1 FOOTNOTES
+
+List of footnotes to the text.
+
+=head1 REFERENCES
+
+List of references.
=cut
+
+__END__
+Local Variables:
+ fill-column:78
+End:
