docs/pdds/draft/pdd11_extending.pod

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