1# Copyright (C) 2001-2010, Parrot Foundation. 2 3=head1 PDD 17: Polymorphic Containers 4 5=head2 Abstract 6 7This PDD describes the internal structure and behavior of the Polymorphic 8Container (PMC) data type. 9 10=head2 Description 11 12PMCs implement all internal data types more complex than a simple integer, 13float, or string, and also the data types of high-level languages. Nothing 14outside the core of Parrot (in fact, nothing outside the data type's vtable 15routines) should infer anything about a PMC. 16 17This does mean, though, that you need to either know what functions are 18available and what they do, or have some method of finding out. Parrot defines 19a standard set of functions that each PMC provides. More complex features are 20constructed out of these fundamental building blocks. 21 22=over 4 23 24=item - PMCs contain both state and behavior 25 26=item - PMCs can inherit from other PMCs 27 28=item - PMCs can be composed of low-level roles 29 30=item - High-level objects can subclass low-level PMCs 31 32 33=back 34 35=head2 Implementation 36 37=head3 Internal structure 38 39All PMCs have the form: 40 41 struct PMC { 42 Parrot_UInt flags; 43 VTABLE *vtable; 44 DPOINTER *data; 45 PMC *_metadata; 46 } 47 48C<flags> holds a set of flags associated with the PMC; these are documented 49in F<include/parrot/pobj.h>, and are generally only used within the Parrot 50internals. 51 52C<vtable> holds a pointer to the B<vtable> associated with the PMC. This 53points to a set of functions, with interfaces described in L<Vtable Functions> 54that implement the basic behaviour of the PMC (i.e. how it behaves under 55addition, subtraction, cloning etc.) 56 57C<data> holds a pointer to the core data associated with the PMC. This 58may be null. 59 60C<_metadata> holds internal PMC metadata (properties). See the setprop/getprop 61ops in F<docs/ops/pmc.pod>. 62 63C<_synchronize> is for access synchronization between shared PMCs. 64 65PMCs are used to implement the basic data types of the high level languages 66running on top of Parrot. For instance, a Perl 5 C<SV> will map onto one (or 67more) types of PMC, while particular Python datatypes will map onto different 68types of PMC. 69 70=head3 Defining PMCs 71 72PMCs are declared by the C<pmclass> keyword: 73 74 pmclass <name> [ <modifier> ... ] { 75 } 76 77The modifiers specify core features, such as: 78 79=over 4 80 81=item abstract 82 83The PMC cannot be instantiated. (By convention, abstract classes are given 84lower-case names.) 85 86=item no_init 87 88Don't generate class initialization code (don't set up a vtable for the PMC). 89Used with C<abstract>. 90 91=item dynpmc 92 93The PMC is a dynamic PMC, so generate special class initialization code 94suitable for dynamic loading at runtime. 95 96=item singleton 97 98The PMC is a singleton, created in the constant PMC pool. 99 100=item no_ro 101 102Don't create a second read-only vtable for the PMC. (Used, for example, 103by STM's C<share_ro()>.) 104 105=item is_shared 106 107The PMC is shared (across threads). 108 109=item extends 110 111Inherit from another PMC. Takes one argument, the name of the PMC to inherit 112from. 113 114=item does 115 116Compose a role. Takes one argument, the name of the role to compose. [NOTE: 117this modifier has been taken from the older feature C<does> which is now 118called C<provides>.] 119 120=item resolves 121 122Resolve a conflicting vtable function, method, or attribute from a composed 123role by using the same named vtable function, method, or attribute from the 124current C<pmclass> or C<prole>. 125 126=item provides 127 128The PMC satisfies a particular low-level interface, which gives some 129assurances on how and where a PMC can be used. 130 131Roles composed with C<does> may also define C<provides> for one or more 132interfaces. (They generally define at least a C<provides> corresponding 133to their own name.) 134 135=over 4 136 137=item * C<array> is an aggregate PMC with numerically-keyed elements 138 139=item * C<hash> is an aggregate PMC with string-keyed elements 140 141=item * C<library> corresponds to a dynamic library 142 143=item * C<ref> references another PMC 144 145=item * C<string> behaves similarly to the base string type 146 147=item * C<integer> behaves similarly to the base int type 148 149=item * C<float> behaves similarly to the base number type 150 151=item * C<boolean> does true/false only. 152 153=item * C<scalar> (only used by the sample src/dynpmc/foo.pmc) 154 155=item * C<event> can be used with event queue 156 157=back 158 159=item hll 160 161Declare the PMC in an HLL namespace other than the default HLL 'parrot'. 162Takes one argument, the name of the HLL. 163 164=item maps 165 166Map the current PMC to a core PMC type for code declared in a particular 167HLL. May only be used together with the C<hll> modifier. 168 169=back 170 171=head4 Defining attributes 172 173The attributes of a PMC (both public and private) live in a custom 174struct for the PMC, stored in the C<data> member of the C<PMC> struct. 175The standard way of declaring attributes is with C<ATTR> within the body 176of a C<pmclass> or C<prole> declaration. 177 178 ATTR <type> <name> [ :<modifier> ... ]; 179 180This declaration is used to generate the data struct for the PMC 181(named "Parrot_<pmcname>_attributes"). 182The data struct incorporates any attributes declared 183in a composed role or inherited class. Composed attributes are inserted at the 184end of the generated struct. Inherited attributes are inserted at the top of 185the generated struct, so the struct members shared by the parent and child are 186in the same position, and code compiled for direct struct access to the parent 187can also perform the same direct struct access on the child. 188 189The declaration is also used to generate accessor macros, C<GET_ATTR_attrname> 190and C<SET_ATTR_attrname>, to set up helper information for the C<inspect> 191vtable function, and to provide attribute access through the default 192C<get_attr> and C<set_attr> vtable functions. 193 194It's also possible to define and store the PMC's data struct manually, 195but the standard declaration syntax must be used in roles, in PMCs that 196compose roles, and in PMCs that will be subclassed by high-level classes 197(this means all core PMCs, and most non-core PMCs). 198 199Low-level PMCs that use multiple inheritance (C<pmclass> declarations with 200more than one C<extends> entry) have to be careful with the contents of their 201structs. There's no problem if the two parents have identical data struct 202members. But, if the two parents have different data struct members, any 203vtable functions inherited from the parents will not be able to directly 204access the parents' struct members or use the accessor macros. The solution is 205to either override those vtable functions that directly access data struct 206members in the child PMC, define the parents as roles instead of classes, or 207declare the multiply inheriting child in PIR or an HLL. 208 209=head4 Defining vtable functions 210 211Vtable functions are defined as C functions within the body of the C<pmclass> 212declaration, and are marked with C<VTABLE>. 213 214 VTABLE STRING *get_string() {...} 215 VTABLE void set_string_native(STRING *value) {...} 216 217Within the body of vtable functions, several shortcuts are provided: 218 219=over 4 220 221=item INTERP 222 223The current interpreter object. 224 225=item SELF 226 227The current invocant by dynamic type. 228 229=item STATICSELF 230 231The current invocant by static type. 232 233=item SUPER 234 235Calls the current method in the nearest superclass, using the dynamic 236type of C<SELF>. 237 238=item STATICSUPER 239 240Calls the current method in the nearest superclass, using the static 241type of C<SELF>. 242 243=back 244 245=head4 Methods 246 247Methods are declared in the body of the C<pmclass> or C<prole> 248declaration with C<METHOD>. 249 250 METHOD inspect(STRING *what :optional, int got_what :opt_flag) {...} 251 252=head3 PMCs and Namespaces 253 254Like high-level classes, low-level PMCs are tied to a corresponding 255namespace. By default this is a namespace with the same name as the PMC 256in the 'parrot' HLL, but the C<hll> modifier in the C<pmclass> 257declaration selects a different HLL. 258 259Accessing a core PMC type from within an HLL other than 'parrot' 260requires the same steps as accessing a class from another HLL, first 261retrieving the namespace object, and then instantiating from that 262namespace. 263 264=begin PIR_FRAGMENT 265 266 $P0 = get_root_namespace ['parrot'; 'Integer'] 267 $P1 = new $P0 268 269=end PIR_FRAGMENT 270 271HLLs can choose to provide direct access to Parrot's core PMC types by 272aliasing them within the HLL namespace. 273 274=head3 Inheritance 275 276PMCs can inherit behavior and state from other PMCs. Inheritance is performed 277in the C<pmclass> declaration using the C<extends> keyword. 278 279 pmclass Foo extends Bar { 280 } 281 282=head3 Composition 283 284Composition is another form of code reuse in PMCs. Unlike inheritance, 285composed roles aren't complete stand-alone PMCs, they are just bundles of 286behavior and state that can be used within the composing PMC. As such, roles 287are never instantiated directly, and are never translated to C directly. They 288have no core structs, though they define attributes to be added to the PMC 289they are composed into. 290 291When a PMC that uses a role is translated to C, the role provides vtable 292functions, methods, and attributes that will be added to the generated C 293code for that PMC. Composed vtable functions, methods, and attributes 294are not permitted to have the same name as corresponding features 295defined in the composing PMC. This is called a conflict, and must be 296explicitly resolved in the composing PMC. When composed features have 297the same name as inherited vtable functions, methods, or attributes, the 298composed feature overrides the inherited feature, just as it would if 299defined in the composing PMC. 300 301Roles are defined using the C<prole> keyword. 302 303 prole <name> <modifiers> { 304 } 305 306Roles can compose other roles, but they can't inherit. 307 308Role attributes are defined using the same format as PMC attributes. 309 310Core roles live in src/role and have a file extension of C<.pr>. 311 312Roles are composed into a PMC with the C<does> modifier. 313 314=head3 PMCs and high-level objects 315 316High-level objects, as specified in PDD15, need to be able to inherit 317from PMCs. Subclassing a low-level PMC from a high-level class makes an 318entry in the high-level class's list of parents. 319 320For PDD15 objects, there is a corresponding instance of the C<Class> 321PMC. For a low-level PMC, however, the class definition is written in C 322and compiled away. There needs to be something placed in the parents 323list for a PDD15 class, that can provide access to the low-level PMC's 324vtable and methods, and define the storage that the low-level PMC will 325need within the high-level object. That something is the C<PMCProxy> 326PMC. Like a PDD15 class, it is stored as the C<class> element in the 327namespace associated with a PMC, provides introspection facilities and 328can sit in an inheritance hierarchy. 329 330The PMCProxy PMCs are only created when needed for subclassing a low-level 331PMC, to avoid a large load of unused PMCProxy objects. When created, they are 332cached in the class slot of the namespace corresponding to the low-level PMC, 333so they are only created once. 334 335Therefore, subclassing a PMC looks, at a PIR level, like subclassing a high 336level class. 337 338=begin PIR_FRAGMENT 339 340 $P0 = get_class 'Hash' 341 $P1 = newclass 'MyClass' 342 addparent $P1, $P0 # The new class inherits from the Hash PMC 343 344=end PIR_FRAGMENT 345 346Or, more briefly: 347 348=begin PIR_FRAGMENT 349 350 $P1 = subclass 'Hash', 'MyClass' 351 352=end PIR_FRAGMENT 353 354PMCs store state in a very different way to PDD15 objects. When a method 355inherited from a PMC is called on a PDD15 object, that method needs to 356access the attributes of the inherited low-level PMC. Further, if 357multiple PMCs are inherited from, they may each have attributes with the 358same name, that need to be correctly "visible" to the PDD 15 object 359according to the laws of inheritance. Users of Parrot at a PIR level 360should not have to care about such issues. 361 362To enable attributes from the low-level PMC to act as full inherited 363attributes in the child class, the PMCProxy class will create a set of 364PDD 15 attributes that correspond in type and name to the attributes 365declared with C<ATTR> in the declaration body of the low-level PMC, as 366if each had been added with C<add_attribute>. It will also override the 367C<GET_ATTR_attrname> and C<SET_ATTR_attrname> functions to point to the 368PDD 15 attributes (with automatic boxing and unboxing for the PMC 369values) rather than to members of a C struct. 370 371The PMCProxy will also scan the low-level PMC for methods declared with 372C<METHOD> and insert them in the proxy class as if each had been 373declared with C<add_method> (possibly with a shim to standardize calling 374conventions, but hopefully the calling conventions are similar enough 375between C-defined and PIR-defined methods not to need a shim). The 376PMCProxy will maintain a link to the low-level PMC's vtable, and use it 377for any vtable calls that aren't overridden by the proxy class itself. 378 379As a result, a low-level PMC used as a parent of a PDD 15 class will 380never be instantiated directly. It will only be used as a source for 381attribute names and types, methods, and a vtable. 382 383When a method is called on an object whose class has low-level PMC 384parents, the call is made exactly as it would be for PDD 15 parents. The 385invocant is always the PDD 15 object. Any method or vtable calls made 386within the low-level PMC are dispatched on the PDD 15 object invocant. 387This allows the PDD 15 object to intelligently handle method and vtable 388overrides within multiple parents and itself. 389 390If a low-level PMC expects to be overridden by high-level classes (which 391means all the core low-level PMC types), it must respect the standard 392interface. 393 394 395=head2 Definitions 396 397=head3 Vtable Functions 398 399Vtables decouple the interface and implementation of various object functions. 400The actual vtable structure contains pointers to functions that implement the 401methods for that particular PMC. All pointers must point to valid functions 402with appropriate prototypes. 403 404In C code, the first parameter to any vtable routine is the current 405interpreter. The second parameter is the PMC itself. 406 407The following list details each of the vtable functions, their prototypes, and 408their behavior. 409 410=head4 Core Vtable Functions 411 412=over 4 413 414=item init 415 416 void init(INTERP, PMC *self) 417 418Called when a PMC is first instantiated. It takes an unused PMC parameter and 419turns it into a PMC of the appropriate class. 420 421=item init_pmc 422 423 void init_pmc(INTERP, PMC *self, PMC *initializer) 424 425Alternative entry point called when a PMC is first instantiated. Accepts a 426PMC parameter used to initialize the given object. Interpretation of the PMC 427initializer is left open, each PMC is free to choose its own implementation. A 428null value passed as the initializer parameter is allowed. 429 430NOTE: It is strongly suggested that init_pmc(PMCNULL) be equivalent to 431init(), though there will of necessity be exceptions. 432 433=item init_init 434 435 void init_int(INTERP, PMC *self, INTVAL initializer) 436 437Alternative entry point called when a PMC is first instantiated. Accepts an 438integer parameter used to initialize the given object. Interpretation of the 439integer initializer is left open, each PMC is free to choose its own 440implementation. This is very useful for PMCs that require an integer size 441parameter and is used as such in FixedPMCArray and related. 442 443=item instantiate 444 445 PMC* instantiate(INTERP, PMC *self, PMC *init) 446 447Creates a new PMC object of the type of the class and calls init_pmc(), 448passing in the initialization argument, I<init>, which is usually a 449hash. This opcode is most often used with high-level classes, but 450low-level PMCs may instantiate an object of their own type. 451 452=item inspect 453 454 PMC* inspect(INTERP, PMC *self) 455 456Return a hash of all characteristics of the I<self> PMC available for 457introspection. 458 459 PMC* inspect_str(INTERP, PMC *self, STRING *what) 460 461Return a PMC value for one characteristic of the I<self> PMC, selected 462by string name. Returns PMCNULL if the characteristic doesn't exist. 463 464=item morph 465 466 void morph(INTERP, PMC *self, INTVAL type) 467 468Turn the PMC into a PMC of type I<type>. If the morphing can't be done in any 469reasonable way -- for instance if an integer is asked to turn into an Array -- 470then the PMC is first destroyed, then recreated as an empty PMC of the new 471type. 472 473This method is primarily used when the interpreter has need of coercing a PMC 474to a particular type, and isn't meant as a general purpose casting tool. 475Compilers should only emit valid morphing operations. 476 477=item mark 478 479 void mark(INTERP, PMC *self) 480 481Called when the GC is tracing live PMCs. If this method is called then the 482code must mark all strings and PMCs that it contains as live, otherwise they 483may be collected. 484 485This method is only called if the GC has detected that this PMC is both alive 486and has a custom mark routine as indicated by the custom mark PMC flag. (Most 487normal PMCs don't need a custom mark routine.) 488 489If a PMC has this flag set, then it is responsible for marking all buffers and 490PMCs under its control as alive. If it does not, those PMCs or buffers may be 491collected later. This method does I<not> have to call the C<mark> method on 492any PMCs it marks--the GC system takes care of that. (So no need to recurse 493into aggregate PMCs or anything of the sort). 494 495This method may allocate no memory from Parrot, nor may it alter Parrot's 496internal structures. It should have no side-effects from the C level either. 497This routine may not throw an exception. 498 499=item destroy 500 501 void destroy(INTERP, PMC *self) 502 503Called when the PMC is destroyed. This method is called by the GC when it 504determines that a PMC is dead and that the PMC has marked itself as having a 505destroy method (an active finalizer). 506 507When this method finishes, the PMC will be marked as dead. As such you should 508make sure that you don't leave any references to it in any Parrot structure 509by the end of the method. 510 511This method may not throw an exception. It will be ignored if it does. 512 513=item clone 514 515 PMC* clone(INTERP, PMC *self) 516 517Return a clone of a PMC. 518 519=item defined 520 521 INTVAL defined(INTERP, PMC *self) 522 523Return a true value if the PMC is defined, false otherwise. 524 525=item get_class 526 527 PMC* get_class(INTERP, PMC *self) 528 529Return the class object for this PMC. For high-level objects, this is a 530C<Class> object (or other high-level class object). For low-level PMCs, 531this returns a C<PMCProxy> object. 532 533=item get_namespace 534 535 PMC* get_namespace(INTERP, PMC *self) 536 537Return the namespace object for this PMC. 538 539=item freeze 540 541 void freeze(INTERP, PMC *self, visit_info* info) 542 543Freeze the PMC to an archived string format (a bytecode string constant 544that can be saved in a packfile). 545 546=item thaw 547 548 void thaw (INTERP, PMC *self, visit_info* info) 549 550Thaw a PMC from an archived string format (a bytecode string constant 551that can be saved in a packfile). 552 553=item thawfinish 554 555 void thawfinish (INTERP, PMC *self, visit_info* info) 556 557Called after the PMC has been thawed to perform any finalization steps. 558 559=item visit 560 561 void visit (INTERP, PMC *self, visit_info* info) 562 563Used by C<freeze> and C<thaw> to visit the contents of the PMC. 564 565=item share 566 567 void share(INTERP, PMC *self) 568 569 PMC* share_ro(INTERP, PMC *self) 570 571Mark a PMC as shared and read-only. 572 573[NOTE: these seem to be used interchangeably, should be distinguished or 574merged.] 575 576=back 577 578=head4 Accessors 579 580=over 4 581 582=item getprop 583 584 PMC* getprop(INTERP, PMC *self, STRING *key) 585 586Return the value from the property hash of I<self> keyed by I<key>. The key 587should not be null. 588 589=item setprop 590 591 void setprop(INTERP, PMC *self, STRING *key, PMC *value) 592 593Set the value in the property hash of I<self> that is keyed by I<key> to the 594value of I<value>. The key should not be null. 595 596=item delprop 597 598 void delprop(INTERP, PMC *self, STRING *key) 599 600Delete the value from the property hash of I<self> keyed by I<key>. The key 601should not be null. 602 603=item getprops 604 605 PMC* getprops(INTERP, PMC *self) 606 607Return the entire property hash for I<self>. 608 609=item type 610 611 INTVAL type(INTERP, PMC *self) 612 613Return the type of the PMC. Type is a unique number associated with the PMC 614when the PMC's class is loaded. Negative numbers are considered 615interpreter-specific, non-public types. 616 617=item name 618 619 STRING* name(INTERP, PMC *self) 620 621Return the name of the class for the PMC. 622 623=item get_integer 624 625 INTVAL get_integer(INTERP, PMC *self) 626 627Return the native integer value of the PMC. 628 629=item get_number 630 631 FLOATVAL get_number(INTERP, PMC *self) 632 633Return the native floating-point value of the PMC. 634 635=item get_string 636 637 STRING* get_string(INTERP, PMC *self) 638 639Return the native string value of the PMC. This may be in any encoding, chosen 640by the PMC. 641 642=item get_repr 643 644 STRING* get_repr(INTERP, PMC *self) 645 646Return a string representation of the PMC. [NOTE: redundant with 647C<get_string>, candidate for deprecation.] 648 649=item get_bool 650 651 INTVAL get_bool(INTERP, PMC *self) 652 653Return the true/false value of the PMC (the constant TRUE or the constant 654FALSE). The definition of truth for a given PMC will depend on the type of the 655PMC. For a scalar, it may be as simple as returning false when the PMC has a 656value 0 or "", and returning true when the PMC has any other value. 657 658=item get_pmc 659 660 PMC* get_pmc(INTERP, PMC *self) 661 662Return the PMC value for this PMC. This is useful in circumstances where the 663thing being accessed may return something other than its own value. For 664example, an array might return a reference to itself. Any PMC may return a 665value different from the PMC that C<get_pmc> is being called on. 666 667=item set_integer_native 668 669 void set_integer_native(INTERP, PMC *self, INTVAL value) 670 671Set the integer value of this PMC from a native integer value (integer 672register/constant). 673 674=item set_integer_same 675 676 void set_integer_same(INTERP, PMC *self, PMC *value) 677 678Set the value of this PMC from the integer value of another PMC. The value PMC 679is guaranteed to be of the same type as the I<self> PMC, so optimizations may 680be made. 681 682=item set_number_native 683 684 void set_number_native(INTERP, PMC *self, FLOATVAL value) 685 686Set the value of this PMC from a native floating-point value (float 687register/constant). 688 689=item set_number_same 690 691 void set_number_same(INTERP, PMC *self, PMC *value) 692 693Set the value of this PMC from the floating-point value another PMC. The value 694PMC is guaranteed to be of the same type as the I<self> PMC, so optimizations 695may be made. 696 697=item get_pointer 698 699 void* get_pointer(INTERP, PMC *self) 700 701Returns a pointer value for the PMC. Useful for PMCs that hold pointers to 702arbitrary data. The details of the data (type, location etc.) depend on the 703PMC. 704 705=item set_bignum_int 706 707 void set_bignum_int(INTERP, PMC *self, INTVAL value) 708 709Morph the PMC to a BIGNUM PMC, and set the extended-precision value from a 710native integer. 711 712=item set_string_native 713 714 void set_string_native(INTERP, PMC *self, STRING *value) 715 716Set the value of this PMC from a native string value (string 717register/constant). 718 719=item assign_string_native 720 721 void assign_string_native(INTERP, PMC *self, STRING *value) 722 723Set the value of this PMC to a copied native string value (string 724register/constant). 725 726=item set_string_same 727 728 void set_string_same(INTERP, PMC *self, PMC *value) 729 730Set the value of this PMC from the string value of another PMC. The value PMC 731is guaranteed to be of the same type as the I<self> PMC, so optimizations may 732be made. 733 734=item set_bool 735 736 void set_bool(INTERP, PMC *self, INTVAL value) 737 738Set the boolean state of the PMC to TRUE if the native integer value passed in 739is TRUE, or FALSE if the value is FALSE. The definition of truth is left open 740to the particular PMC. For a scalar, it may be as simple as setting false when 741a 0 value is passed in, and setting true when any other value is passed in. 742 743=item assign_pmc 744 745 void assign_pmc(INTERP, PMC *self, PMC *value) 746 747Set the value of the PMC in I<self> to the value of the PMC in I<value> by 748copying the value. 749 750=item set_pmc 751 752 void set_pmc(INTERP, PMC *self, PMC *value) 753 754Make the PMC in I<self> refer to the PMC passed as I<value>. 755 756=item set_pointer 757 758 void set_pointer(INTERP, PMC *self, void* value) 759 760Set the pointer value of the PMC Useful for PMCs that hold pointers to 761arbitrary data. The details of the data (type, location etc.) depend on the 762PMC. 763 764=back 765 766=head4 Aggregate Vtable Functions 767 768Many of the following functions have a *_keyed form, a *_keyed_int form, and a 769*_keyed_str form. The keyed forms take a PMC *, INTVAL, or STRING * key as a 770parameter. The PMC * parameter is null (PMCNULL) if there is no key for that 771PMC; this means that that argument is unkeyed. 772 773In some cases, the caller must provide a non-null key. Those cases are 774explicitly stated below. In the other cases, you may have to implement the 775keyed vtable functions and check for a null I<self> key even if you are 776implementing a non-aggregate type. If the I<self> key is non-null and the PMC 777class is a non-aggregate type, the _keyed_* methods should throw an exception. 778 779If you do not implement the *_keyed_int and *_keyed_str functions, the default 780will convert the INTVAL or STRING * into a key PMC * and call the 781corresponding *_keyed functions. 782 783=over 4 784 785=item elements 786 787 INTVAL elements(INTERP, PMC *self) 788 789Return the number of elements in the PMC. 790 791=item get_integer_keyed 792 793 INTVAL get_integer_keyed(INTERP, PMC *self, PMC *key) 794 INTVAL get_integer_keyed_int(INTERP, PMC *self, INTVAL key) 795 INTVAL get_integer_keyed_str(INTERP, PMC *self, STRING *key) 796 797Return the integer value for the element indexed by a PMC, integer, or string 798key. The key is guaranteed not to be null for this function. 799 800=item get_number_keyed 801 802 FLOATVAL get_number_keyed(INTERP, PMC *self, PMC *key) 803 FLOATVAL get_number_keyed_int(INTERP, PMC *self, INTVAL key) 804 FLOATVAL get_number_keyed_str(INTERP, PMC *self, STRING *key) 805 806Return the native floating-point value for the element indexed by a PMC, 807integer, or string key. The key is guaranteed not to be null for this 808function. 809 810=item get_string_keyed 811 812 STRING* get_string_keyed(INTERP, PMC *self, PMC *key) 813 STRING* get_string_keyed_int(INTERP, PMC *self, INTVAL key) 814 STRING* get_string_keyed_str(INTERP, PMC *self, STRING *key) 815 816Return the string value for the element indexed by a PMC, integer, or string 817key. The key is guaranteed not to be null for this function. 818 819=item get_pmc_keyed 820 821 PMC* get_pmc_keyed(INTERP, PMC *self, PMC *key) 822 PMC* get_pmc_keyed_int(INTERP, PMC *self, INTVAL key) 823 PMC* get_pmc_keyed_str(INTERP, PMC *self, STRING *key) 824 825Return the PMC value for the element indexed by a PMC, integer, or 826string key. The key is guaranteed not to be null for this function. 827 828=item get_pointer_keyed 829 830 void* get_pointer_keyed(INTERP, PMC *self, PMC *key) 831 void* get_pointer_keyed_int(INTERP, PMC *self, INTVAL key) 832 void* get_pointer_keyed_str(INTERP, PMC *self, STRING *key) 833 834Return the pointer value for the element indexed by a PMC, integer, or 835string key. The details of the data (type, location etc.) depend on the 836PMC. 837 838=item set_integer_keyed 839 840 void set_integer_keyed(INTERP, PMC *self, PMC *key, INTVAL value) 841 void set_integer_keyed_int(INTERP, PMC *self, INTVAL key, INTVAL value) 842 void set_integer_keyed_str(INTERP, PMC *self, STRING *key, INTVAL value) 843 844Set the integer value of the element indexed by a PMC, integer, or 845string key. The key is guaranteed not to be null for this function. 846 847=item set_number_keyed 848 849 void set_number_keyed(INTERP, PMC *self, PMC *key, FLOATVAL value) 850 void set_number_keyed_int(INTERP, PMC *self, INTVAL key, FLOATVAL value) 851 void set_number_keyed_str(INTERP, PMC *self, STRING *key, FLOATVAL value) 852 853Set the floating-point value of the element indexed by a PMC, integer, 854or string key. The key is guaranteed not to be null for this function. 855 856=item set_string_keyed 857 858 void set_string_keyed(INTERP, PMC *self, PMC *key, STRING *value) 859 void set_string_keyed_int(INTERP, PMC *self, INTVAL key, STRING *value) 860 void set_string_keyed_str(INTERP, PMC *self, STRING *key, STRING *value) 861 862Set the string value of the element indexed by a PMC, integer, or string 863key. The key is guaranteed not to be null for this function. 864 865=item set_pmc_keyed 866 867 void set_pmc_keyed(INTERP, PMC *self, PMC *key, PMC *value) 868 void set_pmc_keyed_int(INTERP, PMC *self, INTVAL key, PMC *value) 869 void set_pmc_keyed_str(INTERP, PMC *self, STRING *key, PMC *value) 870 871Set the PMC value of the element indexed by a PMC, integer, or string key by 872copying the value of another PMC. 873 874=item set_pointer_keyed 875 876 void set_pointer_keyed(INTERP, PMC *self, PMC *key, void* value) 877 void set_pointer_keyed_int(INTERP, PMC *self, INTVAL key, void* value) 878 void set_pointer_keyed_str(INTERP, PMC *self, STRING *key, void* value) 879 880Set the pointer value of the element indexed by a PMC, integer, or string key. 881 882=item pop_integer 883 884 INTVAL pop_integer(INTERP, PMC *self) 885 886Return the integer value of the last item on the list, removing that item. 887 888=item pop_float 889 890 FLOATVAL pop_float(INTERP, PMC *self) 891 892Return the floating-point value of the last item on the list, removing that 893item. 894 895=item pop_string 896 897 STRING* pop_string(INTERP, PMC *self) 898 899Return the string value of the last item on the list, removing that item. 900 901=item pop_pmc 902 903 PMC* pop_pmc(INTERP, PMC *self) 904 905Return the PMC value of the last item on the list, removing that item. 906 907=item push_integer 908 909 void push_integer(INTERP, PMC *self, INTVAL value) 910 911Add the passed in integer value to the end of the list. 912 913=item push_float 914 915 void push_float(INTERP, PMC *self, FLOATVAL value) 916 917Add the passed in floating-point number to the end of the list. 918 919=item push_string 920 921 void push_string(INTERP, PMC *self, STRING *value) 922 923Add the passed in string to the end of the list. 924 925=item push_pmc 926 927 void push_pmc(INTERP, PMC *self, PMC *value) 928 929Add the passed in PMC to the end of the list. 930 931=item shift_integer 932 933 INTVAL shift_integer(INTERP, PMC *self) 934 935Return the integer value of the first item on the list, removing that item. 936 937=item shift_float 938 939 FLOATVAL shift_float(INTERP, PMC *self) 940 941Return the floating-point value of the first item on the list, removing that 942item. 943 944=item shift_string 945 946 STRING* shift_string(INTERP, PMC *self) 947 948Return the string value of the first item on the list, removing that item. 949 950=item shift_pmc 951 952 PMC* shift_pmc(INTERP, PMC *self) 953 954Return the PMC value of the first item on the list, removing that item. 955 956=item unshift_integer 957 958 void unshift_integer(INTERP, PMC *self, INTVAL value) 959 960Add the passed in integer value to the beginning of the list. 961 962=item unshift_float 963 964 void unshift_float(INTERP, PMC *self, FLOATVAL value) 965 966Add the passed in floating-point number to the beginning of the list. 967 968=item unshift_string 969 970 void unshift_string(INTERP, PMC *self, STRING *value) 971 972Add the passed in string to the beginning of the list. 973 974=item unshift_pmc 975 976 void unshift_pmc(INTERP, PMC *self, PMC *value) 977 978Add the passed in PMC to the beginning of the list. 979 980=item splice 981 982 void splice(INTERP, PMC *self, PMC *value, INTVAL offset, INTVAL count) 983 984Replace some number of PMCs (specified by the integer I<count>) at 985offset I<offset> from the beginning of I<self> with the PMCs in the 986aggregate I<value>. 987 988=item exists_keyed 989 990 INTVAL exists_keyed(INTERP, PMC *self, PMC *key) 991 INTVAL exists_keyed_int(INTERP, PMC *self, INTVAL key) 992 INTVAL exists_keyed_str(INTERP, PMC *self, STRING *key) 993 994Check if the element indexed by a PMC, integer, or string key exists. 995 996=item defined_keyed 997 998 INTVAL defined_keyed(INTERP, PMC *self, PMC *key) 999 INTVAL defined_keyed_int(INTERP, PMC *self, INTVAL key) 1000 INTVAL defined_keyed_str(INTERP, PMC *self, STRING *key) 1001 1002Check if the element indexed by a PMC, integer, or string key is defined. 1003 1004=item delete_keyed 1005 1006 void delete_keyed(INTERP, PMC *self, PMC *key) 1007 void delete_keyed_int(INTERP, PMC *self, INTVAL key) 1008 void delete_keyed_str(INTERP, PMC *self, STRING *key) 1009 1010Delete the element indexed by a PMC, integer, or string key. 1011 1012=back 1013 1014=head4 Math Vtable Functions 1015 1016=over 4 1017 1018=item add 1019 1020 void add(INTERP, PMC *self, PMC *value, PMC *dest) 1021 void add_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1022 void add_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1023 1024 void i_add(INTERP, PMC *self, PMC *value) 1025 void i_add_int(INTERP, PMC *self, INTVAL value) 1026 void i_add_float(INTERP, PMC *self, FLOATVAL value) 1027 1028Add the value of I<self> to the value of a PMC, native integer, or native 1029floating-point number and store the result in a PMC I<dest>. Note that I<dest> 1030may be the same PMC as I<self>; in that case optimizations may be made. 1031The C<i_> variants perform an inplace operation, modifying the value of 1032I<self>. 1033 1034=item subtract 1035 1036 PMC* subtract(INTERP, PMC *self, PMC *value, PMC *dest) 1037 PMC* subtract_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1038 PMC* subtract_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1039 1040 void i_subtract(INTERP, PMC *self, PMC *value) 1041 void i_subtract_int(INTERP, PMC *self, INTVAL value) 1042 void i_subtract_float(INTERP, PMC *self, FLOATVAL value) 1043 1044Subtract the value of a PMC, native integer, or native floating-point number 1045from a PMC and store the result in I<dest>. If I<dest> is null create a result 1046PMC of an appropriate type. Note that I<dest> may be the same PMC as I<self>; 1047in that case optimizations may be made. The C<i_> variants perform an 1048inplace operation, modifying the value of I<self>. 1049 1050=item increment 1051 1052 void increment(INTERP, PMC *self) 1053 1054Increment the value of a PMC by 1. 1055 1056=item decrement 1057 1058 void decrement(INTERP, PMC *self) 1059 1060Decrement the value of a PMC by 1. 1061 1062=item multiply 1063 1064 void multiply(INTERP, PMC *self, PMC *value, PMC *dest) 1065 void multiply_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1066 void multiply_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1067 1068 void i_multiply(INTERP, PMC *self, PMC *value) 1069 void i_multiply_int(INTERP, PMC *self, INTVAL value) 1070 void i_multiply_float(INTERP, PMC *self, FLOATVAL value) 1071 1072Multiply a PMC, native integer, or floating-point value by the value of the 1073PMC I<self> and store the result in the I<dest> PMC. Note that I<dest> may be 1074the same PMC as I<self>; in that case optimizations may be made. The C<i_> 1075variants perform an inplace operation, modifying the value of I<self>. 1076 1077=item divide 1078 1079 void divide(INTERP, PMC *self, PMC *value, PMC *dest) 1080 void divide_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1081 void divide_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1082 1083 void i_divide(INTERP, PMC *self, PMC *value) 1084 void i_divide_int(INTERP, PMC *self, INTVAL value) 1085 void i_divide_float(INTERP, PMC *self, FLOATVAL value) 1086 1087Divide the value of the I<self> PMC by a PMC, native integer, or native 1088floating-point number and store the result in I<dest>. Note that I<dest> may 1089be the same PMC as I<self>; in that case optimizations may be made. The 1090C<i_> variants perform an inplace operation, modifying the value of 1091I<self>. 1092 1093=item floor_divide 1094 1095 PMC* floor_divide(INTERP, PMC *self, PMC *value, PMC *dest) 1096 PMC* floor_divide_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1097 PMC* floor_divide_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1098 1099 void i_floor_divide(INTERP, PMC *self, PMC *value) 1100 void i_floor_divide_int(INTERP, PMC *self, INTVAL value) 1101 void i_floor_divide_float(INTERP, PMC *self, FLOATVAL value) 1102 1103Divide the PMC's value number by I<value> and return the result in 1104I<dest>. The result is the C<floor()> of the division i.e. the next 1105whole integer towards -inf. If the denominator is zero, a 'Divide by 1106zero' exception is thrown. The C<i_> variants perform an inplace 1107operation, modifying the value of I<self>. 1108 1109=item modulus 1110 1111 void modulus(INTERP, PMC *self, PMC *value, PMC *dest) 1112 void modulus_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1113 void modulus_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1114 1115 void i_modulus(INTERP, PMC *self, PMC *value) 1116 void i_modulus_int(INTERP, PMC *self, INTVAL value) 1117 void i_modulus_float(INTERP, PMC *self, FLOATVAL value) 1118 1119Divide the value of the I<self> PMC by the value of a PMC, native integer, or 1120native floating-point number and store the remainder in I<dest>. Note that 1121I<dest> may be the same PMC as I<self>; in that case optimizations may be 1122made. The C<i_> variants perform an inplace operation, modifying the value of 1123I<self>. 1124 1125=item cmodulus 1126 1127 void cmodulus(INTERP, PMC *self, PMC *value, PMC *dest) 1128 void cmodulus_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1129 void cmodulus_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1130 1131 void i_cmodulus(INTERP, PMC *self, PMC *value) 1132 void i_cmodulus_int(INTERP, PMC *self, INTVAL value) 1133 void i_cmodulus_float(INTERP, PMC *self, FLOATVAL value) 1134 1135Divide the value of the I<self> PMC by the value of a PMC, native integer, or 1136native floating-point number and store the remainder in I<dest>. Note that 1137I<dest> may be the same PMC as I<self>; in that case optimizations may be 1138made. The C<i_> variants perform an inplace operation, modifying the value of 1139I<self>. 1140 1141Note that C<modulus> uses Knuth's "corrected mod" algorithm, as implemented in 1142F<src/utils.c>, while C<cmodulus> uses the C-style fmod function. 1143 1144=item pow 1145 1146 PMC* pow(INTERP, PMC *self, PMC *value, PMC *dest) 1147 PMC* pow_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1148 PMC* pow_float(INTERP, PMC *self, FLOATVAL value, PMC *dest) 1149 1150 void i_pow(INTERP, PMC *self, PMC *value) 1151 void i_pow_int(INTERP, PMC *self, INTVAL value) 1152 void i_pow_float(INTERP, PMC *self, FLOATVAL value) 1153 1154Return the value of I<self> raised to the power of I<value>. The C<i_> 1155variants perform an inplace operation, modifying the value of I<self>. 1156 1157=item absolute 1158 1159 PMC* absolute(INTERP, PMC *self, PMC *dest) 1160 void i_absolute(INTERP, PMC *self) 1161 1162Return the absolute value of I<self>. The C<i_> variant performs an 1163inplace operation, modifying the value of I<self>. 1164 1165=item neg 1166 1167 void neg(INTERP, PMC *self, PMC *dest) 1168 void i_neg(INTERP, PMC *self) 1169 1170Negate the sign of I<self> and store the result in I<dest>. Note that 1171I<self> and I<dest> may refer to the same PMC, in which case 1172optimizations may be made. The C<i_> variant performs an inplace 1173operation, modifying the value of I<self>. 1174 1175=back 1176 1177=head4 Logical Vtable Functions 1178 1179=over 4 1180 1181=item bitwise_or 1182 1183 void bitwise_or(INTERP, PMC *self, PMC *value, PMC *dest) 1184 void bitwise_or_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1185 void i_bitwise_or(INTERP, PMC *self, PMC *value) 1186 void i_bitwise_or_int(INTERP, PMC *self, INTVAL value) 1187 1188Calculate the bitwise-OR of the value of the I<self> PMC and the value of a 1189PMC or native integer and store the result in I<dest>. Note that I<dest> may 1190be the same PMC as I<self>; in that case optimizations may be made. 1191[Question: what happens when the I<self> and I<value> PMCs aren't integers?] 1192 1193The C<i_> variants perform an inplace operation and store the result in 1194I<self>. 1195 1196=item bitwise_and 1197 1198 PMC* bitwise_and(INTERP, PMC *self, PMC *value, PMC *dest) 1199 PMC* bitwise_and_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1200 void i_bitwise_and(INTERP, PMC *self, PMC *value) 1201 void i_bitwise_and_int(INTERP, PMC *self, INTVAL value) 1202 1203Return the result of a bitwise AND on the passed in I<value> and the I<self> 1204PMC. The C<i_> variants perform an inplace operation and store the result in 1205I<self>. 1206 1207=item bitwise_xor 1208 1209 PMC* bitwise_xor(INTERP, PMC *self, PMC *value, PMC *dest) 1210 PMC* bitwise_xor_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1211 void i_bitwise_xor(INTERP, PMC *self, PMC *value) 1212 void i_bitwise_xor_int(INTERP, PMC *self, INTVAL value) 1213 1214Return the result of a bitwise XOR on the passed in I<value> and the I<self> 1215PMC. The C<i_> variants perform an inplace operation and store the result in 1216I<self>. 1217 1218=item bitwise_ors 1219 1220 PMC* bitwise_ors(INTERP, PMC *self, PMC *value, PMC *dest) 1221 PMC* bitwise_ors_str(INTERP, PMC *self, STRING *value, PMC *dest) 1222 void i_bitwise_ors(INTERP, PMC *self, PMC *value) 1223 void i_bitwise_ors_str(INTERP, PMC *self, STRING *value) 1224 1225Return the result of a bitwise OR over an entire string on the passed in 1226I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation 1227and store the result in I<self>. 1228 1229=item bitwise_ands 1230 1231 PMC* bitwise_ands(INTERP, PMC *self, PMC *value, PMC *dest) 1232 PMC* bitwise_ands_str(INTERP, PMC *self, STRING *value, PMC *dest) 1233 void i_bitwise_ands(INTERP, PMC *self, PMC *value) 1234 void i_bitwise_ands_str(INTERP, PMC *self, STRING *value) 1235 1236Return the result of a bitwise AND over an entire string on the passed in 1237I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation 1238and store the result in I<self>. 1239 1240=item bitwise_xors 1241 1242 PMC* bitwise_xors(INTERP, PMC *self, PMC *value, PMC *dest) 1243 PMC* bitwise_xors_str(INTERP, PMC *self, STRING *value, PMC *dest) 1244 void i_bitwise_xors(INTERP, PMC *self, PMC *value) 1245 void i_bitwise_xors_str(INTERP, PMC *self, STRING *value) 1246 1247Return the result of a bitwise XOR over an entire string on the passed in 1248I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation 1249and store the result in I<self>. 1250 1251=item bitwise_not 1252 1253 PMC* bitwise_not(INTERP, PMC *self, PMC *dest) 1254 void i_bitwise_not(INTERP, PMC *self) 1255 1256Returns the bitwise negation of the I<self> PMC. The C<i_> variant performs an 1257inplace operation, storing the result in I<self>. 1258 1259=item bitwise_nots 1260 1261 PMC* bitwise_nots(INTERP, PMC *self, PMC *dest) 1262 void i_bitwise_nots(INTERP, PMC *self) 1263 1264Returns the bitwise negation of the string I<self> PMC. The C<i_> variant 1265performs an inplace operation, storing the result in I<self>. 1266 1267=item bitwise_shl 1268 1269 PMC* bitwise_shl(INTERP, PMC *self, PMC *value, PMC *dest) 1270 PMC* bitwise_shl_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1271 void i_bitwise_shl(INTERP, PMC *self, PMC *value) 1272 void i_bitwise_shl_int(INTERP, PMC *self, INTVAL value) 1273 1274Return the value of the I<self> PMC bitwise shifted left by the amount 1275specified in I<value>, shifting in zeroes on the right (arithmetic/logical 1276bitwise shift). A negative I<value> shifts right. The C<i_> variants perform 1277an inplace operation, storing the result in I<self>. 1278 1279The result may be promoted to a C<BigInt>. 1280 1281=item bitwise_shr 1282 1283 PMC* bitwise_shr(INTERP, PMC *self, PMC *value, PMC *dest) 1284 PMC* bitwise_shr_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1285 void i_bitwise_shr(INTERP, PMC *self, PMC *value) 1286 void i_bitwise_shr_int(INTERP, PMC *self, INTVAL value) 1287 1288Return the value of the I<self> PMC bitwise shifted right by the amount 1289specified in I<value>, shifting in copies of the sign bit on the left 1290(arithmetic bitwise shift). A negative I<value> shifts left. The C<i_> 1291variants perform an inplace operation, storing the result in I<self>. 1292 1293The result may be promoted to a C<BigInt> (when I<value> is negative). 1294 1295=item bitwise_lsr 1296 1297 PMC* bitwise_lsr(INTERP, PMC *self, PMC *value, PMC *dest) 1298 PMC* bitwise_lsr_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1299 void i_bitwise_lsr(INTERP, PMC *self, PMC *value) 1300 void i_bitwise_lsr_int(INTERP, PMC *self, INTVAL value) 1301 1302Return the value of the I<self> PMC bitwise shifted right by the amount 1303specified in I<value>, shifting in zeroes on the left (logical bitwise shift). 1304A negative I<value> shifts left. The C<i_> variants perform an inplace 1305operation, storing the result in I<self>. 1306 1307=item is_equal 1308 1309 INTVAL is_equal(INTERP, PMC *self, PMC *value) 1310 INTVAL is_equal_num(INTERP, PMC *self, PMC *value) 1311 INTVAL is_equal_string(INTERP, PMC *self, PMC *value) 1312 1313Return an integer value (1/0) indicating if the I<self> PMC is equal to 1314the I<value> PMC. The C<_num> version tests for numeric equality, while 1315the C<_string> version tests for string equality. 1316 1317=item is_same 1318 1319 INTVAL is_same(INTERP, PMC *self, PMC *value) 1320 1321Return an integer value (1/0) indicating if I<self> is the same as 1322I<value> (with "sameness" determined by each PMC). 1323 1324=item cmp 1325 1326 INTVAL cmp(INTERP, PMC *self, PMC *value) 1327 INTVAL cmp_num(INTERP, PMC *self, PMC *value) 1328 INTVAL cmp_string(INTERP, PMC *self, PMC *value) 1329 1330Returns the integer result of comparing the values of I<self> and 1331I<value> (0 for equal, 1 if I<self> is greater, -1 if I<value> is 1332greater). The C<_num> version performs a numeric comparison, while the 1333C<_string> version performs a string comparison. 1334 1335=back 1336 1337=head4 String Vtable Functions 1338 1339=over 4 1340 1341=item concatenate 1342 1343 PMC* concatenate(INTERP, PMC *self, PMC *value, PMC *dest) 1344 PMC* concatenate_str(INTERP, PMC *self, STRING *value, PMC *dest) 1345 void i_concatenate(INTERP, PMC *self, PMC *value) 1346 void i_concatenate_str(INTERP, PMC *self, STRING *value) 1347 1348Concatenate I<self> with a PMC or string value and return the result. 1349The C<i_> variant performs an inplace concatenation, modifying the value 1350of I<self>. 1351 1352=item repeat 1353 1354 PMC* repeat(INTERP, PMC *self, PMC *value, PMC *dest) 1355 PMC* repeat_int(INTERP, PMC *self, INTVAL value, PMC *dest) 1356 void i_repeat(INTERP, PMC *self, PMC *value) 1357 void i_repeat_int(INTERP, PMC *self, INTVAL value) 1358 1359Return the result of repeating the value in I<self> the number of times 1360indicated in I<value>. The C<i_> variants perform an inplace operation, 1361modifying the value of I<self>. 1362 1363=item substr 1364 1365 STRING* substr(INTERP, PMC *self, INTVAL offset, INTVAL length) 1366 1367Extracts the string starting at I<offset> with size I<length> and return 1368it as a PMC in I<dest> or as a string return value. 1369 1370=back 1371 1372=head4 Code Vtable Functions 1373 1374=over 4 1375 1376=item invoke 1377 1378 opcode_t* invoke(INTERP, PMC *self, void* next) 1379 1380Invoke the code object I<self>. 1381 1382=back 1383 1384=head4 Class/Object Vtable Functions 1385 1386=over 4 1387 1388=item can 1389 1390 INTVAL can(INTERP, PMC *self, STRING *method) 1391 1392Return a true value if the PMC has a method named I<method>, return 0 1393otherwise. 1394 1395=item isa 1396 1397 INTVAL isa(INTERP, PMC *self, STRING *classname) 1398 1399Return a true value if the PMC inherits from the class named 1400I<classname>, return 0 otherwise. 1401 1402=item does 1403 1404 INTVAL does(INTERP, PMC *self, STRING *role) 1405 1406Return a true value if the PMC C<does> (composes) or C<performs> 1407(satisfies the interface of) the role named I<role>, return 0 otherwise. 1408 1409=item get_attr 1410 1411 PMC* get_attr_str(INTERP, PMC *self, STRING *idx) 1412 1413Retrieve an attribute value from the PMC (instance object). 1414 1415=item set_attr 1416 1417 void set_attr_str(INTERP, PMC *self, STRING *idx, PMC *value) 1418 1419Store an attribute value in the PMC (instance object). 1420 1421=item add_parent 1422 1423 void add_parent(INTERP, PMC *self, PMC *parent) 1424 1425Add a parent to the PMC (class object), establishing an inheritance relation. 1426 1427=item remove_parent 1428 1429 void remove_parent(INTERP, PMC *self, PMC *parent) 1430 1431Remove a parent from a PMC (class object). 1432 1433Not all object metamodels will support removing parents. 1434 1435=item add_role 1436 1437 void add_role(INTERP, PMC *self, PMC *role) 1438 1439Add a role to the PMC (class object), establishing a composition relation. 1440 1441=item remove_role 1442 1443 void remove_role(INTERP, PMC *self, PMC *role) 1444 1445Remove a role from the PMC (class object). 1446 1447Not all object metamodels will support removing roles. 1448 1449=item add_attribute 1450 1451 void add_attribute(INTERP, PMC *self, STRING *name, PMC *type) 1452 1453Add an attribute to the PMC (class object). 1454 1455=item remove_attribute 1456 1457 void remove_attribute(INTERP, PMC *self, STRING *name) 1458 1459Remove an attribute from the PMC (class object). 1460 1461Not all object metamodels will support removing attributes. 1462 1463=item add_method 1464 1465 void add_method(INTERP, PMC *self, STRING *method_name, PMC *sub_pmc) 1466 1467Add a method to the PMC (class object). 1468 1469=item remove_method 1470 1471 void remove_method(INTERP, PMC *self, STRING *method_name) 1472 1473Remove a method from the PMC (class object). 1474 1475Not all object metamodels will support removing methods. 1476 1477=item add_vtable_override 1478 1479 void add_vtable_override(INTERP, PMC *self, STRING *vtable_name, 1480 PMC *sub_pmc) 1481 1482Add a vtable override to the PMC (class object). 1483 1484 void remove_vtable_override(INTERP, PMC *self, STRING *vtable_name) 1485 1486Remove a vtable override from the PMC (class object). 1487 1488=item find_method 1489 1490 PMC* find_method(INTERP, PMC *self, STRING *method_name) 1491 1492Return a subroutine PMC for the passed method name. This subroutine PMC may be 1493cached, so the method I<must> return an equivalent sub PMC each time, or be 1494capable of dealing with the returned sub PMCs being reused. [Why should it be 1495cached? Can you turn off caching? What if you want to override find_method to 1496generate methods on the fly?] 1497 1498=back 1499 1500 1501 1502=head3 Core PMCs 1503 1504Parrot has a number of core PMC types that all programs can guarantee will be 1505available to them. (With the possible exception of Parrot programs executing 1506on an embedded device or other restricted environment) 1507 1508=head4 Scalar types 1509 1510=over 4 1511 1512=item Undef 1513 1514This is the generic no-value type. It has a numeric value of zero, a string 1515value of empty string, and a boolean value of false. It will, on assignment, 1516turn itself into a PMC of the source type, or if assigned a basic type will 1517turn itself into one of the wrapper PMC types (detailed below) for the basic 1518types. 1519 1520=item Integer 1521 1522The PMC wrapper for Parrot's low-level integer type. Always an integer, with 1523other types auto-converted to an integer when stored into this PMC. The range 1524and behaviour of the Integer PMC is identical to the platform low-level 1525integer. 1526 1527The boolean value for an Integer is false if zero, otherwise true. 1528 1529Floating point, string, and bignum values assigned to an Integer PMC round to 1530the nearest integer. Floats, or strings which resolve to numbers, cap at the 1531platform maximum or minimum integer value. 1532 1533Integer PMCs take on a value of 1 if a boolean true is assigned, and a value 1534of 0 if a boolean false is assigned. 1535 1536If an out-of-range value is assigned to an Integer PMC, the PMC will throw an 1537exception if exact math is enabled. 1538 1539=item Float 1540 1541The PMC wrapper for Parrot's low-level floating-point type. Always a float, 1542with other types autoconverted to a float when stored into this PMC. 1543 1544The boolean value for a Float is false if exactly zero, otherwise true. 1545 1546When converted to an integer, floats round to the closest integer, capping at 1547the platform maximum or minimum integer value. 1548 1549When converting to a string, floats use the platform default snprintf format. 1550 1551=item String 1552 1553The PMC wrapper for Parrot's low-level string type. Always a simple string, 1554with other types autoconverted to a string when stored into this PMC. 1555 1556The boolean value for a String is false if empty or the string '0' (a one 1557character string holding a zero) otherwise true. This PMC autoconverts to an 1558integer or float when its integer or float value is fetched. 1559 1560=item Boolean 1561 1562A true/false value. Returns 0 for false, 1 for true when fetched as an 1563integer or float, empty string for false and '1' for true when fetched 1564as a string. 1565 1566=item BigInt 1567 1568An arbitrary precision integer. 1569 1570=item BigNum 1571 1572The PMC wrapper for Parrot's low-level BigNum type. 1573{{ NOTE: this type doesn't seem to exist. }} 1574 1575=item Complex 1576 1577A complex number, consisting of a real part and an imaginary part. 1578{{ NOTE: is this a complete and useful implementation of complex 1579numbers? }} 1580 1581=item Class 1582 1583The PMC for Parrot's class. 1584 1585=item Object 1586 1587The PMC for Parrot's base object type. 1588 1589=item Ref 1590 1591The PMC that represents a reference to another PMC. Delegates all functions to 1592the referred-to PMC. 1593 1594=item AggregateElementRef 1595 1596This PMC represents a reference to an element contained in an aggregate PMC 1597type, such as an array or hash. It is initialized with the key being 1598referenced and the aggregate PMC containing that key. 1599 1600Note that assigning to the reference PMC will be equivalent to a keyed set on 1601the referenced aggregate PMC - that is, it modifies the element rather than 1602doing a v-table call on the element itself. It is important to be aware of 1603this when assigning a PMC through this reference; it is not the same behaviour 1604as the Ref PMC. 1605 1606=item WeakRegisterRef 1607 1608This PMC represents a weak reference to a register. Should the reference live 1609beyond the context containing the register that it references, any attempt to 1610use the reference will throw an exception. 1611 1612A weak register reference can only be created by the C<register_ref> opcode. 1613Any assignment to the register will behave like a set instruction. That is, 1614when assigning a PMC using a WeakRegisterRef PMC, the register will be updated 1615to reference that PMC rather than calling the assign v-table call on the PMC 1616in that register. This is not the same behaviour as the Ref PMC. 1617 1618=item Exception 1619 1620The base class for all exceptions. Currently based on 1621C<ResizablePMCArray>, but that's likely to change. 1622 1623=back 1624 1625=head4 Array types 1626 1627Note that for the following types you can set the size of the array by using 1628the VTABLE_set_integer_native() function. Assigning an integer to the array 1629as a whole sets the array to that size. 1630 1631Size-changing operations (such as push, pop, shift, unshift, and splice) 1632on statically-sized arrays will throw an exception. 1633 1634ResizablePMCArray returns Undef for unset elements (so does the new 1635object model, because it uses ResizablePMCArray for storage), but Hash 1636returns PMCNULL. Standardize all core aggregate PMC types on the 1637singleton PMCNULL. 1638 1639=over 4 1640 1641=item Array 1642 1643The base class for all array types (a statically sized array for any 1644arbitrary type). New array types can be derived from the base Array. 1645In user code it is recommended to use one of the specific array types 1646below, rather than the base type. 1647 1648=item FixedBooleanArray 1649 1650A statically sized array which holds only Boolean values. 1651 1652=item ResizableBooleanArray 1653 1654A dynamically sized array which holds only Boolean values. 1655 1656=item FixedIntegerArray 1657 1658A statically sized array which holds only Integer values. 1659 1660=item ResizableIntegerArray 1661 1662A dynamically sized array which holds only Integer values. 1663 1664=item FixedFloatArray 1665 1666A statically sized array which holds only Float values. 1667 1668=item ResizableFloatArray 1669 1670A dynamically sized array which holds only Float values. 1671 1672=item FixedPMCArray 1673 1674A statically sized array which holds only PMC values. 1675 1676=item ResizablePMCArray 1677 1678A dynamically sized array which holds only PMC values. 1679 1680=item FixedStringArray 1681 1682A statically sized array which holds only String values. 1683 1684=item ResizableStringArray 1685 1686A dynamically sized array which holds only String values. 1687 1688=back 1689 1690=head4 Hash types 1691 1692=over 4 1693 1694=item Hash 1695 1696A container with key-value semantics. The values are PMCs. 1697 1698=item Env 1699 1700Env is a singleton PMC class, that is there is only one Env PMC in any 1701interpreter. This PMC gives access to the process' environment 1702variables--reading from it returns the value of the named process environment 1703variable, while writing to it sets the value of a process environment 1704variable. For example, to retrieve the current value of TERM (the terminal 1705type on most Unix systems): 1706 1707 new P1, 'Env' 1708 set S1, P1['TERM'] 1709 1710Note that an embedding system may override this behavior. 1711 1712=item NameSpace 1713 1714Stores one level of a namespace. Every slot in a namespace contains 1715either another namespace (the next level down), or a variable or 1716subroutine/method. 1717 1718=item OrderedHash 1719 1720A hash that also preserves the order of elements, providing the 1721interface of both a hash and an array. 1722 1723=item AddrRegistry 1724 1725Simulates reference counting for dead-object detection and garbage 1726collection. 1727 1728=back 1729 1730=head4 Subroutine types 1731 1732=over 4 1733 1734=item Sub 1735 1736A fundamental subroutine object, and base class for other subroutine 1737PMC types. 1738 1739=item Closure 1740 1741A closure: subroutine object plus captured lexical scope. 1742 1743=item Continuation 1744 1745A continuation: a subroutine object that captures the interpreter's 1746context at the point where the continuation was constructed. 1747 1748=item Coroutine 1749 1750A coroutine: a continuation object that can stop part way through 1751execution and restart at the point where it left off the next time it's 1752called. 1753 1754=item Eval 1755 1756An extension of C<Sub> that provides dynamic code evaluation and 1757execution. 1758 1759=item ExceptionHandler 1760 1761A code object for handling exceptions. 1762 1763=item MultiSub 1764 1765A container for multiply dispatched subroutines. 1766 1767=item NCI 1768 1769A native call interface wrapper around a C function. 1770 1771=item Bound_NCI 1772 1773An internal NCI method call bound to a particular call instance. 1774 1775=item Compiler 1776 1777A subroutine implementing a language compiler. (Derived from NCI.) 1778 1779=back 1780 1781=head2 References 1782 1783F<docs/pmc2c.pod> 1784 1785=cut 1786 1787__END__ 1788Local Variables: 1789 fill-column:78 1790End: 1791