src/extend.c

   1 /*
   2 Copyright (C) 2001-2007, The Perl Foundation.
   3 $Id$
   4
   5 =head1 NAME
   6
   7 src/extend.c - Parrot extension interface
   8
   9 =head1 DESCRIPTION
  10
  11 These are the functions that parrot extensions (i.e. parrot subroutines
  12 written in C, or some other compiled language, rather than in parrot
  13 bytecode) may access.
  14
  15 There is a deliberate distancing from the internals here. Don't go
  16 peeking inside -- you've as much access as bytecode does, but no more,
  17 so we can provide backwards compatibility for as long as we possibly
  18 can.
  19
  20 =head2 Functions
  21
  22 =over 4
  23
  24 =cut
  25
  26 */
  27
  28 /* Some internal notes. Parrot will die a horrible and bizarre death
  29    if the stack start pointer's not set and a DOD run is
  30    triggered. The pointer *will* be set by the interpreter if the
  31    interpreter calls code which calls these functions, so most
  32    extension code is safe, no problem.
  33
  34    The problem comes in if these routines are called from *outside*
  35    an interpreter. This happens when an embedding application calls
  36    them to do stuff with PMCs, STRINGS, interpreter contents, and
  37    suchlike things. This is perfectly legal -- in fact it's what
  38    we've documented should be done -- but the problem is that the
  39    stack base pointer will be NULL. This is Very Bad.
  40
  41    To deal with this there are two macros that are defined to handle
  42    the problem.
  43
  44    PARROT_CALLIN_START(interp) will figure out if the stack
  45    anchor needs setting and, if so, will set it. It must *always*
  46    come immediately after the last variable declared in the block
  47    making the calls into the interpreter, as it declares a variable
  48    and has some code.
  49
  50    PARROT_CALLIN_END(interp) will put the stack anchor back to
  51    the way it was, and should always be the last statement before a
  52    return. (If you have multiple returns have it in multiple times)
  53
  54    Not doing this is a good way to introduce bizarre heisenbugs, so
  55    just do it. This is the only place they ought to have to be put
  56    in, and most of the functions are already written, so it's not
  57    like it's an onerous requirement.
  58
  59 */
  60
  61 #include "parrot/parrot.h"
  62 #include "parrot/extend.h"
  63
  64 /* HEADERIZER HFILE: include/parrot/extend.h */
  65
  66 /*
  67
  68 =item C<int Parrot_vfprintf>
  69
  70 Writes a C string format with a varargs list to a PIO.
  71
  72 =item C<int Parrot_fprintf>
  73
  74 Writes a C string format with varargs to a PIO.
  75
  76 =item C<int Parrot_printf>
  77
  78 Writes a C string format with varargs to C<stdout>.
  79
  80 =item C<int Parrot_eprintf>
  81
  82 Writes a C string format with varargs to C<stderr>.
  83
  84 */
  85
  86 PARROT_API
  87 int
  88 Parrot_vfprintf(PARROT_INTERP, ARGIN(Parrot_PMC pio),
  89         ARGIN(const char *s), va_list args)
  90 {
  91     STRING * str;
  92     INTVAL retval;
  93
  94     PARROT_CALLIN_START(interp);
  95     str = Parrot_vsprintf_c(interp, s, args);
  96     retval = PIO_putps(interp, pio, str);
  97     PARROT_CALLIN_END(interp);
  98
  99     return retval;
 100 }
 101
 102 PARROT_API
 103 int
 104 Parrot_fprintf(PARROT_INTERP, ARGIN(Parrot_PMC pio),
 105         ARGIN(const char *s), ...)
 106 {
 107     va_list args;
 108     INTVAL retval;
 109
 110     va_start(args, s);
 111     retval = Parrot_vfprintf(interp, pio, s, args);
 112     va_end(args);
 113
 114     return retval;
 115 }
 116
 117 PARROT_API
 118 int
 119 Parrot_printf(NULLOK_INTERP, ARGIN(const char *s), ...)
 120 {
 121     va_list args;
 122     INTVAL retval;
 123     va_start(args, s);
 124
 125     if (interp) {
 126         retval = Parrot_vfprintf(interp, PIO_STDOUT(interp), s, args);
 127     }
 128     else {
 129         /* Be nice about this...
 130          **   XXX BD Should this use the default PIO_STDOUT or something?
 131          */
 132         retval = vfprintf(stdout, s, args);
 133     }
 134     va_end(args);
 135
 136     return retval;
 137 }
 138
 139 PARROT_API
 140 int
 141 Parrot_eprintf(NULLOK_INTERP, ARGIN(const char *s), ...)
 142 {
 143     va_list args;
 144     INTVAL retval;
 145
 146     va_start(args, s);
 147
 148     if (interp) {
 149         retval = Parrot_vfprintf(interp, PIO_STDERR(interp), s, args);
 150     }
 151     else {
 152         /* Be nice about this...
 153          **   XXX BD Should this use the default PIO_STDOUT or something?
 154          */
 155         retval=vfprintf(stderr, s, args);
 156     }
 157
 158     va_end(args);
 159
 160     return retval;
 161 }
 162
 163 /*
 164
 165 =item C<Parrot_String Parrot_PMC_get_string_intkey>
 166
 167 Return the integer keyed string value of the passed-in PMC
 168
 169 =cut
 170
 171 */
 172
 173 PARROT_API
 174 Parrot_String
 175 Parrot_PMC_get_string_intkey(PARROT_INTERP,
 176         Parrot_PMC pmc, Parrot_Int key)
 177 {
 178     Parrot_String retval;
 179     PARROT_CALLIN_START(interp);
 180     retval = VTABLE_get_string_keyed_int(interp, pmc, key);
 181     PARROT_CALLIN_END(interp);
 182     return retval;
 183 }
 184
 185
 186 /*
 187
 188 =item C<void * Parrot_PMC_get_pointer_intkey>
 189
 190 Return a pointer to the PMC indicated by an integer key.
 191
 192 =cut
 193
 194 */
 195
 196 PARROT_API
 197 PARROT_WARN_UNUSED_RESULT
 198 PARROT_CAN_RETURN_NULL
 199 void *
 200 Parrot_PMC_get_pointer_intkey(PARROT_INTERP,
 201         Parrot_PMC pmc, Parrot_Int key)
 202 {
 203     void *retval;
 204     PARROT_CALLIN_START(interp);
 205     retval = VTABLE_get_pointer_keyed_int(interp, pmc, key);
 206     PARROT_CALLIN_END(interp);
 207     return retval;
 208 }
 209
 210 /*
 211
 212 =item C<Parrot_PMC Parrot_PMC_get_pmc_intkey>
 213
 214 Return the integer keyed PMC value of the passed-in PMC
 215
 216 =cut
 217
 218 */
 219
 220 PARROT_API
 221 Parrot_PMC
 222 Parrot_PMC_get_pmc_intkey(PARROT_INTERP,
 223         Parrot_PMC pmc, Parrot_Int key)
 224 {
 225     Parrot_PMC retval;
 226     PARROT_CALLIN_START(interp);
 227     retval = VTABLE_get_pmc_keyed_int(interp, pmc, key);
 228     PARROT_CALLIN_END(interp);
 229     return retval;
 230 }
 231
 232 /*
 233
 234 =item C<Parrot_Int Parrot_PMC_get_intval>
 235
 236 Return the signed integer value of the value in the PMC.
 237
 238 =cut
 239
 240 */
 241
 242 PARROT_API
 243 Parrot_Int
 244 Parrot_PMC_get_intval(PARROT_INTERP, Parrot_PMC pmc)
 245 {
 246     Parrot_Int retval;
 247     PARROT_CALLIN_START(interp);
 248     retval = VTABLE_get_integer(interp, pmc);
 249     PARROT_CALLIN_END(interp);
 250     return retval;
 251 }
 252
 253 /*
 254
 255 =item C<Parrot_Int Parrot_PMC_get_intval_intkey>
 256
 257 Return the keyed, signed integer value of the value in the PMC.
 258
 259 =cut
 260
 261 */
 262
 263 PARROT_API
 264 Parrot_Int
 265 Parrot_PMC_get_intval_intkey(PARROT_INTERP,
 266         Parrot_PMC pmc, Parrot_Int key)
 267 {
 268     Parrot_Int retval;
 269     PARROT_CALLIN_START(interp);
 270     retval = VTABLE_get_integer_keyed_int(interp, pmc, key);
 271     PARROT_CALLIN_END(interp);
 272     return retval;
 273 }
 274
 275 /*
 276
 277 =item C<Parrot_Int Parrot_PMC_get_intval_pmckey>
 278
 279 Return the keyed, signed integer value of the value in the PMC.
 280
 281 =cut
 282
 283 */
 284
 285 PARROT_API
 286 Parrot_Int
 287 Parrot_PMC_get_intval_pmckey(PARROT_INTERP,
 288         Parrot_PMC pmc, Parrot_PMC key)
 289 {
 290     Parrot_Int retval;
 291     PARROT_CALLIN_START(interp);
 292     retval = VTABLE_get_integer_keyed(interp, pmc, key);
 293     PARROT_CALLIN_END(interp);
 294     return retval;
 295 }
 296
 297 /*
 298
 299 =item C<Parrot_Float Parrot_PMC_get_numval>
 300
 301 Return the floating-point value of the PMC.
 302
 303 =cut
 304
 305 */
 306
 307 PARROT_API
 308 Parrot_Float
 309 Parrot_PMC_get_numval(PARROT_INTERP, Parrot_PMC pmc)
 310 {
 311     Parrot_Float retval;
 312     PARROT_CALLIN_START(interp);
 313     retval = VTABLE_get_number(interp, pmc);
 314     PARROT_CALLIN_END(interp);
 315     return retval;
 316 }
 317
 318 /*
 319
 320 =item C<Parrot_Float Parrot_PMC_get_numval_intkey>
 321
 322 Return the keyed, signed integer value of the value in the PMC.
 323
 324 =cut
 325
 326 */
 327
 328 PARROT_API
 329 Parrot_Float
 330 Parrot_PMC_get_numval_intkey(PARROT_INTERP,
 331         Parrot_PMC pmc, Parrot_Int key)
 332 {
 333     Parrot_Float retval;
 334     PARROT_CALLIN_START(interp);
 335     retval = VTABLE_get_number_keyed_int(interp, pmc, key);
 336     PARROT_CALLIN_END(interp);
 337     return retval;
 338 }
 339
 340 /*
 341
 342 =item C<char * Parrot_PMC_get_cstring_intkey>
 343
 344 Return a null-terminated string that represents the string value of the PMC.
 345
 346 Note that you must free this string with C<string_cstring_free()>!
 347
 348 =cut
 349
 350 */
 351
 352 PARROT_API
 353 PARROT_MALLOC
 354 PARROT_CAN_RETURN_NULL
 355 char *
 356 Parrot_PMC_get_cstring_intkey(PARROT_INTERP,
 357         Parrot_PMC pmc, Parrot_Int key)
 358 {
 359     STRING *intermediate;
 360     char   *retval;
 361
 362     PARROT_CALLIN_START(interp);
 363     intermediate = VTABLE_get_string_keyed_int(interp, pmc, key);
 364     retval       = string_to_cstring(interp, intermediate);
 365     PARROT_CALLIN_END(interp);
 366
 367     return retval;
 368 }
 369
 370 /*
 371
 372 =item C<char * Parrot_PMC_get_cstring>
 373
 374 Return a null-terminated string that represents the string value of the PMC.
 375
 376 Note that you must free this string with C<string_cstring_free()>!
 377
 378 =cut
 379
 380 */
 381
 382 PARROT_API
 383 PARROT_MALLOC
 384 PARROT_CAN_RETURN_NULL
 385 char *
 386 Parrot_PMC_get_cstring(PARROT_INTERP, Parrot_PMC pmc)
 387 {
 388     STRING *intermediate;
 389     char   *retval;
 390
 391     PARROT_CALLIN_START(interp);
 392     intermediate = VTABLE_get_string(interp, pmc);
 393     retval       = string_to_cstring(interp, intermediate);
 394     PARROT_CALLIN_END(interp);
 395
 396     return retval;
 397 }
 398
 399 /*
 400
 401 =item C<char * Parrot_PMC_get_cstringn>
 402
 403 Return a null-terminated string for the PMC, along with the length.
 404
 405 Yes, right now this is a bit of a cheat. It needs fixing, but without
 406 disturbing the interface.
 407
 408 Note that you must free the string with C<string_cstring_free()>.
 409
 410 =cut
 411
 412 */
 413
 414 PARROT_API
 415 PARROT_MALLOC
 416 PARROT_CAN_RETURN_NULL
 417 char *
 418 Parrot_PMC_get_cstringn(PARROT_INTERP, ARGIN(Parrot_PMC pmc),
 419         ARGOUT(Parrot_Int *length))
 420 {
 421     char *retval;
 422
 423     PARROT_CALLIN_START(interp);
 424     retval  = string_to_cstring(interp, VTABLE_get_string(interp, pmc));
 425     *length = strlen(retval);
 426     PARROT_CALLIN_END(interp);
 427
 428     return retval;
 429 }
 430
 431 /*
 432
 433 =item C<char * Parrot_PMC_get_cstringn_intkey>
 434
 435 Return a null-terminated string for the PMC, along with the length.
 436
 437 Yes, right now this is a bit of a cheat. It needs fixing, but without
 438 disturbing the interface.
 439
 440 Note that you must free this string with C<string_cstring_free()>.
 441
 442 =cut
 443
 444 */
 445
 446 PARROT_API
 447 PARROT_MALLOC
 448 PARROT_CAN_RETURN_NULL
 449 char *
 450 Parrot_PMC_get_cstringn_intkey(PARROT_INTERP, ARGIN(Parrot_PMC pmc),
 451         ARGOUT(Parrot_Int *length), Parrot_Int key)
 452 {
 453     char *retval;
 454
 455     PARROT_CALLIN_START(interp);
 456     retval  = string_to_cstring(interp,
 457                                VTABLE_get_string_keyed_int(interp, pmc, key));
 458     *length = strlen(retval);
 459     PARROT_CALLIN_END(interp);
 460
 461     return retval;
 462 }
 463
 464 /*
 465
 466 =item C<void Parrot_PMC_set_string>
 467
 468 Assign the passed-in Parrot string to the passed-in PMC.
 469
 470 =cut
 471
 472 */
 473
 474 PARROT_API
 475 void
 476 Parrot_PMC_set_string(PARROT_INTERP,
 477         Parrot_PMC pmc, Parrot_String value)
 478 {
 479     PARROT_CALLIN_START(interp);
 480     VTABLE_set_string_native(interp, pmc, value);
 481     PARROT_CALLIN_END(interp);
 482 }
 483
 484 /*
 485
 486 =item C<void Parrot_PMC_set_string_intkey>
 487
 488 Assign the passed-in Parrot string to the passed-in PMC.
 489
 490 =cut
 491
 492 */
 493
 494 PARROT_API
 495 void
 496 Parrot_PMC_set_string_intkey(PARROT_INTERP,
 497         Parrot_PMC pmc, Parrot_Int key, Parrot_String value)
 498 {
 499     PARROT_CALLIN_START(interp);
 500     VTABLE_set_string_keyed_int(interp, pmc, key, value);
 501     PARROT_CALLIN_END(interp);
 502 }
 503
 504 /*
 505
 506 =item C<void Parrot_PMC_set_pmc_intkey>
 507
 508 Assign the passed-in pmc to the passed-in slot of the passed-in PMC.
 509
 510 =cut
 511
 512 */
 513
 514 PARROT_API
 515 void
 516 Parrot_PMC_set_pmc_intkey(PARROT_INTERP,
 517         Parrot_PMC pmc, Parrot_Int key, Parrot_PMC value)
 518 {
 519     PARROT_CALLIN_START(interp);
 520     VTABLE_set_pmc_keyed_int(interp, pmc, key, value);
 521     PARROT_CALLIN_END(interp);
 522 }
 523
 524 /*
 525
 526 =item C<void Parrot_PMC_set_pmc_pmckey>
 527
 528 Assign the passed-in pmc to the passed-in slot of the passed-in PMC.
 529
 530 =cut
 531
 532 */
 533
 534 PARROT_API
 535 void
 536 Parrot_PMC_set_pmc_pmckey(PARROT_INTERP,
 537         Parrot_PMC pmc, Parrot_PMC key, Parrot_PMC value)
 538 {
 539     PARROT_CALLIN_START(interp);
 540     VTABLE_set_pmc_keyed(interp, pmc, key, value);
 541     PARROT_CALLIN_END(interp);
 542 }
 543
 544 /*
 545
 546 =item C<void Parrot_PMC_set_pointer_intkey>
 547
 548 Assign the passed-in pointer to the passed-in PMC.
 549
 550 =cut
 551
 552 */
 553
 554 PARROT_API
 555 void
 556 Parrot_PMC_set_pointer_intkey(PARROT_INTERP,
 557         ARGIN(Parrot_PMC pmc), Parrot_Int key, ARGIN_NULLOK(void *value))
 558 {
 559     PARROT_CALLIN_START(interp);
 560     VTABLE_set_pointer_keyed_int(interp, pmc, key, value);
 561     PARROT_CALLIN_END(interp);
 562 }
 563
 564 /*
 565
 566 =item C<void Parrot_PMC_set_intval>
 567
 568 Assign the passed-in Parrot integer to the passed-in PMC.
 569
 570 =cut
 571
 572 */
 573
 574 PARROT_API
 575 void
 576 Parrot_PMC_set_intval(PARROT_INTERP, Parrot_PMC pmc, Parrot_Int value)
 577 {
 578     PARROT_CALLIN_START(interp);
 579     VTABLE_set_integer_native(interp, pmc, value);
 580     PARROT_CALLIN_END(interp);
 581 }
 582
 583 /*
 584
 585 =item C<void Parrot_PMC_set_intval_intkey>
 586
 587 Assign the passed-in Parrot integer to the passed-in PMC.
 588
 589 =cut
 590
 591 */
 592
 593 PARROT_API
 594 void
 595 Parrot_PMC_set_intval_intkey(PARROT_INTERP,
 596         Parrot_PMC pmc, Parrot_Int key, Parrot_Int value)
 597 {
 598     PARROT_CALLIN_START(interp);
 599     VTABLE_set_integer_keyed_int(interp, pmc, key, value);
 600     PARROT_CALLIN_END(interp);
 601 }
 602
 603 /*
 604
 605 =item C<void Parrot_PMC_set_numval>
 606
 607 Assign the passed-in Parrot number to the passed-in PMC.
 608
 609 =cut
 610
 611 */
 612
 613 PARROT_API
 614 void
 615 Parrot_PMC_set_numval(PARROT_INTERP, Parrot_PMC pmc, Parrot_Float value)
 616 {
 617     PARROT_CALLIN_START(interp);
 618     VTABLE_set_number_native(interp, pmc, value);
 619     PARROT_CALLIN_END(interp);
 620 }
 621
 622 /*
 623
 624 =item C<void Parrot_PMC_set_numval_intkey>
 625
 626 Assign the passed-in Parrot number to the passed-in PMC.
 627
 628 =cut
 629
 630 */
 631
 632 PARROT_API
 633 void
 634 Parrot_PMC_set_numval_intkey(PARROT_INTERP,
 635         Parrot_PMC pmc, Parrot_Int key, Parrot_Float value)
 636 {
 637     PARROT_CALLIN_START(interp);
 638     VTABLE_set_number_keyed_int(interp, pmc, key, value);
 639     PARROT_CALLIN_END(interp);
 640 }
 641
 642 /*
 643
 644 =item C<void Parrot_PMC_set_cstring>
 645
 646 Assign the passed-in null-terminated C string to the passed-in PMC.
 647
 648 =cut
 649
 650 */
 651
 652 PARROT_API
 653 void
 654 Parrot_PMC_set_cstring(PARROT_INTERP, Parrot_PMC pmc, ARGIN_NULLOK(const char *value))
 655 {
 656     PARROT_CALLIN_START(interp);
 657     VTABLE_set_string_native(interp, pmc,
 658                              string_from_cstring(interp, value, 0));
 659     PARROT_CALLIN_END(interp);
 660 }
 661
 662 /*
 663
 664 =item C<void Parrot_PMC_set_cstring_intkey>
 665
 666 Assign the passed-in null-terminated C string to the passed-in PMC.
 667
 668 =cut
 669
 670 */
 671
 672 PARROT_API
 673 void
 674 Parrot_PMC_set_cstring_intkey(PARROT_INTERP,
 675         Parrot_PMC pmc, Parrot_Int key, ARGIN_NULLOK(const char *value))
 676 {
 677     PARROT_CALLIN_START(interp);
 678     VTABLE_set_string_keyed_int(interp, pmc, key,
 679                                 string_from_cstring(interp, value, 0));
 680     PARROT_CALLIN_END(interp);
 681 }
 682
 683 /*
 684
 685 =item C<void Parrot_PMC_set_cstringn>
 686
 687 Assign the passed-in length-noted string to the passed-in PMC.
 688
 689 =cut
 690
 691 */
 692
 693 PARROT_API
 694 void
 695 Parrot_PMC_set_cstringn(PARROT_INTERP,
 696         Parrot_PMC pmc, ARGIN_NULLOK(const char *value), Parrot_Int length)
 697 {
 698     PARROT_CALLIN_START(interp);
 699     VTABLE_set_string_native(interp, pmc,
 700                              string_from_cstring(interp, value, length));
 701     PARROT_CALLIN_END(interp);
 702 }
 703
 704 /*
 705
 706 =item C<void Parrot_PMC_push_intval>
 707
 708 Push the passed-in Parrot integer onto the passed in PMC
 709
 710 =cut
 711
 712 */
 713
 714 PARROT_API
 715 void
 716 Parrot_PMC_push_intval(PARROT_INTERP,
 717         Parrot_PMC pmc, Parrot_Int value)
 718 {
 719     PARROT_CALLIN_START(interp);
 720     VTABLE_push_integer(interp, pmc, value);
 721     PARROT_CALLIN_END(interp);
 722 }
 723
 724 /*
 725
 726 =item C<void Parrot_PMC_push_numval>
 727
 728 Push the passed-in Parrot number onto the passed in PMC
 729
 730 =cut
 731
 732 */
 733
 734 PARROT_API
 735 void
 736 Parrot_PMC_push_numval(PARROT_INTERP, Parrot_PMC pmc, Parrot_Float value)
 737 {
 738     PARROT_CALLIN_START(interp);
 739     VTABLE_push_float(interp, pmc, value);
 740     PARROT_CALLIN_END(interp);
 741 }
 742
 743 /*
 744
 745 =item C<void Parrot_PMC_delete_pmckey>
 746
 747 Deletes the value associated with the passed-in PMC from the PMC.
 748
 749 =cut
 750
 751 */
 752
 753 PARROT_API
 754 void
 755 Parrot_PMC_delete_pmckey(PARROT_INTERP, Parrot_PMC pmc, Parrot_PMC key)
 756 {
 757     PARROT_CALLIN_START(interp);
 758     VTABLE_delete_keyed(interp, pmc, key);
 759     PARROT_CALLIN_END(interp);
 760 }
 761
 762 /*
 763
 764 =item C<void Parrot_PMC_set_cstringn_intkey>
 765
 766 Assign the passed-in length-noted string to the passed-in PMC.
 767
 768 =cut
 769
 770 */
 771
 772 PARROT_API
 773 void
 774 Parrot_PMC_set_cstringn_intkey(PARROT_INTERP,
 775         Parrot_PMC pmc, Parrot_Int key, ARGIN_NULLOK(const char *value), Parrot_Int length)
 776 {
 777     PARROT_CALLIN_START(interp);
 778     VTABLE_set_string_keyed_int(interp, pmc, key,
 779                                 string_from_cstring(interp, value, length));
 780     PARROT_CALLIN_END(interp);
 781 }
 782
 783 /*
 784
 785 =item C<Parrot_PMC Parrot_PMC_new>
 786
 787 Create and return a new PMC.
 788
 789 =cut
 790
 791 */
 792
 793 PARROT_API
 794 Parrot_PMC
 795 Parrot_PMC_new(PARROT_INTERP, Parrot_Int type)
 796 {
 797     Parrot_PMC newpmc;
 798     PARROT_CALLIN_START(interp);
 799     newpmc = pmc_new_noinit(interp, type);
 800     VTABLE_init(interp, newpmc);
 801     PARROT_CALLIN_END(interp);
 802     return newpmc;
 803 }
 804
 805 /*
 806
 807 =item C<Parrot_Int Parrot_PMC_typenum>
 808
 809 Returns the internal identifier that represents the named class.
 810
 811 =cut
 812
 813 */
 814
 815 PARROT_API
 816 Parrot_Int
 817 Parrot_PMC_typenum(PARROT_INTERP, ARGIN_NULLOK(const char *_class))
 818 {
 819     Parrot_Int retval;
 820     PARROT_CALLIN_START(interp);
 821     retval = pmc_type(interp, string_from_cstring(interp, _class, 0));
 822     PARROT_CALLIN_END(interp);
 823     return retval;
 824 }
 825
 826 /*
 827
 828 =item C<Parrot_PMC Parrot_PMC_null>
 829
 830 Returns the special C<NULL> PMC.
 831
 832 =cut
 833
 834 */
 835
 836 PARROT_API
 837 Parrot_PMC
 838 Parrot_PMC_null(void)
 839 {
 840     return PMCNULL;
 841 }
 842
 843 /*
 844
 845 =item C<void Parrot_free_cstring>
 846
 847 Deallocate a C string that the interpreter has handed to you.
 848
 849 =cut
 850
 851 */
 852
 853 PARROT_API
 854 void
 855 Parrot_free_cstring(ARGIN_NULLOK(char *string))
 856 {
 857     string_cstring_free(string);
 858 }
 859
 860 /*
 861
 862 =item C<void* Parrot_call_sub>
 863
 864 Call a parrot subroutine with the given function signature. The first char in
 865 C<signature> denotes the return value. Next chars are arguments.
 866
 867 The return value of this function can be void or a pointer type.
 868
 869 Signature chars are:
 870
 871     v ... void return
 872     I ... Parrot_Int
 873     N ... Parrot_Float
 874     S ... Parrot_String
 875     P ... Parrot_PMC
 876
 877 =cut
 878
 879 */
 880
 881 PARROT_API
 882 PARROT_WARN_UNUSED_RESULT
 883 PARROT_CAN_RETURN_NULL
 884 void*
 885 Parrot_call_sub(PARROT_INTERP, Parrot_PMC sub,
 886                  ARGIN(const char *signature), ...)
 887 {
 888     va_list ap;
 889     void *result;
 890
 891     PARROT_CALLIN_START(interp);
 892
 893     va_start(ap, signature);
 894     CONTEXT(interp)->constants =
 895         PMC_sub(sub)->seg->const_table->constants;
 896     result = Parrot_runops_fromc_arglist(interp, sub, signature, ap);
 897     va_end(ap);
 898
 899     PARROT_CALLIN_END(interp);
 900     return result;
 901 }
 902
 903 /*
 904
 905 =item C<Parrot_Int Parrot_call_sub_ret_int>
 906
 907 Like C<Parrot_call_sub>, with Parrot_Int return result.
 908
 909 =cut
 910
 911 */
 912
 913 PARROT_API
 914 Parrot_Int
 915 Parrot_call_sub_ret_int(PARROT_INTERP, Parrot_PMC sub,
 916                  ARGIN(const char *signature), ...)
 917 {
 918     va_list ap;
 919     Parrot_Int result;
 920
 921     PARROT_CALLIN_START(interp);
 922
 923     va_start(ap, signature);
 924     CONTEXT(interp)->constants =
 925         PMC_sub(sub)->seg->const_table->constants;
 926     result = Parrot_runops_fromc_arglist_reti(interp, sub, signature, ap);
 927     va_end(ap);
 928
 929     PARROT_CALLIN_END(interp);
 930     return result;
 931 }
 932
 933 /*
 934
 935 =item C<Parrot_Float Parrot_call_sub_ret_float>
 936
 937 Like C<Parrot_call_sub>, with Parrot_Float return result.
 938
 939 =cut
 940
 941 */
 942
 943 PARROT_API
 944 Parrot_Float
 945 Parrot_call_sub_ret_float(PARROT_INTERP, Parrot_PMC sub,
 946                  ARGIN(const char *signature), ...)
 947 {
 948     va_list      ap;
 949     Parrot_Float result;
 950
 951     PARROT_CALLIN_START(interp);
 952
 953     va_start(ap, signature);
 954     CONTEXT(interp)->constants =
 955         PMC_sub(sub)->seg->const_table->constants;
 956     result = Parrot_runops_fromc_arglist_retf(interp, sub, signature, ap);
 957     va_end(ap);
 958
 959     PARROT_CALLIN_END(interp);
 960     return result;
 961 }
 962
 963 /*
 964
 965 =item C<void * Parrot_call_method>
 966
 967 Call a parrot method for the given object.
 968
 969 =cut
 970
 971 */
 972
 973 PARROT_API
 974 PARROT_WARN_UNUSED_RESULT
 975 PARROT_CAN_RETURN_NULL
 976 void *
 977 Parrot_call_method(PARROT_INTERP, Parrot_PMC sub, Parrot_PMC obj,
 978                         Parrot_String method, ARGIN(const char *signature), ...)
 979 {
 980     void    *result;
 981     va_list ap;
 982
 983     PARROT_CALLIN_START(interp);
 984     va_start(ap, signature);
 985     result = Parrot_run_meth_fromc_arglist(interp, sub,
 986             obj, method, signature, ap);
 987     va_end(ap);
 988     PARROT_CALLIN_END(interp);
 989     return result;
 990 }
 991
 992 /*
 993
 994 =item C<Parrot_Int Parrot_call_method_ret_int>
 995
 996 Call a parrot method for the given object.
 997
 998 =cut
 999
1000 */
1001
1002 PARROT_API
1003 Parrot_Int
1004 Parrot_call_method_ret_int(PARROT_INTERP, Parrot_PMC sub,
1005         Parrot_PMC obj, Parrot_String method, ARGIN(const char *signature), ...)
1006 {
1007     Parrot_Int result;
1008     va_list    ap;
1009
1010     PARROT_CALLIN_START(interp);
1011     va_start(ap, signature);
1012     result = Parrot_run_meth_fromc_arglist_reti(interp, sub,
1013             obj, method, signature, ap);
1014     va_end(ap);
1015     PARROT_CALLIN_END(interp);
1016     return result;
1017 }
1018
1019 /*
1020
1021 =item C<Parrot_Float Parrot_call_method_ret_float>
1022
1023 Call a parrot method for the given object.
1024
1025 =cut
1026
1027 */
1028
1029 PARROT_API
1030 Parrot_Float
1031 Parrot_call_method_ret_float(PARROT_INTERP, Parrot_PMC sub,
1032         Parrot_PMC obj, Parrot_String method, ARGIN(const char *signature), ...)
1033 {
1034     Parrot_Float result;
1035     va_list      ap;
1036
1037     PARROT_CALLIN_START(interp);
1038     va_start(ap, signature);
1039     result = Parrot_run_meth_fromc_arglist_retf(interp, sub,
1040             obj, method, signature, ap);
1041     va_end(ap);
1042     PARROT_CALLIN_END(interp);
1043     return result;
1044 }
1045
1046 /*
1047
1048 =item C<Parrot_Int Parrot_get_intreg>
1049
1050 Return the value of an integer register.
1051
1052 =cut
1053
1054 */
1055
1056 PARROT_API
1057 Parrot_Int
1058 Parrot_get_intreg(PARROT_INTERP, Parrot_Int regnum)
1059 {
1060     return REG_INT(interp, regnum);
1061 }
1062
1063 /*
1064
1065 =item C<Parrot_Float Parrot_get_numreg>
1066
1067 Return the value of a numeric register.
1068
1069 =cut
1070
1071 */
1072
1073 PARROT_API
1074 Parrot_Float
1075 Parrot_get_numreg(PARROT_INTERP, Parrot_Int regnum)
1076 {
1077     return REG_NUM(interp, regnum);
1078 }
1079
1080 /*
1081
1082 =item C<Parrot_String Parrot_get_strreg>
1083
1084 Return the value of a string register.
1085
1086 =cut
1087
1088 */
1089
1090 PARROT_API
1091 Parrot_String
1092 Parrot_get_strreg(PARROT_INTERP, Parrot_Int regnum)
1093 {
1094     return REG_STR(interp, regnum);
1095 }
1096
1097 /*
1098
1099 =item C<Parrot_PMC Parrot_get_pmcreg>
1100
1101 Return the value of a PMC register.
1102
1103 =cut
1104
1105 */
1106
1107 PARROT_API
1108 Parrot_PMC
1109 Parrot_get_pmcreg(PARROT_INTERP, Parrot_Int regnum)
1110 {
1111     return REG_PMC(interp, regnum);
1112 }
1113
1114 /*
1115
1116 =item C<void Parrot_set_intreg>
1117
1118 Set the value of an I register.
1119
1120 =cut
1121
1122 */
1123
1124 PARROT_API
1125 void
1126 Parrot_set_intreg(PARROT_INTERP, Parrot_Int regnum,
1127                   Parrot_Int value)
1128 {
1129     REG_INT(interp, regnum) = value;
1130 }
1131
1132 /*
1133
1134 =item C<void Parrot_set_numreg>
1135
1136 Set the value of an N register.
1137
1138 =cut
1139
1140 */
1141
1142 PARROT_API
1143 void
1144 Parrot_set_numreg(PARROT_INTERP, Parrot_Int regnum,
1145                   Parrot_Float value)
1146 {
1147     REG_NUM(interp, regnum) = value;
1148 }
1149
1150 /*
1151
1152 =item C<void Parrot_set_strreg>
1153
1154 Set the value of an S register.
1155
1156 */
1157
1158 PARROT_API
1159 void
1160 Parrot_set_strreg(PARROT_INTERP, Parrot_Int regnum,
1161                   Parrot_String value)
1162 {
1163     REG_STR(interp, regnum) = value;
1164 }
1165
1166 /*
1167
1168 =item C<void Parrot_set_pmcreg>
1169
1170 Set the value of a P register.
1171
1172 =cut
1173
1174 */
1175
1176 PARROT_API
1177 void
1178 Parrot_set_pmcreg(PARROT_INTERP, Parrot_Int regnum,
1179                   Parrot_PMC value)
1180 {
1181     REG_PMC(interp, regnum) = value;
1182 }
1183
1184 /*=for api extend Parrot_new_string
1185  *
1186  */
1187 /*
1188
1189 =item C<Parrot_String Parrot_new_string>
1190
1191 Create a new Parrot string from a passed-in buffer. Pass in a 0 for
1192 flags for right now.
1193
1194 A copy of the buffer is made.
1195
1196 =cut
1197
1198 */
1199
1200 PARROT_API
1201 PARROT_WARN_UNUSED_RESULT
1202 PARROT_CANNOT_RETURN_NULL
1203 Parrot_String
1204 Parrot_new_string(PARROT_INTERP, ARGIN_NULLOK(const char *buffer), int length,
1205         ARGIN_NULLOK(const char * const encoding_name), Parrot_Int flags)
1206 {
1207     Parrot_String retval;
1208     PARROT_CALLIN_START(interp);
1209     retval = string_make(interp, buffer, length, encoding_name, flags);
1210     PARROT_CALLIN_END(interp);
1211     return retval;
1212 }
1213
1214 /*
1215
1216 =item C<Parrot_Language Parrot_find_language>
1217
1218 Find the magic language token for a language, by language name.
1219
1220 =cut
1221
1222 */
1223
1224 PARROT_API
1225 PARROT_WARN_UNUSED_RESULT
1226 Parrot_Language
1227 Parrot_find_language(SHIM_INTERP, SHIM(char *language))
1228 {
1229     return 0;
1230 }
1231
1232 /*
1233
1234 =item C<void Parrot_register_pmc>
1235
1236 Add a reference of the PMC to the interpreters DOD registry. This
1237 prevents PMCs only known to extension from getting destroyed during DOD
1238 runs.
1239
1240 =cut
1241
1242 */
1243
1244 PARROT_API
1245 void
1246 Parrot_register_pmc(PARROT_INTERP, Parrot_PMC pmc)
1247 {
1248     PARROT_CALLIN_START(interp);
1249     dod_register_pmc(interp, pmc);
1250     PARROT_CALLIN_END(interp);
1251 }
1252
1253 /*
1254
1255 =item C<void Parrot_unregister_pmc>
1256
1257 Remove a reference of the PMC from the interpreters DOD registry. If the
1258 reference count reaches zero, the PMC will be destroyed during the next
1259 DOD run.
1260
1261 =cut
1262
1263 */
1264
1265 PARROT_API
1266 void
1267 Parrot_unregister_pmc(PARROT_INTERP, Parrot_PMC pmc)
1268 {
1269     PARROT_CALLIN_START(interp);
1270     dod_unregister_pmc(interp, pmc);
1271     PARROT_CALLIN_END(interp);
1272 }
1273
1274 /*
1275
1276 =item C<void Parrot_PMC_set_vtable>
1277
1278 Replaces the vtable of the PMC.
1279
1280 =cut
1281
1282 */
1283
1284 PARROT_API
1285 void
1286 Parrot_PMC_set_vtable(SHIM_INTERP, Parrot_PMC pmc, Parrot_VTABLE vtable)
1287 {
1288     pmc->vtable = vtable;
1289 }
1290
1291 /*
1292
1293 =item C<Parrot_VTABLE Parrot_get_vtable>
1294
1295 Returns the vtable corresponding to the given PMC ID.
1296
1297 =cut
1298
1299 */
1300
1301 PARROT_API
1302 PARROT_PURE_FUNCTION
1303 Parrot_VTABLE
1304 Parrot_get_vtable(PARROT_INTERP, Parrot_Int id)
1305 {
1306     return interp->vtables[id];
1307 }
1308
1309 /*
1310
1311 =back
1312
1313 =head1 SEE ALSO
1314
1315 See F<include/parrot/extend.h> and F<docs/pdds/pdd11_extending.pod>.
1316
1317 =head1 HISTORY
1318
1319 Initial version by Dan Sugalski.
1320
1321 =cut
1322
1323 */
1324
1325
1326 /*
1327  * Local variables:
1328  *   c-file-style: "parrot"
1329  * End:
1330  * vim: expandtab shiftwidth=4:
1331  */