docs/pdds/draft/pdd10_embedding.pod

   1 # Copyright (c) 2001-2010, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 [DRAFT] PDD10: Embedding and Extending
   5
   6 =head2 Abstract
   7
   8 What we believe people will do when embedding and extending Parrot, why they
   9 do it, and how.
  10
  11 {{ NOTE: some of this will later move into pdds 11 & 12, but for now
  12 just want to get the stub checked in. }}
  13
  14 =head2 Version
  15
  16 $Revision$
  17
  18 =head2 Description
  19
  20 Why embed:
  21
  22 =over 4
  23
  24 =item * access to special features/libraries/languages Parrot provides
  25
  26 =item * need an interpreter for a DSL or existing language
  27
  28 =item * want to run Parrot on another platform or environment (dedicated
  29 hardware, in a web server, et cetera)
  30
  31 =back
  32
  33 Why extend:
  34
  35 =over 4
  36
  37 =item * need something NCI doesn't provide
  38
  39 =item * writing a custom PMC
  40
  41 =back
  42
  43 Philosophical rules:
  44
  45 =over 4
  46
  47 =item * only ever use opaque pointers
  48
  49 =item * should be able to communicate through PMCs
  50
  51 =item * minimize conversions to and from C data
  52
  53 =over 4
  54
  55 =item * perhaps macros; Ruby does this fairly well and Perl 5 does this
  56 poorly
  57
  58 =item * minimize the number of necessary functions
  59
  60 =item * probably can follow core Parrot code to some extent, but beware the
  61 Perl 5 problem
  62
  63 =over 4
  64
  65 =item * do not expose Parrot internals that may change
  66
  67 =over 4
  68
  69 =item * minimize the number of headers used
  70
  71 =item * minimize the number of Parrot types exposed
  72
  73 =item * follow boundaries similar to those of PIR where possible
  74
  75 =back
  76
  77 =item * probably includes vtable functions on PMCs
  78
  79 =back
  80
  81 =back
  82
  83 =back
  84
  85 Gotchas:
  86
  87 =over 4
  88
  89 =item * who handles signals?
  90
  91 =item * who owns file descriptors and other Unix resources?
  92
  93 =item * is there an exception boundary?
  94
  95 =item * namespace issues -- especially key related
  96
  97 =item * probably a continuation/control flow boundary
  98
  99 =item * packfiles and subroutines probably too much information for
 100 either
 101
 102 =item * do not let MMD and other implementation details escape
 103
 104 =item * okay to require some PBC/PIR/PASM for handling round-trip data
 105
 106 =item * Parrot should not spew errors to STDERR when embedded
 107
 108 =item * who allocates and deallocates resources passed through the boundary
 109 level?
 110
 111 =item * should be access to Parrot's event loop when embedded
 112
 113 =item * passing var args to Parrot subs likely painful
 114
 115 =over 4
 116
 117 =item * perhaps macros/functions to add parameters to call
 118
 119 =item * build up a call signature somehow?
 120
 121 =item * some abstraction for a call frame?
 122
 123 =back
 124
 125 =item * compiling code from a string should return the PMC Sub entry point
 126 (:main)
 127
 128 =item * are there still directory path, loading, and deployment issues?
 129
 130 =item * how do dynamic oplibs and custom PMCs interact?
 131
 132 =item * what's the best way to handle character sets and Unicode?
 133
 134 =back
 135
 136 =head2 Definitions
 137
 138 Embedding - using libparrot from within another program, likely with a
 139 C/NCI/FFI interface
 140
 141 Extending - writing Parrot extensions, likely through C or another language
 142
 143 In practice, there is little difference between the two; mostly in terms of
 144 who has control.  The necessary interfaces should stay the same.
 145
 146 =head2 Implementation
 147
 148 Implementation details.
 149
 150 Simplicity is the main goal; it should be almost trivial to embed Parrot in an
 151 existing application.  It must be trivial to do the right thing; the APIs must
 152 make it so much easier to work correctly than to make mistakes.  This means,
 153 in particular, that:
 154
 155 =over 4
 156
 157 =item * it should never be possible to crash or corrupt the interpreter when
 158 following the interface as documented
 159
 160 =item * each API call or element should have a single purpose
 161
 162 =item * names must be consistent in the API documentation and the examples
 163
 164 =item * it I<should> be possible to embed Parrot I<within> Parrot through NCI,
 165 as a test both of the sanity of the external interface as well as NCI
 166
 167 =back
 168
 169 =head3 Working with Interpreters
 170
 171 It is the external code's duty to create, manage, and destroy interpreters.
 172
 173 C<Parrot_new( NULL )> returns an opaque pointer to a new interpreter:
 174
 175   Parrot_Interp Parrot_new(Parrot_Interp parent);
 176
 177 C<parent> can be NULL for the I<first> interpreter created.  All subsequent
 178 calls to this function should pass an existing interpreter.
 179
 180 I<Note: it is not clear what happens if you fail to do so; is there a way to
 181 detect this in the interface and give a warning?>
 182
 183 C<Parrot_destroy ( interp )> destroys an interpreter and frees its resources.
 184
 185   void Parrot_destroy(Parrot_Interp);
 186
 187 I<Note: It is not clear what happens if this interpreter has active children.>
 188
 189 =head3 Working with Source Code and PBC Files
 190
 191 Perhaps the most common case for working with code is loading it from an
 192 external file.  This may often be PBC, but it must also be possible to load
 193 code with any registered compiler.  This I<must> be a single-stage operation:
 194
 195   Parrot_PMC Parrot_load_bytecode( Parrot_Interp, const char *filepath );
 196
 197   Parrot_PMC Parrot_load_hll_code( Parrot_Interp, const char *compiler,
 198                                                   const char *filepath );
 199
 200 The PMC returned will be the Sub PMC representing the entry point into the
 201 code.  That is, it will be the PMC representing the C<:main> subroutine, if
 202 one exists, or the first subroutine in the file.
 203
 204 If there is an error -- such that the file does not exist, the compiler is
 205 unknown, or there was a compilation or invalid bytecode error -- the PMC
 206 should be an Exception PMC instead.
 207
 208 I<Note: I suppose NULL would work as well; it might be more C-like.  Continue
 209 considering.>
 210
 211 I<Note also: the current C<Parrot_pbc_read()> and C<Parrot_pbc_load()> exposes
 212 the details of packfiles to the external API and uses two operations to
 213 perform a single logical operation.>
 214
 215 I<Note: it may be worth reconsidering these names, if
 216 C<Parrot_load_bytecode()> can load PBC, PIR, and PASM files without having a
 217 compiler named explicitly.>
 218
 219 Compiling source code generated or read from the host application is also
 220 possible:
 221
 222   Parrot_PMC Parrot_compile_string( Parrot_Interp, Parrot_String compiler,
 223                                                    const char *code,
 224                                                    Parrot_String error );
 225
 226 The potential return values are the same as for loading code from disk.
 227
 228 I<Note: this declaration should move from F<interpreter.h> to F<embed.h>.>
 229
 230 =head3 Working with PMCs
 231
 232 TBD.
 233
 234 =head3 Calling Functions
 235
 236 TBD.
 237
 238 =head3 Calling Opcodes
 239
 240 TBD.
 241
 242 =head2 Language Notes
 243
 244 It should be possible to register a compiler for an HLL with an interpreter
 245 such that it is possible to load source code written in that language or pass
 246 source code to an interpreter successfully.
 247
 248 =head2 References
 249
 250 None.
 251
 252 =cut
 253
 254 __END__
 255 Local Variables:
 256   fill-column:78
 257 End: