Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
215 lines (128 sloc) 5.47 KB


docs/pmc2c.pod - The PMC definition to C compiler.


% perl tools/build/ --vtable
% perl tools/build/ --dump src/pmc/scalar.pmc
% perl tools/build/ --c src/pmc/scalar.pmc


This document covers the PMC definition to C compiler, i.e., tools/build/

Compiling PMCs

To compile methods the first --vtable phase needs to scan src/vtable.tbl once and dump vtable.dump.

In the second --dump phase on the each .pmc file pmc2c will parse the class definition, inheritance and all methods and will store this information in .dump files along the .pmc file.

The program determines the names of the .c and .h files from the basename of the .pmc file (e.g. scalar.pmc -> scalar.c and scalar.h).

The .pmc file is searched for /pmclass \w*/ which attempts to find the class being declared.

Once the class is found, all of its superclasses are scanned and their methods added to the methods of the current PMC. PMCs default to inheriting from 'default'. Only single inheritance is supported.

Once the superclass is determined, it is processed and its method names are extracted and saved.

Next, each method body is processed with various directives (see below) getting replaced by their appropriate values.

Finally, in the third phase <--c> the .c and .h files are generated. The appropriate base class header files are included.

If the no_init flag was used, then no init function is generated. Otherwise, one is generated which sets up the vtable and enters it into the vtables array.

The .c file is generated by appending the functions after the various directives have been replaced.

PMC File Syntax

The basic syntax of a PMC file is

  1. A preamble, consisting of code to be copied directly to the .c file

  2. The pmclass declaration:

    pmclass PMCNAME [flags] {

    where flags are:

    extends PMCPARENT

    All methods not defined in PMCNAME are inherited from the PMCPARENT class. If no parent class is defined, methods from default.pmc are used.


    This class cannot be instantiated. Abstract classes are shown with lower case class names in the class tree.


    Used with abstract: No class_init code is generated.


    Classes with this flag get 2 vtables and 2 enums, one pair with read/write set methods, and one with read-only set methods.

    does interface

    The class 'does' the given interfaces (the collection of methods which the class implements).

    The default is "scalar". Other currently used interfaces are:

    array    : container PMC with numerically-keyed elements
    event    : PMC that can be used with event queue
    hash     : container PMC with string-keyed elements
    library  : PMC that corresponds to a dynamic library
    ref      : PMC that references another PMC
    string   : PMC that behaves similarly to the base string type
    boolean  : PMC that does true/false only.
    integer  : PMC that behaves similarly to the base int type
    float    : PMC that behaves similarly to the base number type
    scalar   : (only used by the sample src/dynpmc/foo.pmc)

    This is not a canonical list, but merely a snapshot of what's in use.


    The class is a dynamic class. These have a special class_init routine suitable for dynamic loading at runtime. See the src/dynpmc directory for an example.

    group GROUP

    The class is part of a group of interrelated PMCs that should be compiled together into a single shared library of the given name. Only valid for dynamic PMCs.

    lib LIB

    The class needs an external library.

    hll HLL

    The High level language this PMC corresponds to.

    maps Type

    The basic parrot PMC type that this PMC correspond to for .HLL usage. For example:

    pmclass TclInt hll Tcl maps Integer

    allows this PMC to automatically be used when autoboxing I registers to PMCs.

    Requires the hll flag. Note that multiple mappings can be specified:

    pmclass myOrderedHash hll frob maps Hash maps Array
  3. A list of attribute declarations:


    The ATTR declaration keyword is followed by the type of the attribute and the name of the attribute. Any valid C type is a valid attribute type, but only INTVAL, FLOATVAL, STRING *, and PMC * can be handled directly from PIR. Other types are generally only used by low-level internal PMCs.

  4. A list of vtable function implementations

  5. The final close }

Method Body Substitutions

The vtable function bodies can use the following substitutions:


Converted to the current PMC object of type PMC *.


Converted to the interpreter object.


Calls the static vtable or method 'method' in OtherClass.


Calls the vtable or method 'method' using the dynamic type of SELF.


Same as above, but calls the current method.


Calls the vtable or method 'method' using the static type of SELF (in other words, calls another method defined in the same file).


Calls the overridden implementation of the current method in OtherClass.


Calls the overridden implementation of the current method in the nearest superclass, using the type of SELF.