/ 
parrot-0.5.1
/ docs/vtables.pod

NAME

docs/vtables.pod - Parrot Vtables

Implementing Variable Types with Vtables

This is a guide to creating your own PMC (Parrot Magic Cookie) classes. It tells you what you need to write in order to add new variable types to Parrot.

Overview

The guts of the Parrot interpreter are by design ignorant (or, if you want to be less disparaging, agnostic) of the intricacies of variable type behavior. The standard example is the difference between Perl scalars and Python scalars. In Perl, if you have

$a = "a9";
$a++;

you end up with $a being b0. This is because of the magic of the Perl increment operator. In Python, on the other hand, you'd get a runtime error.

  • To be perfectly honest, this is a slightly flawed example, since it's unlikely that there will be a distinct "Python scalar" PMC class. The Python compiler could well infer variables by their type such that a would be a PythonString and b would be a PythonNumber. But the point remains - incrementing a PythonString is very different from incrementing a PerlScalar.

Since the behavior is a function of the "type" of the PMC, it's natural to consider the various different types of PMC as classes in an object-oriented system. The Parrot interpreter calls methods on the individual PMC objects to manipulate them. So the example above would translate to something like:

  1. Construct a new PMC in the PerlScalar class.

  2. Call a method setting its string value to "a9".

  3. Call a method to tell it to increment itself.

And if you replace PerlScalar with PythonString, you get different behavior but to the fundamental guts of the interpreter, the instructions are the same. PMCs are an abstract virtual class; the interpreter calls a method, the PMC object does the right thing, and the interpreter shouldn't have to care particularly what that right thing happens to be.

Hence, adding a new data type to Parrot is a question of providing methods which implement that data type's expected behavior. Let's now look at how one is supposed to do this.

Starting out

If you're adding data types to the core of Parrot, (and you've checked with Chip that you're supposed to be doing so) you should be creating a file in the src/pmc/ subdirectory; this is where all the built-in PMC classes live. (And a good source of examples to plunder even if you're not writing a core data type.)

You should almost always start by running tools/dev/gen_class.pl to generate a skeleton for the class. Let's generate a number type for the beautifully non-existent Fooby language:

% perl tools/dev/gen_class.pl FoobyNumber > src/pmc/foobynumber.pmc

This will produce a skeleton C file (to be preprocessed by the tools/build/pmc2c.pl program) with stubs for all the methods you need to fill in. The function init allows you to set up anything you need to set up. Comment out the namespace method from the automatically generated set of methods (otherwise, the compile will fail).

Now you'll have to do something a little different depending on whether you're writing a built-in class or an extension class. If you're writing a built-in class, then you'll see a reference to enum_class_FoobyNumber in the init function. For built-in classes, this is automatically defined in pmc.h when you run Configure.pl. If you're not writing a built-in class, you need to indicate this by using the 'extension' keyword after the 'pmclass YOURCLASS' declaration in src/pmc/YOURCLASS.pmc. Then, change the type of the init function to return VTABLE, and then return temp_base_vtable instead of assigning to the interpreter specific vtables array.

To finish up adding a built-in class:

  1. Add src/pmc/YOURCLASS.pmc to the MANIFEST

  2. Run make realclean, and rerun Configure.pl to add your new PMC to the set of built-in PMCs.

What You Can and Cannot Do

The usual way to continue from the tools/dev/gen_class.pl-generated skeleton is to define a structure that will hook onto the data, if your data type needs to use that, and then also define some user-defined flags.

Flags are accessed by pmc->flags. Most of the bits in the flag word are reserved for use by parrot itself, but a number of them have been assigned for general use by individual classes. These are referred to as Pobj_private0_FLAG .. Pobj_private7_FLAG. (The '7' may change during the early development of parrot, but will become pretty fixed at some point.)

Normally, you will want to alias these generic bit names to something more meaningful within your class:

enum {
    Foobynumber_is_bignum = Pobj_private0_FLAG,
    Foobynumber_is_bigint = Pobj_private1_FLAG,
    ....
};

You're quite at liberty to declare these in a separate header file, but I find it more convenient to keep everything together in foobynumber.c. To manipulate the flags, use the macros listed in pobj.h.

You may also use the cache union in the PMC structure to remove some extraneous dereferences in your code if that would help.

Multimethods

One slightly (potentially) tricky element of implementing vtables is that several of the vtable functions have variant forms depending on the type of data that they're being called with.

For instance, the set_integer method has multiple forms; the default set_integer means that you are being called with a PMC, and you should probably use the get_integer method of the PMC to find its integer value; set_integer_native means you're being passed an INTVAL. The final form is slightly special; if the interpreter calls set_integer_same, you know that the PMC that you are being passed is of the same type as you. Hence, you can break the class abstraction to save a couple of dereferences - if you want to.

Similar shortcuts exist for strings, (native and same) and floating point numbers.

Implementing methods

The master list of vtable methods can be found in vtable.tbl in the root directory of the Parrot source, with documentation in docs/pdds/pdd02_vtables.pod. A few of these are very important, for instance:

type

Return the enumeration value of your class.

name

Return a string containing your class name.

init

Initialization. Parrot makes exactly one call to either init or init_pmc at PMC construction time.

init_pmc

Alternative entry point for initialization that takes a PMC argument. Parrot makes exactly one call to either init or init_pmc at PMC construction time.

NOTE: It is strongly suggested that init_pmc(PMCNULL) be equivalent to init().

is_equal

True if the passed-in PMC has the same value as you. For instance, a Perl integer and a Python integer could have the same value, but could not be the same thing as defined by is_same.

clone

Copy your data and state into the passed-in destination PMC.

Others are methods you may or may not need, depending on your type:

morph

Turn yourself into the specified type.

destroy

Do any data shut-down and finalization you need to do. To have this method called, you must set the Pobj_active_destroy_FLAG.

get_integer

Return an integer representation of yourself.

get_number

Return a floating-point representation of yourself.

get_string

Return a string representation of yourself (a STRING* object), this should be a copy of whatever string you are holding, not just a pointer to your own string so that anything that calls this method can happily modify this value without making a mess of your guts.

get_bool

Return a boolean representation of yourself.

get_value

Return your private data as a raw pointer.

is_same

True if the passed-in PMC refers to exactly the same data as you. (Contrast is_equal)

set_integer

Set yourself to the passed-in integer value. This is an integer multimethod.

set_number

Set yourself to the passed-in float value. This is a floating-point multimethod.

set_string

Set yourself to the passed-in string. This is a string multimethod.

set_value

Set your private data to the raw pointer passed in. This will only be used in exceptional circumstances.

add

Fetch the number part of value and add your numeric value to it, storing the result in dest. (Probably by calling its set_integer or set_number method) This is a numeric multimethod.

subtract

Fetch the number part of value and subtract your numeric value from it, storing the result in dest. (Probably by calling its set_integer or set_number method) This is a numeric multimethod.

multiply
divide
modulus

You get the picture.

concatenate

Fetch the string part of value and concatenate it to yourself, storing the result in dest. (Probably by calling its set_string method) This is a string multimethod.

logical_or
logical_and

Perform the given short-circuiting logical operations between your boolean value and the value passed in, storing the result in dest.

logical_not

Set yourself to be a logical negation of the value passed in.

repeat

Repeat your string representation value times and store the result in dest.

If any method doesn't fit into your class, just don't implement it and don't provide an empty function body. The default class, which all classes inherit from, will throw an exception, if this method would be called.

If your class is a modification of an existing class, you may wish to use inheritance. At the beginning of your vtable specification in src/pmc/YOURCLASS.pmc, add the extends SUPERCLASS phrase. For example:

pmclass PackedArray extends Array { ...

See the POD documentation in tools/build/pmc2c.pl for a list of useful keywords that you may use in the .pmc file. (Run perldoc -F pmc2c.pl to view the POD.)