1 # Copyright (C) 2001-2008, The Perl Foundation.
6 docs/pdds/pdd17_pmc.pod - Parrot Magic Cookies
14 This PDD describes the internal structure and behavior of the Parrot Magic
15 Cookie (PMC) data type.
19 PMCs implement all internal data types more complex than a simple integer,
20 float, or string, and also the data types of high-level languages. Nothing
21 outside the core of Parrot (in fact, nothing outside the data type's vtable
22 routines) should infer anything about a PMC (hence the Magic part).
24 This does mean, though, that you need to either know what functions are
25 available and what they do, or have some method of finding out. Parrot defines
26 a standard set of functions that each PMC provides. More complex features are
27 constructed out of these fundamental building blocks.
33 =item - PMCs contain both state and behavior
35 =item - PMCs can inherit from other PMCs
37 =item - PMCs can be composed of low-level roles
39 =item - High-level objects can subclass low-level PMCs
46 =head2 Internal structure
48 All PMCs have the form:
55 struct PMC_EXT *pmc_ext;
58 where C<cache> is a C<UnionVal> union:
60 typedef union UnionVal {
66 DPOINTER* _struct_val;
74 struct parrot_string_t * _string_val;
77 C<u> holds data associated with the PMC. This can be in the form of an integer
78 value, a floating-point value, a string value, or a pointer to other data.
79 C<u> may be empty, since the PMC structure also provides a more general data
80 pointer, but is useful for PMCs which hold only a single piece of data (e.g.
83 C<flags> holds a set of flags associated with the PMC; these are documented
84 in F<include/parrot/pobj.h>, and are generally only used within the Parrot
87 C<vtable> holds a pointer to the B<vtable> associated with the PMC. This
88 points to a set of functions, with interfaces described in L<Vtable Functions>
89 that implement the basic behaviour of the PMC (i.e. how it behaves under
90 addition, subtraction, cloning etc.)
92 C<data> holds a pointer to the core data associated with the PMC. This
95 C<pmc_ext> points to an extended PMC structure. This has the form:
99 struct _Sync *_synchronize; # [Note: may be deprecated, see STM]
103 C<_metadata> holds internal PMC metadata. The specification for this has not
106 C<_synchronize> is for access synchronization between shared PMCs.
108 C<_next_for_GC> determines the next PMC in the 'used' list during dead object
111 PMCs are not required to have a C<PMC_EXT> structure (i.e. C<pmc_ext> can be
114 PMCs are used to implement the basic data types of the high level languages
115 running on top of Parrot. For instance, a Perl 5 C<SV> will map onto one (or
116 more) types of PMC, while particular Python datatypes will map onto different
121 PMCs are declared by the C<pmclass> keyword:
123 pmclass <name> [ <modifier> ... ] {
126 The modifiers specify core features, such as:
132 Adds the C<PMC_EXT> structure when instantiating the PMC.
136 The PMC cannot be instantiated. (By convention, abstract classes are given
141 Don't generate class initialization code (don't set up a vtable for the PMC).
142 Used with C<abstract>.
146 The PMC is a dynamic PMC, so generate special class initialization code
147 suitable for dynamic loading at runtime.
151 The PMC is a singleton, created in the constant PMC pool.
155 Don't create a second read-only vtable for the PMC. (Used, for example,
156 by STM's C<share_ro()>.)
160 The PMC is shared (across threads).
164 Inherit from another PMC. Takes one argument, the name of the PMC to inherit
169 Compose a role. Takes one argument, the name of the role to compose. [NOTE:
170 this modifier has been taken from the older feature C<does> which is now
175 Resolve a conflicting vtable function, method, or attribute from a composed
176 role by using the same named vtable function, method, or attribute from the
177 current C<pmclass> or C<prole>.
181 The PMC satisfies a particular low-level interface, which gives some
182 assurances on how and where a PMC can be used.
184 Roles composed with C<does> may also define C<provides> for one or more
185 interfaces. (They generally define at least a C<provides> corresponding
190 =item * C<array> is an aggregate PMC with numerically-keyed elements
192 =item * C<hash> is an aggregate PMC with string-keyed elements
194 =item * C<library> corresponds to a dynamic library
196 =item * C<ref> references another PMC
198 =item * C<string> behaves similarly to the base string type
200 =item * C<integer> behaves similarly to the base int type
202 =item * C<float> behaves similarly to the base number type
204 =item * C<boolean> does true/false only.
206 =item * C<scalar> (only used by the sample src/dynpmc/foo.pmc)
208 =item * C<event> can be used with event queue
214 Declare the PMC in an HLL namespace other than the default HLL 'parrot'.
215 Takes one argument, the name of the HLL.
219 Map the current PMC to a core PMC type for code declared in a particular
220 HLL. May only be used together with the C<hll> modifier.
224 =head3 Defining attributes
226 The attributes of a PMC (both public and private) live in a custom
227 struct for the PMC, stored in the C<data> member of the C<PMC> struct.
228 The standard way of declaring attributes is with C<ATTR> within the body
229 of a C<pmclass> or C<prole> declaration.
231 ATTR <type> <name> [ :<modifier> ... ];
233 This declaration is used to generate the data struct for the PMC (named
234 "Parrot_<pmcname>_Data"). The data struct incorporates any attributes declared
235 in a composed role or inherited class. Composed attributes are inserted at the
236 end of the generated struct. Inherited attributes are inserted at the top of
237 the generated struct, so the struct members shared by the parent and child are
238 in the same position, and code compiled for direct struct access to the parent
239 can also perform the same direct struct access on the child.
241 The declaration is also used to generate accessor macros, C<GET_ATTR_attrname>
242 and C<SET_ATTR_attrname>, to set up helper information for the C<inspect>
243 vtable function, and to provide attribute access through the default
244 C<get_attr> and C<set_attr> vtable functions.
246 It's also possible to define and store the PMC's data struct manually,
247 but the standard declaration syntax must be used in roles, in PMCs that
248 compose roles, and in PMCs that will be subclassed by high-level classes
249 (this means all core PMCs, and most non-core PMCs).
251 Low-level PMCs that use multiple inheritance (C<pmclass> declarations with
252 more than one C<extends> entry) have to be careful with the contents of their
253 structs. There's no problem if the two parents have identical data struct
254 members. But, if the two parents have different data struct members, any
255 vtable functions inherited from the parents will not be able to directly
256 access the parents' struct members or use the accessor macros. The solution is
257 to either override those vtable functions that directly access data struct
258 members in the child PMC, define the parents as roles instead of classes, or
259 declare the multiply inheriting child in PIR or an HLL.
261 =head3 Defining vtable functions
263 Vtable functions are defined as C functions within the body of the C<pmclass>
264 declaration, and are marked with C<VTABLE>.
266 VTABLE STRING *get_string() {...}
267 VTABLE void set_string_native(STRING *value) {...}
269 Within the body of vtable functions, several shortcuts are provided:
275 The current interpreter object.
279 The current invocant by dynamic type.
283 The current invocant by static type.
287 Calls the current method in the nearest superclass, using the dynamic
292 Calls the current method in the nearest superclass, using the static
299 Methods are declared in the body of the C<pmclass> or C<prole>
300 declaration with C<METHOD>.
302 METHOD inspect(STRING *what :optional, int got_what :opt_flag) {...}
304 =head2 PMCs and Namespaces
306 Like high-level classes, low-level PMCs are tied to a corresponding
307 namespace. By default this is a namespace with the same name as the PMC
308 in the 'parrot' HLL, but the C<hll> modifier in the C<pmclass>
309 declaration selects a different HLL.
311 Accessing a core PMC type from within an HLL other than 'parrot'
312 requires the same steps as accessing a class from another HLL, first
313 retrieving the namespace object, and then instantiating from that
316 $P0 = get_root_namespace ['parrot'; 'Integer']
319 HLLs can choose to provide direct access to Parrot's core PMC types by
320 aliasing them within the HLL namespace.
324 PMCs can inherit behavior and state from other PMCs. Inheritance is performed
325 in the C<pmclass> declaration using the C<extends> keyword.
327 pmclass Foo extends Bar {
332 Composition is another form of code reuse in PMCs. Unlike inheritance,
333 composed roles aren't complete stand-alone PMCs, they are just bundles of
334 behavior and state that can be used within the composing PMC. As such, roles
335 are never instantiated directly, and are never translated to C directly. They
336 have no core structs, though they define attributes to be added to the PMC
337 they are composed into.
339 When a PMC that uses a role is translated to C, the role provides vtable
340 functions, methods, and attributes that will be added to the generated C
341 code for that PMC. Composed vtable functions, methods, and attributes
342 are not permitted to have the same name as corresponding features
343 defined in the composing PMC. This is called a conflict, and must be
344 explicitly resolved in the composing PMC. When composed features have
345 the same name as inherited vtable functions, methods, or attributes, the
346 composed feature overrides the inherited feature, just as it would if
347 defined in the composing PMC.
349 Roles are defined using the C<prole> keyword.
351 prole <name> <modifiers> {
354 Roles can compose other roles, but they can't inherit.
356 Role attributes are defined using the same format as PMC attributes.
358 Core roles live in src/role and have a file extension of C<.pr>.
360 Roles are composed into a PMC with the C<does> modifier.
362 =head2 PMCs and high-level objects
364 High-level objects, as specified in PDD15, need to be able to inherit
365 from PMCs. Subclassing a low-level PMC from a high-level class makes an
366 entry in the high-level class's list of parents.
368 For PDD15 objects, there is a corresponding instance of the C<Class>
369 PMC. For a low-level PMC, however, the class definition is written in C
370 and compiled away. There needs to be something placed in the parents
371 list for a PDD15 class, that can provide access to the low-level PMC's
372 vtable and methods, and define the storage that the low-level PMC will
373 need within the high-level object. That something is the C<PMCProxy>
374 PMC. Like a PDD15 class, it is stored as the C<class> element in the
375 namespace associated with a PMC, provides introspection facilities and
376 can sit in an inheritance hierarchy.
378 The PMCProxy PMCs are only created when needed for subclassing a low-level
379 PMC, to avoid a large load of unused PMCProxy objects. When created, they are
380 cached in the class slot of the namespace corresponding to the low-level PMC,
381 so they are only created once.
383 Therefore, subclassing a PMC looks, at a PIR level, like subclassing a high
386 $P0 = get_class 'Hash'
387 $P1 = newclass 'MyClass'
388 addparent $P1, $P0 # The new class inherits from the Hash PMC
392 $P1 = subclass 'Hash', 'MyClass'
394 PMCs store state in a very different way to PDD15 objects. When a method
395 inherited from a PMC is called on a PDD15 object, that method needs to
396 access the attributes of the inherited low-level PMC. Further, if
397 multiple PMCs are inherited from, they may each have attributes with the
398 same name, that need to be correctly "visible" to the PDD 15 object
399 according to the laws of inheritance. Users of Parrot at a PIR level
400 should not have to care about such issues.
402 To enable attributes from the low-level PMC to act as full inherited
403 attributes in the child class, the PMCProxy class will create a set of
404 PDD 15 attributes that correspond in type and name to the attributes
405 declared with C<ATTR> in the declaration body of the low-level PMC, as
406 if each had been added with C<add_attribute>. It will also override the
407 C<GET_ATTR_attrname> and C<SET_ATTR_attrname> functions to point to the
408 PDD 15 attributes (with automatic boxing and unboxing for the PMC
409 values) rather than to members of a C struct.
411 The PMCProxy will also scan the low-level PMC for methods declared with
412 C<METHOD> and insert them in the proxy class as if each had been
413 declared with C<add_method> (possibly with a shim to standardize calling
414 conventions, but hopefully the calling conventions are similar enough
415 between C-defined and PIR-defined methods not to need a shim). The
416 PMCProxy will maintain a link to the low-level PMC's vtable, and use it
417 for any vtable calls that aren't overridden by the proxy class itself.
419 As a result, a low-level PMC used as a parent of a PDD 15 class will
420 never be instantiated directly. It will only be used as a source for
421 attribute names and types, methods, and a vtable.
423 When a method is called on an object whose class has low-level PMC
424 parents, the call is made exactly as it would be for PDD 15 parents. The
425 invocant is always the PDD 15 object. Any method or vtable calls made
426 within the low-level PMC are dispatched on the PDD 15 object invocant.
427 This allows the PDD 15 object to intelligently handle method and vtable
428 overrides within multiple parents and itself.
430 If a low-level PMC expects to be overridden by high-level classes (which
431 means all the core low-level PMC types), it must respect the standard
437 =head2 Vtable Functions
439 Vtables decouple the interface and implementation of various object functions.
440 The actual vtable structure contains pointers to functions that implement the
441 methods for that particular PMC. All pointers must point to valid functions
442 with appropriate prototypes.
444 In C code, the first parameter to any vtable routine is the current
445 interpreter. The second parameter is the PMC itself.
447 The following list details each of the vtable functions, their prototypes, and
450 =head3 Core Vtable Functions
456 void init(INTERP, PMC* self)
458 Called when a PMC is first instantiated. It takes an unused PMC parameter and
459 turns it into a PMC of the appropriate class.
463 void init_pmc(INTERP, PMC* self, PMC* initializer)
465 Alternative entry point called when a PMC is first instantiated. Accepts a
466 PMC parameter used to initialize the given object. Interpretation of the PMC
467 initializer is left open, each PMC is free to choose its own implemention. A
468 null value passed as the initializer parameter is allowed.
470 NOTE: It is strongly suggested that init_pmc(PMCNULL) be equivalent to
471 init(), though there will of necessity be exceptions.
475 PMC* instantiate(INTERP, PMC* self, PMC* init)
477 Creates a new PMC object of the type of the class and calls init_pmc(),
478 passing in the initialization argument, I<init>, which is usually a
479 hash. This opcode is most often used with high-level classes, but
480 low-level PMCs may instantiate an object of their own type.
482 =item new_from_string [deprecated: See RT# 47011]
484 PMC* new_from_string(INTERP, PMC* self, STRING* rep, INTVAL flags)
486 Construct a PMC initializing it from a string representation and integer
487 flags. [NOTE: this has been replaced by C<instantiate>. Any
488 initialization arguments can be passed in the I<init> hash.]
492 PMC* inspect(INTERP, PMC* self)
494 Return a hash of all characteristics of the I<self> PMC available for
497 PMC* inspect_str(INTERP, PMC* self, STRING* what)
499 Return a PMC value for one characteristic of the I<self> PMC, selected
500 by string name. Returns PMCNULL if the characteristic doesn't exist.
504 void morph(INTERP, PMC* self, INTVAL type)
506 Turn the PMC into a PMC of type I<type>. If the morphing can't be done in any
507 reasonable way -- for instance if an integer is asked to turn into an Array --
508 then the PMC is first destroyed, then recreated as an empty PMC of the new
511 This method is primarily used when the interpreter has need of coercing a PMC
512 to a particular type, and isn't meant as a general purpose casting tool.
513 Compilers should only emit valid morphing operations.
517 void mark(INTERP, PMC* self)
519 Called when the DOD is tracing live PMCs. If this method is called then the
520 code must mark all strings and PMCs that it contains as live, otherwise they
523 This method is only called if the DOD has detected that this PMC is both alive
524 and has a custom mark routine as indicated by the custom mark PMC flag. (Most
525 normal PMCs don't need a custom mark routine.)
527 If a PMC has this flag set, then it is responsible for marking all buffers and
528 PMCs under its control as alive. If it does not, those PMCs or buffers may be
529 collected later. This method does I<not> have to call the C<mark> method on
530 any PMCs it marks--the DOD system takes care of that. (So no need to recurse
531 into aggregate PMCs or anything of the sort).
533 This method may allocate no memory from Parrot, nor may it alter Parrot's
534 internal structures. It should have no side-effects from the C level either.
535 This routine may not throw an exception.
539 void destroy(INTERP, PMC* self)
541 Called when the PMC is destroyed. This method is called by the DOD when it
542 determines that a PMC is dead and that the PMC has marked itself as having a
543 destroy method (an active finalizer).
545 When this method finishes, the PMC will be marked as dead. As such you should
546 make sure that you don't leave any references to it in any Parrot structure
547 by the end of the method.
549 This method may not throw an exception. It will be ignored if it does.
553 PMC* clone(INTERP, PMC* self)
555 Return a clone of a PMC.
559 INTVAL defined(INTERP, PMC* self)
561 Return a true value if the PMC is defined, false otherwise.
565 PMC* get_class(INTERP, PMC* self)
567 Return the class object for this PMC. For high-level objects, this is a
568 C<Class> object (or other high-level class object). For low-level PMCs,
569 this returns a C<PMCProxy> object.
573 PMC* get_namespace(INTERP, PMC* self)
575 Return the namespace object for this PMC.
579 void freeze(INTERP, PMC* self, visit_info* info)
581 Freeze the PMC to an archived string format (a bytecode string constant
582 that can be saved in a packfile).
586 void thaw (INTERP, PMC* self, visit_info* info)
588 Thaw a PMC from an archived string format (a bytecode string constant
589 that can be saved in a packfile).
593 void thawfinish (INTERP, PMC* self, visit_info* info)
595 Called after the PMC has been thawed to perform any finalization steps.
599 void visit (INTERP, PMC* self, visit_info* info)
601 Used by C<freeze> and C<thaw> to visit the contents of the PMC.
605 void share(INTERP, PMC* self)
607 PMC* share_ro(INTERP, PMC* self)
609 Mark a PMC as shared and read-only.
611 [NOTE: these seem to be used interchangably, should be distinguished or
622 PMC* getprop(INTERP, PMC* self, STRING* key)
624 Return the value from the property hash of I<self> keyed by I<key>. The key
629 void setprop(INTERP, PMC* self, STRING* key, PMC* value)
631 Set the value in the property hash of I<self> that is keyed by I<key> to the
632 value of I<value>. The key should not be null.
636 void delprop(INTERP, PMC* self, STRING* key)
638 Delete the value from the property hash of I<self> keyed by I<key>. The key
643 PMC* getprops(INTERP, PMC* self)
645 Return the entire property hash for I<self>.
647 =item type [deprecated: See RT #48567]
649 INTVAL type(INTERP, PMC* self)
651 Return the type of the PMC. Type is a unique number associated with the PMC
652 when the PMC's class is loaded. Negative numbers are considered
653 interpreter-specific, non-public types.
657 STRING* name(INTERP, PMC* self)
659 Return the name of the class for the PMC.
663 INTVAL get_integer(INTERP, PMC* self)
665 Return the native integer value of the PMC.
669 FLOATVAL get_number(INTERP, PMC* self)
671 Return the native floating-point value of the PMC.
675 PMC* get_bignum(INTERP, PMC* self)
677 Return the extended precision numeric value of the PMC as a new bignum PMC.
681 STRING* get_string(INTERP, PMC* self)
683 Return the native string value of the PMC. This may be in any encoding, chosen
688 STRING* get_repr(INTERP, PMC* self)
690 Return a string representation of the PMC. [NOTE: redundant with
691 C<get_string>, candidate for deprecation.]
695 INTVAL get_bool(INTERP, PMC* self)
697 Return the true/false value of the PMC (the constant TRUE or the constant
698 FALSE). The definition of truth for a given PMC will depend on the type of the
699 PMC. For a scalar, it may be as simple as returning false when the PMC has a
700 value 0 or "", and returning true when the PMC has any other value.
704 PMC* get_pmc(INTERP, PMC* self)
706 Return the PMC value for this PMC. This is useful in circumstances where the
707 thing being accessed may return something other than its own value. For
708 example, an array might return a reference to itself. Any PMC may return a
709 value different from the PMC that C<get_pmc> is being called on.
711 =item set_integer_native
713 void set_integer_native(INTERP, PMC* self, INTVAL value)
715 Set the integer value of this PMC from a native integer value (integer
718 =item set_integer_same
720 void set_integer_same(INTERP, PMC* self, PMC* value)
722 Set the value of this PMC from the integer value of another PMC. The value PMC
723 is guaranteed to be of the same type as the I<self> PMC, so optimizations may
726 =item set_number_native
728 void set_number_native(INTERP, PMC* self, FLOATVAL value)
730 Set the value of this PMC from a native floating-point value (float
733 =item set_number_same
735 void set_number_same(INTERP, PMC* self, PMC* value)
737 Set the value of this PMC from the floating-point value another PMC. The value
738 PMC is guaranteed to be of the same type as the I<self> PMC, so optimizations
743 void* get_pointer(INTERP, PMC* self)
745 Returns a pointer value for the PMC. Useful for PMCs that hold pointers to
746 arbitrary data. The details of the data (type, location etc.) depend on the
751 void set_bignum_int(INTERP, PMC* self, INTVAL value)
753 Morph the PMC to a BIGNUM PMC, and set the extended-precision value from a
756 =item set_string_native
758 void set_string_native(INTERP, PMC* self, STRING* value)
760 Set the value of this PMC from a native string value (string
763 =item assign_string_native
765 void assign_string_native(INTERP, PMC* self, STRING* value)
767 Set the value of this PMC to a copied native string value (string
770 =item set_string_same
772 void set_string_same(INTERP, PMC* self, PMC* value)
774 Set the value of this PMC from the string value of another PMC. The value PMC
775 is guaranteed to be of the same type as the I<self> PMC, so optimizations may
780 void set_bool(INTERP, PMC* self, INTVAL value)
782 Set the boolean state of the PMC to TRUE if the native integer value passed in
783 is TRUE, or FALSE if the value is FALSE. The definition of truth is left open
784 to the particular PMC. For a scalar, it may be as simple as setting false when
785 a 0 value is passed in, and seting true when any other value is passed in.
789 void assign_pmc(INTERP, PMC* self, PMC* value)
791 Set the value of the PMC in I<self> to the value of the PMC in I<value> by
796 void set_pmc(INTERP, PMC* self, PMC* value)
798 Make the PMC in I<self> refer to the PMC passed as I<value>.
802 void set_pointer(INTERP, PMC* self, void* value)
804 Set the pointer value of the PMC Useful for PMCs that hold pointers to
805 arbitrary data. The details of the data (type, location etc.) depend on the
810 =head3 Aggregate Vtable Functions
812 Many of the following functions have a *_keyed form, a *_keyed_int form, and a
813 *_keyed_str form. The keyed forms take a PMC*, INTVAL, or STRING* key as a
814 parameter. The PMC* parameter is null (PMCNULL) if there is no key for that
815 PMC; this means that that argument is unkeyed.
817 In some cases, the caller must provide a non-null key. Those cases are
818 explicitly stated below. In the other cases, you may have to implement the
819 keyed vtable functions and check for a null I<self> key even if you are
820 implementing a non-aggregate type. If the I<self> key is non-null and the PMC
821 class is a non-aggregate type, the _keyed_* methods should throw an exception.
823 If you do not implement the *_keyed_int and *_keyed_str functions, the default
824 will convert the INTVAL or STRING* into a key PMC* and call the corresponding
831 INTVAL elements(INTERP, PMC* self)
833 Return the number of elements in the PMC.
835 =item get_integer_keyed
837 INTVAL get_integer_keyed(INTERP, PMC* self, PMC* key)
838 INTVAL get_integer_keyed_int(INTERP, PMC* self, INTVAL key)
839 INTVAL get_integer_keyed_str(INTERP, PMC* self, STRING* key)
841 Return the integer value for the element indexed by a PMC, integer, or string
842 key. The key is guaranteed not to be null for this function.
844 =item get_number_keyed
846 FLOATVAL get_number_keyed(INTERP, PMC* self, PMC* key)
847 FLOATVAL get_number_keyed_int(INTERP, PMC* self, INTVAL key)
848 FLOATVAL get_number_keyed_str(INTERP, PMC* self, STRING* key)
850 Return the native floating-point value for the element indexed by a PMC,
851 integer, or string key. The key is guaranteed not to be null for this
854 =item get_string_keyed
856 STRING* get_string_keyed(INTERP, PMC* self, PMC* key)
857 STRING* get_string_keyed_int(INTERP, PMC* self, INTVAL key)
858 STRING* get_string_keyed_str(INTERP, PMC* self, STRING* key)
860 Return the string value for the element indexed by a PMC, integer, or string
861 key. The key is guaranteed not to be null for this function.
865 PMC* get_pmc_keyed(INTERP, PMC* self, PMC* key)
866 PMC* get_pmc_keyed_int(INTERP, PMC* self, INTVAL key)
867 PMC* get_pmc_keyed_str(INTERP, PMC* self, STRING* key)
869 Return the PMC value for the element indexed by a PMC, integer, or
870 string key. The key is guaranteed not to be null for this function.
872 =item get_pointer_keyed
874 void* get_pointer_keyed(INTERP, PMC* self, PMC* key)
875 void* get_pointer_keyed_int(INTERP, PMC* self, INTVAL key)
876 void* get_pointer_keyed_str(INTERP, PMC* self, STRING* key)
878 Return the pointer value for the element indexed by a PMC, integer, or
879 string key. The details of the data (type, location etc.) depend on the
882 =item set_integer_keyed
884 void set_integer_keyed(INTERP, PMC* self, PMC* key, INTVAL value)
885 void set_integer_keyed_int(INTERP, PMC* self, INTVAL key, INTVAL value)
886 void set_integer_keyed_str(INTERP, PMC* self, STRING* key, INTVAL value)
888 Set the integer value of the element indexed by a PMC, integer, or
889 string key. The key is guaranteed not to be null for this function.
891 =item set_number_keyed
893 void set_number_keyed(INTERP, PMC* self, PMC* key, FLOATVAL value)
894 void set_number_keyed_int(INTERP, PMC* self, INTVAL key, FLOATVAL value)
895 void set_number_keyed_str(INTERP, PMC* self, STRING* key, FLOATVAL value)
897 Set the floating-point value of the element indexed by a PMC, integer,
898 or string key. The key is guaranteed not to be null for this function.
900 =item set_string_keyed
902 void set_string_keyed(INTERP, PMC* self, PMC* key, STRING* value)
903 void set_string_keyed_int(INTERP, PMC* self, INTVAL key, STRING* value)
904 void set_string_keyed_str(INTERP, PMC* self, STRING* key, STRING* value)
906 Set the string value of the element indexed by a PMC, integer, or string
907 key. The key is guaranteed not to be null for this function.
911 void set_pmc_keyed(INTERP, PMC* self, PMC* key, PMC* value)
912 void set_pmc_keyed_int(INTERP, PMC* self, INTVAL key, PMC* value)
913 void set_pmc_keyed_str(INTERP, PMC* self, STRING* key, PMC* value)
915 Set the PMC value of the element indexed by a PMC, integer, or string key by
916 copying the value of another PMC.
918 =item set_pointer_keyed
920 void set_pointer_keyed(INTERP, PMC* self, PMC* key, void* value)
921 void set_pointer_keyed_int(INTERP, PMC* self, INTVAL key, void* value)
922 void set_pointer_keyed_str(INTERP, PMC* self, STRING* key, void* value)
924 Set the pointer value of the element indexed by a PMC, integer, or string key.
926 =item type_keyed [deprecated: see individual tickets below]
928 INTVAL type_keyed(INTERP, PMC* self, PMC* key) [RT #48577]
929 INTVAL type_keyed_int(INTERP, PMC* self, INTVAL key) [RT #48579]
930 INTVAL type_keyed_str(INTERP, PMC* self, STRING* key) [RT #48581]
932 Return the type number of the PMC indexed by a PMC, integer, or string key.
933 The I<key> parameter is guaranteed not to be null for this method.
937 INTVAL pop_integer(INTERP, PMC* self)
939 Return the integer value of the last item on the list, removing that item.
943 FLOATVAL pop_float(INTERP, PMC* self)
945 Return the floating-point value of the last item on the list, removing that
950 STRING* pop_string(INTERP, PMC* self)
952 Return the string value of the last item on the list, removing that item.
956 PMC* pop_pmc(INTERP, PMC* self)
958 Return the PMC value of the last item on the list, removing that item.
962 void push_integer(INTERP, PMC* self, INTVAL value)
964 Add the passed in integer value to the end of the list.
968 void push_float(INTERP, PMC* self, FLOATVAL value)
970 Add the passed in floating-point number to the end of the list.
974 void push_string(INTERP, PMC* self, STRING* value)
976 Add the passed in string to the end of the list.
980 void push_pmc(INTERP, PMC* self, PMC* value)
982 Add the passed in PMC to the end of the list.
986 INTVAL shift_integer(INTERP, PMC* self)
988 Return the integer value of the first item on the list, removing that item.
992 FLOATVAL shift_float(INTERP, PMC* self)
994 Return the floating-point value of the first item on the list, removing that
999 STRING* shift_string(INTERP, PMC* self)
1001 Return the string value of the first item on the list, removing that item.
1005 PMC* shift_pmc(INTERP, PMC* self)
1007 Return the PMC value of the first item on the list, removing that item.
1009 =item unshift_integer
1011 void unshift_integer(INTERP, PMC* self, INTVAL value)
1013 Add the passed in integer value to the beginning of the list.
1017 void unshift_float(INTERP, PMC* self, FLOATVAL value)
1019 Add the passed in floating-point number to the beginning of the list.
1021 =item unshift_string
1023 void unshift_string(INTERP, PMC* self, STRING* value)
1025 Add the passed in string to the beginning of the list.
1029 void unshift_pmc(INTERP, PMC* self, PMC* value)
1031 Add the passed in PMC to the beginning of the list.
1035 void splice(INTERP, PMC* self, PMC* value, INTVAL offset, INTVAL count)
1037 Replace some number of PMCs (specified by the integer I<count>) at
1038 offset I<offset> from the beginning of I<self> with the PMCs in the
1043 INTVAL exists_keyed(INTERP, PMC* self, PMC* key)
1044 INTVAL exists_keyed_int(INTERP, PMC* self, INTVAL key)
1045 INTVAL exists_keyed_str(INTERP, PMC* self, STRING* key)
1047 Check if the element indexed by a PMC, integer, or string key exists.
1051 INTVAL defined_keyed(INTERP, PMC* self, PMC* key)
1052 INTVAL defined_keyed_int(INTERP, PMC* self, INTVAL key)
1053 INTVAL defined_keyed_str(INTERP, PMC* self, STRING* key)
1055 Check if the element indexed by a PMC, integer, or string key is defined.
1059 void delete_keyed(INTERP, PMC* self, PMC* key)
1060 void delete_keyed_int(INTERP, PMC* self, INTVAL key)
1061 void delete_keyed_str(INTERP, PMC* self, STRING* key)
1063 Delete the element indexed by a PMC, integer, or string key.
1067 PMC* nextkey_keyed(INTERP, PMC* self, PMC* key, INTVAL what)
1068 PMC* nextkey_keyed_int(INTERP, PMC* self, INTVAL key, INTVAL what)
1069 PMC* nextkey_keyed_str(INTERP, PMC* self, STRING* key, INTVAL what)
1071 Advance to the next position while iterating through an aggregate. [NOTE: this
1072 feature needs review together with the Iterator PMC.]
1076 =head3 Math Vtable Functions
1082 void add(INTERP, PMC* self, PMC* value, PMC* dest)
1083 void add_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1084 void add_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1086 void i_add(INTERP, PMC* self, PMC* value)
1087 void i_add_int(INTERP, PMC* self, INTVAL value)
1088 void i_add_float(INTERP, PMC* self, FLOATVAL value)
1090 Add the value of I<self> to the value of a PMC, native integer, or native
1091 floating-point number and store the result in a PMC I<dest>. Note that I<dest>
1092 may be the same PMC as I<self>; in that case optimizations may be made.
1093 The C<i_> variants perform an inplace operation, modifying the value of
1098 PMC* subtract(INTERP, PMC* self, PMC* value, PMC* dest)
1099 PMC* subtract_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1100 PMC* subtract_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1102 void i_subtract(INTERP, PMC* self, PMC* value)
1103 void i_subtract_int(INTERP, PMC* self, INTVAL value)
1104 void i_subtract_float(INTERP, PMC* self, FLOATVAL value)
1106 Subtract the value of a PMC, native integer, or native floating-point number
1107 from a PMC and store the result in I<dest>. If I<dest> is null create a result
1108 PMC of an appropriate type. Note that I<dest> may be the same PMC as I<self>;
1109 in that case optimizations may be made. The C<i_> variants perform an
1110 inplace operation, modifying the value of I<self>.
1114 void increment(INTERP, PMC* self)
1116 Increment the value of a PMC by 1.
1120 void decrement(INTERP, PMC* self)
1122 Decrement the value of a PMC by 1.
1126 void multiply(INTERP, PMC* self, PMC* value, PMC* dest)
1127 void multiply_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1128 void multiply_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1130 void i_multiply(INTERP, PMC* self, PMC* value)
1131 void i_multiply_int(INTERP, PMC* self, INTVAL value)
1132 void i_multiply_float(INTERP, PMC* self, FLOATVAL value)
1134 Multiply a PMC, native integer, or floating-point value by the value of the
1135 PMC I<self> and store the result in the I<dest> PMC. Note that I<dest> may be
1136 the same PMC as I<self>; in that case optimizations may be made. The C<i_>
1137 variants perform an inplace operation, modifying the value of I<self>.
1141 void divide(INTERP, PMC* self, PMC* value, PMC* dest)
1142 void divide_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1143 void divide_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1145 void i_divide(INTERP, PMC* self, PMC* value)
1146 void i_divide_int(INTERP, PMC* self, INTVAL value)
1147 void i_divide_float(INTERP, PMC* self, FLOATVAL value)
1149 Divide the value of the I<self> PMC by a PMC, native integer, or native
1150 floating-point number and store the result in I<dest>. Note that I<dest> may
1151 be the same PMC as I<self>; in that case optimizations may be made. The
1152 C<i_> variants perform an inplace operation, modifying the value of
1157 PMC* floor_divide(INTERP, PMC* self, PMC* value, PMC* dest)
1158 PMC* floor_divide_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1159 PMC* floor_divide_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1161 void i_floor_divide(INTERP, PMC* self, PMC* value)
1162 void i_floor_divide_int(INTERP, PMC* self, INTVAL value)
1163 void i_floor_divide_float(INTERP, PMC* self, FLOATVAL value)
1165 Divide the PMC's value number by I<value> and return the result in
1166 I<dest>. The result is the C<floor()> of the division i.e. the next
1167 whole integer towards -inf. If the denominator is zero, a 'Divide by
1168 zero' exception is thrown. The C<i_> variants perform an inplace
1169 operation, modifying the value of I<self>.
1173 void modulus(INTERP, PMC* self, PMC* value, PMC* dest)
1174 void modulus_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1175 void modulus_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1177 void i_modulus(INTERP, PMC* self, PMC* value)
1178 void i_modulus_int(INTERP, PMC* self, INTVAL value)
1179 void i_modulus_float(INTERP, PMC* self, FLOATVAL value)
1181 Divide the value of the I<self> PMC by the value of a PMC, native integer, or
1182 native floating-point number and store the remainder in I<dest>. Note that
1183 I<dest> may be the same PMC as I<self>; in that case optimizations may be
1184 made. The C<i_> variants perform an inplace operation, modifying the value of
1189 void cmodulus(INTERP, PMC* self, PMC* value, PMC* dest)
1190 void cmodulus_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1191 void cmodulus_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1193 void i_cmodulus(INTERP, PMC* self, PMC* value)
1194 void i_cmodulus_int(INTERP, PMC* self, INTVAL value)
1195 void i_cmodulus_float(INTERP, PMC* self, FLOATVAL value)
1197 Divide the value of the I<self> PMC by the value of a PMC, native integer, or
1198 native floating-point number and store the remainder in I<dest>. Note that
1199 I<dest> may be the same PMC as I<self>; in that case optimizations may be
1200 made. The C<i_> variants perform an inplace operation, modifying the value of
1203 Note that C<modulus> uses Knuth's "corrected mod" algorithm, as implemented in
1204 F<src/utils.c>, while C<cmodulus> uses the C-style fmod function.
1208 PMC* pow(INTERP, PMC* self, PMC* value, PMC* dest)
1209 PMC* pow_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1210 PMC* pow_float(INTERP, PMC* self, FLOATVAL value, PMC* dest)
1212 void i_pow(INTERP, PMC* self, PMC* value)
1213 void i_pow_int(INTERP, PMC* self, INTVAL value)
1214 void i_pow_float(INTERP, PMC* self, FLOATVAL value)
1216 Return the value of I<self> raised to the power of I<value>. The C<i_>
1217 variants perform an inplace operation, modifying the value of I<self>.
1221 PMC* absolute(INTERP, PMC* self, PMC* dest)
1222 void i_absolute(INTERP, PMC* self)
1224 Return the absolute value of I<self>. The C<i_> variant performs an
1225 inplace operation, modifying the value of I<self>.
1229 void neg(INTERP, PMC* self, PMC* dest)
1230 void i_neg(INTERP, PMC* self)
1232 Negate the sign of I<self> and store the result in I<dest>. Note that
1233 I<self> and I<dest> may refer to the same PMC, in which case
1234 optimizations may be made. The C<i_> variant performs an inplace
1235 operation, modifying the value of I<self>.
1239 =head3 Logical Vtable Functions
1245 void bitwise_or(INTERP, PMC* self, PMC* value, PMC* dest)
1246 void bitwise_or_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1247 void i_bitwise_or(INTERP, PMC* self, PMC* value)
1248 void i_bitwise_or_int(INTERP, PMC* self, INTVAL value)
1250 Calculate the bitwise-OR of the value of the I<self> PMC and the value of a
1251 PMC or native integer and store the result in I<dest>. Note that I<dest> may
1252 be the same PMC as I<self>; in that case optimizations may be made.
1253 [Question: what happens when the I<self> and I<value> PMCs aren't integers?]
1255 The C<i_> variants perform an inplace operation and store the result in
1260 PMC* bitwise_and(INTERP, PMC* self, PMC* value, PMC* dest)
1261 PMC* bitwise_and_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1262 void i_bitwise_and(INTERP, PMC* self, PMC* value)
1263 void i_bitwise_and_int(INTERP, PMC* self, INTVAL value)
1265 Return the result of a bitwise AND on the passed in I<value> and the I<self>
1266 PMC. The C<i_> variants perform an inplace operation and store the result in
1271 PMC* bitwise_xor(INTERP, PMC* self, PMC* value, PMC* dest)
1272 PMC* bitwise_xor_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1273 void i_bitwise_xor(INTERP, PMC* self, PMC* value)
1274 void i_bitwise_xor_int(INTERP, PMC* self, INTVAL value)
1276 Return the result of a bitwise XOR on the passed in I<value> and the I<self>
1277 PMC. The C<i_> variants perform an inplace operation and store the result in
1282 PMC* bitwise_ors(INTERP, PMC* self, PMC* value, PMC* dest)
1283 PMC* bitwise_ors_str(INTERP, PMC* self, STRING* value, PMC* dest)
1284 void i_bitwise_ors(INTERP, PMC* self, PMC* value)
1285 void i_bitwise_ors_str(INTERP, PMC* self, STRING* value)
1287 Return the result of a bitwise OR over an entire string on the passed in
1288 I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation
1289 and store the result in I<self>.
1293 PMC* bitwise_ands(INTERP, PMC* self, PMC* value, PMC* dest)
1294 PMC* bitwise_ands_str(INTERP, PMC* self, STRING* value, PMC* dest)
1295 void i_bitwise_ands(INTERP, PMC* self, PMC* value)
1296 void i_bitwise_ands_str(INTERP, PMC* self, STRING* value)
1298 Return the result of a bitwise AND over an entire string on the passed in
1299 I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation
1300 and store the result in I<self>.
1304 PMC* bitwise_xors(INTERP, PMC* self, PMC* value, PMC* dest)
1305 PMC* bitwise_xors_str(INTERP, PMC* self, STRING* value, PMC* dest)
1306 void i_bitwise_xors(INTERP, PMC* self, PMC* value)
1307 void i_bitwise_xors_str(INTERP, PMC* self, STRING* value)
1309 Return the result of a bitwise XOR over an entire string on the passed in
1310 I<value> and the I<self> PMC. The C<i_> variants perform an inplace operation
1311 and store the result in I<self>.
1315 PMC* bitwise_not(INTERP, PMC* self, PMC* dest)
1316 void i_bitwise_not(INTERP, PMC* self)
1318 Returns the bitwise negation of the I<self> PMC. The C<i_> variant performs an
1319 inplace operation, storing the result in I<self>.
1323 PMC* bitwise_nots(INTERP, PMC* self, PMC* dest)
1324 void i_bitwise_nots(INTERP, PMC* self)
1326 Returns the bitwise negation of the string I<self> PMC. The C<i_> variant
1327 performs an inplace operation, storing the result in I<self>.
1331 PMC* bitwise_shl(INTERP, PMC* self, PMC* value, PMC* dest)
1332 PMC* bitwise_shl_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1333 void i_bitwise_shl(INTERP, PMC* self, PMC* value)
1334 void i_bitwise_shl_int(INTERP, PMC* self, INTVAL value)
1336 Return the value of the I<self> PMC bitwise shifted left by the amount
1337 specified in I<value>, shifting in zeroes on the right (arithmetic/logical
1338 bitwise shift). A negative I<value> shifts right. The C<i_> variants perform
1339 an inplace operation, storing the result in I<self>.
1341 The result may be promoted to a C<BigInt>.
1345 PMC* bitwise_shr(INTERP, PMC* self, PMC* value, PMC* dest)
1346 PMC* bitwise_shr_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1347 void i_bitwise_shr(INTERP, PMC* self, PMC* value)
1348 void i_bitwise_shr_int(INTERP, PMC* self, INTVAL value)
1350 Return the value of the I<self> PMC bitwise shifted right by the amount
1351 specified in I<value>, shifting in copies of the sign bit on the left
1352 (arithmetic bitwise shift). A negative I<value> shifts left. The C<i_>
1353 variants perform an inplace operation, storing the result in I<self>.
1355 The result may be promoted to a C<BigInt> (when I<value> is negative).
1359 PMC* bitwise_lsr(INTERP, PMC* self, PMC* value, PMC* dest)
1360 PMC* bitwise_lsr_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1361 void i_bitwise_lsr(INTERP, PMC* self, PMC* value)
1362 void i_bitwise_lsr_int(INTERP, PMC* self, INTVAL value)
1364 Return the value of the I<self> PMC bitwise shifted right by the amount
1365 specified in I<value>, shifting in zeroes on the left (logical bitwise shift).
1366 A negative I<value> shifts left. The C<i_> variants perform an inplace
1367 operation, storing the result in I<self>.
1371 INTVAL is_equal(INTERP, PMC* self, PMC* value)
1372 INTVAL is_equal_num(INTERP, PMC* self, PMC* value)
1373 INTVAL is_equal_string(INTERP, PMC* self, PMC* value)
1375 Return an integer value (1/0) indicating if the I<self> PMC is equal to
1376 the I<value> PMC. The C<_num> version tests for numeric equality, while
1377 the C<_string> version tests for string equality.
1381 INTVAL is_same(INTERP, PMC* self, PMC* value)
1383 Return an integer value (1/0) indicating if I<self> is the same as
1384 I<value> (with "sameness" determined by each PMC).
1388 INTVAL cmp(INTERP, PMC* self, PMC* value)
1389 INTVAL cmp_num(INTERP, PMC* self, PMC* value)
1390 INTVAL cmp_string(INTERP, PMC* self, PMC* value)
1392 Returns the integer result of comparing the values of I<self> and
1393 I<value> (0 for equal, 1 if I<self> is greater, -1 if I<value> is
1394 greater). The C<_num> version performs a numeric comparison, while the
1395 C<_string> version performs a string comparison.
1399 PMC* logical_or(INTERP, PMC* self, PMC* value, PMC* dest)
1401 Performs a logical OR, returning I<self> if it is true, and I<value>
1406 PMC* logical_and(INTERP, PMC* self, PMC* value, PMC* dest)
1408 Performs a logical AND, returning a true value if both I<self> and
1409 I<value> are true, and a false value otherwise. (Currently implemented
1410 as: If I<self> is false, return it, since the entire expression is
1411 false. If I<self> is true, return value, since the truth or falsehood of
1412 I<value> will determine the truth or falsehood of the whole expression.)
1416 PMC* logical_xor(INTERP, PMC* self, PMC* value, PMC* dest)
1418 Performs a logical XOR, returning I<self> if it is true and I<value> is
1419 false, returning I<value> if it is true and I<self> is false, and
1420 returning a false value (PMC of the same type as I<self>, with the
1421 boolean value 0) if both are true or neither are true.
1425 PMC* logical_not(INTERP, PMC* self, PMC* dest)
1426 void i_logical_not(INTERP, PMC* self)
1428 Returns the logical negation of I<self>. The C<i_> variant performs an
1429 inplace negation, modifying the value of I<self>.
1433 =head3 String Vtable Functions
1439 PMC* concatenate(INTERP, PMC* self, PMC* value, PMC* dest)
1440 PMC* concatenate_str(INTERP, PMC* self, STRING* value, PMC* dest)
1441 void i_concatenate(INTERP, PMC* self, PMC* value)
1442 void i_concatenate_str(INTERP, PMC* self, STRING* value)
1444 Concatenate I<self> with a PMC or string value and return the result.
1445 The C<i_> variant performs an inplace concatenation, modifying the value
1450 PMC* repeat(INTERP, PMC* self, PMC* value, PMC* dest)
1451 PMC* repeat_int(INTERP, PMC* self, INTVAL value, PMC* dest)
1452 void i_repeat(INTERP, PMC* self, PMC* value)
1453 void i_repeat_int(INTERP, PMC* self, INTVAL value)
1455 Return the result of repeating the value in I<self> the number of times
1456 indicated in I<value>. The C<i_> variants perform an inplace operation,
1457 modifying the value of I<self>.
1461 void substr(INTERP, PMC* self, INTVAL offset, INTVAL length, PMC* dest)
1462 STRING* substr_str(INTERP, PMC* self, INTVAL offset, INTVAL length)
1464 Extracts the string starting at I<offset> with size I<length> and return
1465 it as a PMC in I<dest> or as a string return value.
1469 =head3 Code Vtable Functions
1475 opcode_t* invoke(INTERP, PMC* self, void* next)
1477 Invoke the code object I<self>.
1481 =head3 Class/Object Vtable Functions
1487 INTVAL can(INTERP, PMC* self, STRING* method)
1489 Return a true value if the PMC has a method named I<method>, return 0
1494 INTVAL isa(INTERP, PMC* self, STRING* classname)
1496 Return a true value if the PMC inherits from the class named
1497 I<classname>, return 0 otherwise.
1501 INTVAL does(INTERP, PMC* self, STRING* role)
1503 Return a true value if the PMC C<does> (composes) or C<performs>
1504 (satisfies the interface of) the role named I<role>, return 0 otherwise.
1508 PMC* get_attr(INTERP, PMC* self, INTVAL idx) [deprecated: see RT #48583]
1509 PMC* get_attr_str(INTERP, PMC* self, STRING* idx)
1511 Retrieve an attribute value from the PMC (instance object).
1515 void set_attr(INTERP, PMC* self, INTVAL idx, PMC* value)
1516 [deprecated: See RT #48585]
1518 void set_attr_str(INTERP, PMC* self, STRING* idx, PMC* value)
1520 Store an attribute value in the PMC (instance object).
1524 void add_parent(INTERP, PMC* self, PMC* parent)
1526 Add a parent to the PMC (class object), establishing an inheritance relation.
1530 void remove_parent(INTERP, PMC* self, PMC* parent)
1532 Remove a parent from a PMC (class object).
1534 Not all object metamodels will support removing parents.
1538 void add_role(INTERP, PMC* self, PMC* role)
1540 Add a role to the PMC (class object), establishing a composition relation.
1544 void remove_role(INTERP, PMC* self, PMC* role)
1546 Remove a role from the PMC (class object).
1548 Not all object metamodels will support removing roles.
1552 void add_attribute(INTERP, PMC* self, STRING* name, PMC* type)
1554 Add an attribute to the PMC (class object).
1556 =item remove_attribute
1558 void remove_attribute(INTERP, PMC* self, STRING* name)
1560 Remove an attribute from the PMC (class object).
1562 Not all object metamodels will support removing attributes.
1566 void add_method(INTERP, PMC* self, STRING* method_name, PMC* sub_pmc)
1568 Add a method to the PMC (class object).
1572 void remove_method(INTERP, PMC* self, STRING* method_name)
1574 Remove a method from the PMC (class object).
1576 Not all object metamodels will support removing methods.
1578 =item add_vtable_override
1580 void add_vtable_override(INTERP, PMC *self, STRING *vtable_name,
1583 Add a vtable override to the PMC (class object).
1585 void remove_vtable_override(INTERP, PMC* self, STRING* vtable_name)
1587 Remove a vtable override from the PMC (class object).
1591 PMC* find_method(INTERP, PMC* self, STRING* method_name)
1593 Return a subroutine PMC for the passed method name. This subroutine PMC may be
1594 cached, so the method I<must> return an equivalent sub PMC each time, or be
1595 capable of dealing with the returned sub PMCs being reused. [Why should it be
1596 cached? Can you turn off caching? What if you want to override find_method to
1597 generate methods on the fly?]
1605 Parrot has a number of core PMC types that all programs can guarantee will be
1606 available to them. (With the possible exception of Parrot programs executing
1607 on an embedded device or other restricted environment)
1615 This is the generic no-value type. It has a numeric value of zero, a string
1616 value of empty string, and a boolean value of false. It will, on assignment,
1617 turn itself into a PMC of the source type, or if assigned a basic type will
1618 turn itself into one of the wrapper PMC types (detailed below) for the basic
1623 The PMC wrapper for Parrot's low-level integer type. Always an integer, with
1624 other types auto-converted to an integer when stored into this PMC. The range
1625 and behaviour of the Integer PMC is identical to the platform low-level
1628 The boolean value for an Integer is false if zero, otherwise true.
1630 Floating point, string, and bignum values assigned to an Integer PMC round to
1631 the nearest integer. Floats, or strings which resolve to numbers, cap at the
1632 platform maximum or minimum integer value.
1634 Integer PMCs take on a value of 1 if a boolean true is assigned, and a value
1635 of 0 if a boolean false is assigned.
1637 If an out-of-range value is assigned to an Integer PMC, the PMC will throw an
1638 exception if exact math is enabled.
1642 The PMC wrapper for Parrot's low-level floating-point type. Always a float,
1643 with other types autoconverted to a float when stored into this PMC.
1645 The boolean value for a Float is false if exactly zero, otherwise true.
1647 When converted to an integer, floats round to the closest integer, capping at
1648 the platform maximum or minimum integer value.
1650 When converting to a string, floats use the platform default snprintf format.
1654 The PMC wrapper for Parrot's low-level string type. Always a simple string,
1655 with other types autoconverted to a string when stored into this PMC.
1657 The boolean value for a String is false if empty or the string '0' (a one
1658 character string holding a zero) otherwise true. This PMC autoconverts to an
1659 integer or float when its integer or float value is fetched.
1663 A true/false value. Returns 0 for false, 1 for true when fetched as an
1664 integer or float, empty string for false and '1' for true when fetched
1669 An arbitrary precision integer.
1673 The PMC wrapper for Parrot's low-level BigNum type.
1674 {{ NOTE: this type doesn't seem to exist. }}
1678 A complex number, consisting of a real part and an imaginary part.
1679 {{ NOTE: is this a complete and useful implementation of complex
1684 The PMC for Parrot's class.
1688 The PMC for Parrot's base object type.
1692 The PMC that represents a reference to another PMC. Delegates all functions to
1693 the referred-to PMC.
1695 =item AggregateElementRef
1697 This PMC represents a reference to an element contained in an aggregate PMC
1698 type, such as an array or hash. It is initialized with the key being
1699 referenced and the aggregate PMC containing that key.
1701 Note that assigning to the reference PMC will be equivalent to a keyed set on
1702 the referenced aggregate PMC - that is, it modifies the element rather than
1703 doing a v-table call on the element itself. It is important to be aware of
1704 this when assigning a PMC through this reference; it is not the same behaviour
1707 =item WeakRegisterRef
1709 This PMC represents a weak reference to a register. Should the reference live
1710 beyond the context containing the register that it references, any attempt to
1711 use the reference will throw an exception.
1713 A weak register reference can only be created by the C<register_ref> opcode.
1714 Any assignment to the register will behave like a set instruction. That is,
1715 when assigning a PMC using a WeakRegisterRef PMC, the register will be updated
1716 to reference that PMC rather than calling the assign v-table call on the PMC
1717 in that register. This is not the same behaviour as the Ref PMC.
1721 A singleton PMC that generates a random number. {{ NOTE: Why do we have
1726 The base class for all exceptions. Currently based on
1727 C<ResizablePMCArray>, but that's likely to change.
1733 Note that for the following types you can set the size of the array by using
1734 the VTABLE_set_integer_native() method. Assigning an integer to the array as a
1735 whole sets the array to that size.
1737 Size-changing operations (such as push, pop, shift, unshift, and splice)
1738 on statically-sized arrays will throw an exception.
1740 ResizablePMCArray returns Undef for unset elements (so does the new
1741 object model, because it uses ResizablePMCArray for storage), but Hash
1742 returns PMCNULL. Standardize all core aggregate PMC types on the
1749 The base class for all array types (a statically sized array for any
1750 arbitrary type). New array types can be derived from the base Array.
1751 In user code it is recommended to use one of the specific array types
1752 below, rather than the base type.
1754 =item FixedBooleanArray
1756 A statically sized array which holds only Boolean values.
1758 =item ResizableBooleanArray
1760 A dynamically sized array which holds only Boolean values.
1762 =item FixedIntegerArray
1764 A statically sized array which holds only Integer values.
1766 =item ResizableIntegerArray
1768 A dynamically sized array which holds only Integer values.
1770 =item FixedFloatArray
1772 A statically sized array which holds only Float values.
1774 =item ResizableFloatArray
1776 A dynamically sized array which holds only Float values.
1780 A statically sized array which holds only PMC values.
1782 =item ResizablePMCArray
1784 A dynamically sized array which holds only PMC values.
1786 =item FixedStringArray
1788 A statically sized array which holds only String values.
1790 =item ResizableStringArray
1792 A dynamically sized array which holds only String values.
1802 A Pair PMC represents one key => value mapping.
1803 Thus it is like a one element hash or a two element array.
1807 A container with key-value semantics. The values are PMCs.
1811 Env is a singleton PMC class, that is there is only one Env PMC in any
1812 interpreter. This PMC gives access to the process' environment
1813 variables--reading from it returns the value of the named process environment
1814 variable, while writing to it sets the value of a process environment
1815 variable. For example, to retrieve the current value of TERM (the terminal
1816 type on most Unix systems):
1821 Note that an embedding system may override this behavior.
1825 Stores one level of a namespace. Every slot in a namespace contains
1826 either another namespace (the next level down), or a variable or
1831 A hash that also preserves the order of elements, providing the
1832 interface of both a hash and an array.
1836 Simulates reference counting for dead-object detection and garbage
1841 =head3 Subroutine types
1847 A fundamental subroutine object, and base class for other subroutine
1852 A closure: subroutine object plus captured lexical scope.
1856 A continuation: a subroutine object that captures the interpreter's
1857 context at the point where the continuation was constructed.
1861 A coroutine: a continuation object that can stop part way through
1862 execution and restart at the point where it left off the next time it's
1867 An extension of C<Sub> that provides dynamic code evaluation and
1870 =item Exception_Handler
1872 A code object for handling exceptions.
1876 A container for multiply dispatched subroutines.
1880 A native call interface wrapper around a C function.
1884 An internal NCI method call bound to a particular call instance.
1888 A subroutine implementing a language compiler. (Derived from NCI.)