docs/pdds/draft/pdd11_extending.pod

   1 # Copyright (C) 2001-2007, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/pdds/pdd11_extending.pod - The Parrot Extension System
   7
   8 =head1 ABSTRACT
   9
  10 The extension API for Parrot is a simple, somewhat abstract, interface to
  11 Parrot for code written in C or other compiled languages. It provides about
  12 the same level of access to Parrot  that bytecode programs have.
  13
  14 =head1 DESCRIPTION
  15
  16 The API presents to C programs roughly the same interface presented to
  17 bytecode programs--that is, a C extension can see everything that a bytecode
  18 program can see, including Parrot's base architecture, registers, stacks, and
  19 whatnot. This view isn't required, however, and often extension code won't
  20 need or want to know what Parrot's internal structures look like. For this
  21 reason the functions in the extension API are divided into two broad groups,
  22 one that has no particular knowledge of the internals and one that does.
  23
  24 The stability of the two API groups is guaranteed separately. Group 1, the
  25 internals unaware group, should be good basically forever. Group 2, the
  26 internals aware group, is only guaranteed for the lifetime of the current
  27 architecture. (It's likely that both groups will last equally long; however,
  28 the Group 1 interface could reasonably be emulated on a different engine,
  29 while the Group 2 interface is more closely tied to Parrot).
  30
  31 B<Note:> The extension API has not yet been completely specified. New
  32 functions may be added, and those described below may change or be removed.
  33 You have been warned...
  34
  35 =head1 IMPLEMENTATION
  36
  37 =head2 API - Group 1: Internals-unaware functions
  38
  39 These functions are the ones that are largely unaware of the structure and
  40 architecture of Parrot. They deal mainly in data as abstract entities, and
  41 Parrot itself as a black box that, at best, can make subroutine or method
  42 calls. This is sufficient for many extensions which act as black box
  43 processing units and in turn treat Parrot itself as a black box.
  44
  45 =head3 PMC access functions
  46
  47 The following functions are for storing and retrieving data inside PMCs. Note
  48 that use of the _keyed functions with non-aggregate PMCs will generally just
  49 result in Parrot throwing an exception.
  50
  51 =over 4
  52
  53 =item C<Parrot_PMC_get_string(interp, pmc)>
  54
  55 Returns a Parrot_String that represents the string value of the PMC.
  56
  57 =item C<Parrot_PMC_get_string_intkey(interp, pmc, Parrot_Int key)>
  58
  59 Keyed version of C<Parrot_PMC_get_string>. Returns a Parrot_String
  60 representing the string value of whatever is stored at the element of the PMC
  61 indexed by C<key>.
  62
  63 =item C<Parrot_PMC_get_pointer(interp, pmc)>
  64
  65 Returns a pointer to some item of data. The details of what the pointer points
  66 to depend on the particular PMC. This function is useful for dealing with PMCs
  67 that hold pointers to arbitrary data.
  68
  69 =item C<Parrot_PMC_get_pointer_intkey(interp, pmc, Parrot_Int key)>
  70
  71 A keyed version of C<Parrot_PMC_get_pointer>. Returns the pointer value of
  72 whatever is stored at the element of the PMC indexed by C<key>.
  73
  74 =item C<Parrot_PMC_get_intval(interp, pmc)>
  75
  76 Returns the integer value of the PMC.
  77
  78 =item C<Parrot_PMC_get_intval_intkey(interp, pmc, Parrot_Int key)>
  79
  80 A keyed version of C<Parrot_PMC_get_intval>. Returns the integer value of
  81 whatever is stored at the element of the PMC indexed by C<key>.
  82
  83 =item C<Parrot_PMC_get_numval(interp, pmc)>
  84
  85 Returns the numeric value of the PMC.
  86
  87 =item C<Parrot_PMC_get_numval_intkey(interp, pmc, Parrot_Int key)>
  88
  89 A keyed version of C<Parrot_PMC_get_numval>. Returns the numeric value of
  90 whatever is stored at the element of the PMC indexed by C<key>.
  91
  92 =item C<Parrot_PMC_get_cstring(interp, pmc)>
  93
  94 Returns a C-string (char *) that represents the string value of the PMC. The
  95 memory the char * points to is a copy of the original value, and changing it
  96 will not change the original in any way.
  97
  98 This memory will I<not> be reclaimed by garbage collection, nor may it be
  99 returned to the system with C<free>. It must be returned with
 100 C<Parrot_free_cstring>.
 101
 102 =item C<Parrot_PMC_get_cstring_intkey(interp, pmc, Parrot_Int key)>
 103
 104 A keyed version of C<Parrot_PMC_get_cstring>. Returns a C-string representing
 105 the string value of whatever is stored at the element of  the PMC indexed by
 106 C<key>.
 107
 108 =item C<Parrot_PMC_get_cstringn(interp, pmc, &len)>
 109
 110 Returns a C-string (char *) that represents the string value of the PMC. The
 111 memory the char * points to is a copy of the original value, and changing it
 112 will not change the original in any way. The C<len> parameter is the address
 113 of an integer that will get the length of the string as Parrot knows it.
 114
 115 This memory will I<not> be reclaimed by garbage collection, nor may it be
 116 returned to the system with C<free>. It must be returned with
 117 C<Parrot_free_cstring>.
 118
 119 =item C<Parrot_PMC_get_cstringn_intkey(interp, pmc, &len, Parrot_Int key)>
 120
 121 A keyed version of C<Parrot_PMC_get_cstringn>. Returns a C-string representing
 122 the string value of whatever is stored at the element of  the PMC indexed by
 123 C<key>. Stores the length of the string in C<len>.
 124
 125 =item C<Parrot_PMC_get_pmc_intkey(interp, pmc, Parrot_Int key)>
 126
 127 Returns the PMC stored at the element of the passed-in PMC that is indexed by
 128 C<key>.
 129
 130 =item C<Parrot_PMC_set_string(interp, pmc, Parrot_String value)>
 131
 132 Assign the passed-in Parrot_String to the passed-in PMC.
 133
 134 =item C<Parrot_PMC_set_string_intkey(interp,
 135 pmc, Parrot_String value, Parrot_Int key)>
 136
 137 Keyed version of C<Parrot_PMC_set_string>. Assigns C<value> to the PMC stored
 138 at element <key> of the passed-in PMC.
 139
 140 =item C<Parrot_PMC_set_pointer(interp, pmc, void *value)>
 141
 142 Assign the passed-in pointer to the passed-in PMC.
 143
 144 =item C<Parrot_PMC_set_pointer_intkey(interp, pmc, void *value,
 145 Parrot_Int key)>
 146
 147 Keyed version of C<Parrot_PMC_set_pointer>. Assigns C<value> to the PMC stored
 148 at element <key> of the passed-in PMC.
 149
 150 =item C<Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value,
 151 Parrot_Int key)>
 152
 153 Assigns C<value> to the PMC stored at element <key> of the passed-in PMC.
 154
 155 =item C<Parrot_PMC_set_intval(interp, pmc, Parrot_Int value)>
 156
 157 Assign the passed-in Parrot integer to the passed-in PMC.
 158
 159 =item C<Parrot_PMC_set_intval_intkey(interp,
 160 pmc, Parrot_Int value, Parrot_Int key)>
 161
 162 Keyed version of C<Parrot_PMC_set_intval>. Assigns C<value> to the PMC stored
 163 at element <key> of the passed-in PMC.
 164
 165 =item C<Parrot_PMC_set_numval(interp, pmc, Parrot_Float value)>
 166
 167 Assign the passed-in Parrot number to the passed-in PMC.
 168
 169 =item C<Parrot_PMC_set_numval_intkey(interp,
 170 pmc, Parrot_Float value, Parrot_Int key)>
 171
 172 Keyed version of C<Parrot_PMC_set_numval>. Assigns C<value> to the PMC stored
 173 at element <key> of the passed-in PMC.
 174
 175 =item C<Parrot_PMC_set_cstring(interp, pmc, const char *value)>
 176
 177 Convert the passed-in null-terminated C string to a Parrot_String and assign
 178 it to the passed-in PMC.
 179
 180 =item C<Parrot_PMC_set_cstring_intkey(interp,
 181 pmc, const char *value, Parrot_Int key)>
 182
 183 Keyed version of C<Parrot_PMC_set_cstring>. Converts C<value> to a
 184 Parrot_String and assigns it to the PMC stored at element <key> of the
 185 passed-in PMC.
 186
 187 =item C<Parrot_PMC_set_cstringn(interp,
 188 pmc, const char *value, Parrot_Int length)>
 189
 190 Convert the passed-in null-terminated C string to a Parrot_String of length
 191 C<length> and assign it to the passed-in PMC. If C<value> is longer than
 192 C<length>, then only the first C<length> characters will be converted. If
 193 C<value> is shorter than C<length>, then the extra characters in the
 194 Parrot_String should be assumed to contain garbage.
 195
 196 =item C<Parrot_PMC_set_cstringn_intkey(interp,
 197 pmc, const char *value, Parrot_int length, Parrot_Int key)>
 198
 199 Keyed version of C<Parrot_PMC_set_cstringn>. Converts the first C<length>
 200 characters of C<value> to a Parrot_String and assigns the resulting string to
 201 the PMC stored at element <key> of the passed-in PMC.
 202
 203 =back
 204
 205 =head3 Creation and destruction
 206
 207 Functions used to create and destroy PMCs, Parrot_Strings, etc.
 208
 209 =over 4
 210
 211 =item C<Parrot_PMC_new(interp, Parrot_Int typenum)>
 212
 213 Creates and returns a new PMC. C<typenum> is an integer identifier that
 214 specifies the type of PMC required. The C<typenum> corresponding to a
 215 particular PMC class name can be found using C<Parrot_PMC_typenum>.
 216
 217 =item C<Parrot_PMC_typenum(interp, const char* class)>
 218
 219 Returns the internal integer identifier corresponding to a PMC with class name
 220 C<class>.
 221
 222 =item C<Parrot_PMC_null()>
 223
 224 Returns the special C<NULL> PMC.
 225
 226 =item C<Parrot_new_string(interp,
 227 char *buffer, int length, Parrot_Encoding encoding,
 228 Parrot_CharType charset, Parrot_Language language, Parrot_Int flags)>
 229
 230 Create a new Parrot string from a passed-in buffer. If the C<encoding>,
 231 C<charset>, or C<language> are unspecified (i.e. if you pass in 0), then the
 232 defaults are used. Otherwise, the functions C<Parrot_find_encoding>,
 233 C<Parrot_find_chartype> and C<Parrot_find_language> (all described below) can
 234 be used to find the appropriate values for a particular choice of  encoding,
 235 chartype or language.
 236
 237 Flag values are currently undocumented.
 238
 239 Note that a copy of the buffer is made.
 240
 241 =item C<Parrot_find_encoding(interp, char *encoding_name)>
 242
 243 Find the magic token for an encoding, by name.
 244
 245 =item C<Parrot_find_chartype(interp, char *chartype)>
 246
 247 Find the magic token for a chartype, by name.
 248
 249 =item C<Parrot_find_language(interp, char *language)>
 250
 251 Find the magic token for a language, by language name.
 252
 253 =item C<Parrot_free_cstring(char* string)>
 254
 255 Deallocates a C string that the interpreter has handed to you. This function
 256 must be used to free strings produced by  C<Parrot_PMC_get_cstring> and
 257 C<Parrot_PMC_get_cstringn>, as these will not be reclaimed by the garbage
 258 collector. It should not be used to deallocate strings that do not come from
 259 Parrot.
 260
 261 =item C<Parrot_register_pmc(interp, pmc)>
 262
 263 Add a reference to the PMC to the interpreter's DOD registry. This prevents
 264 PMCs known only to extensions from getting destroyed during  DOD runs.
 265
 266 =item C<Parrot_unregister_pmc(interp, pmc)>
 267
 268 Remove a reference to the PMC from the interpreter's DOD registry.  If the
 269 reference count reaches zero, the PMC will be destroyed during the  next DOD
 270 run.
 271
 272 =back
 273
 274 =head3 Subroutine and method calls
 275
 276 Functions to call Parrot subroutines and methods
 277
 278 =over 4
 279
 280 =item C<Parrot_call_sub(interp, Parrot_PMC sub, Parrot_Int argcount, ...)>
 281
 282 Calls a Parrot subroutine, with C<argcount> PMC parameters. This function sets
 283 up Parrot's registers in line with the Parrot calling conventions; see
 284 L<pdd03_calling_conventions.pod> for more details.
 285
 286 =item C<Parrot_call_method(interp,
 287 Parrot_PMC sub, Parrot_String method, Parrot_Int argcount, ...)>
 288
 289 Calls a Parrot method named C<method> with C<argcount> PMC parameters. NB.
 290 This is not yet implemented and may change.
 291
 292 =back
 293
 294 =head2 API - Group 2: Internals aware
 295
 296 The internals-aware functions are for those extensions that need to query or
 297 alter the state of Parrot's internals in some way.
 298
 299 Register access functions
 300
 301 The following functions allow the values stored in Parrot's registers to be
 302 accessed. An attempt to access a non-existent register (e.g. string register
 303 -123) will cause the function to throw an exception (well, it will once we
 304 actually implement some bounds-checking...).  The value stored in an
 305 uninitialized register is undefined; it may well be zero (or NULL), but do not
 306 rely on this being the case.
 307
 308 =over 4
 309
 310 =item C<Parrot_get_intreg(interp, Parrot_Int regnum)>
 311
 312 Return the value of an integer register.
 313
 314 =item C<Parrot_get_numreg(interp, Parrot_Int regnum)>
 315
 316 Return the value of a numeric register.
 317
 318 =item C<Parrot_get_strreg(interp, Parrot_Int regnum)>
 319
 320 Return the value of a string register.
 321
 322 =item C<Parrot_get_pmcreg(interp, Parrot_Int regnum)>
 323
 324 Return the value of a PMC register.
 325
 326 =back
 327
 328 =head1 ATTACHMENTS
 329
 330 None.
 331
 332 =head1 FOOTNOTES
 333
 334 None.
 335
 336 =head1 REFERENCES
 337
 338 F<docs/glossary.pod>
 339
 340 =head1 VERSION
 341
 342 =head2 CURRENT
 343
 344     Maintainer:
 345     Class: Internals
 346     PDD Number: 11
 347     Version: 1.0
 348     Status: Developing
 349     Last Modified: February 20, 2004
 350     PDD Format: 1
 351     Language: English
 352
 353 =head2 HISTORY
 354
 355 =over 4
 356
 357 =item Version 1
 358
 359 None. First version
 360
 361 =back
 362
 363 =head1 CHANGES
 364
 365 =over 4
 366
 367 =item Version 1.0
 368
 369 None. First version
 370
 371 =back
 372
 373 =cut