| perl6 docs/pdds/pdd15_objects.pod |
docs/pdds/pdd15_objects.pod - Object and Class semantics for Parrot
This PDD describes the semantics of Parrot's object and class systems. The PDD is divided into two parts, the semantics expressed to user programs through PMCs, and the default back-end class scheme.
Note that the class system is not the single mandated class scheme, merely the one designed to express the semantics needed for perl 6, ruby, and python. Alternate class systems are certainly possible, and direct compatibility with the system as described here isn't strictly necessary.
This is a reasonably straightforward object system. It assumes that objects have:
and that you can:
Additionally we assume that all objects can have properties on them, as all PMCs can have properties. The property get/set method may be overridden on a per-class basis as any other vtable method may be.
For classes, we assume that:
And we further assume that classes can:
This list is likely not definitive, but it's enough to start with. It also doesn't address the semantics of method calls, which need to be dealt with, possibly separately. With that in mind, the object system supports these features with a combination of PMC classes (not to be confused with object classes) and opcodes.
There are four pieces to the object implementation. There are the PMCs for the classes and objects, the opcodes the engine uses to do objecty things, the specific vtable methods used to perform those objecty things, and the supporting code provided by the interpreter engine to do the heavy lifting.
Please note that Parrot, in general, does not restrict operations on objects and classes. If a language has restrictions on what can be done with them, the language is responsible for making sure that disallowed things do not happen. For example, Parrot permits multiple inheritance, and will not stop code that adds a new parent to an existing class. If a language doesn't allow for multiple inheritance it must not emit code which would add multiple parents to a class. (Parrot may, at some point, allow imposition of runtime restrictions on a class, but currently it doesn't)
There are two PMC classes,
ParrotClass and ParrotObject.
ParrotObject PMCs are the actual objects,
and hold all the per-object instance data.
ParrotClass PMCs hold all the class-specific information.
Instantiating a new OO class creates a new ParrotClass PMC,
and enters the new OO class into Parrot's PMC class table,
at which point it is indistinguishable from any other PMC class.
(This doesn't mean that non-ParrotClass things can be subclassed or treated as an OO class.
Neither is that forbidden.
Just unimplemented)
It's important to note that all 'standard' classes are ParrotClass PMC instances, and all 'standard' objects are ParrotObject PMCs. We do not create a brand new PMC class for each OO class, and they all share the ParrotClass or ParrotObject vtable, respectively. This distinction is mostly an artifact of the implementation, and may change in the future.
While the internals of the class and object PMCs should be considered black boxes, here's some documentation as to what they are for implementation purposes.
The ParrotClass PMC holds a 6 element array, which is:
An array PMC of the immediate parent classes
The class name PMC
An array of all parent PMCs, in search order
The class attribute section hash. Keys are the class name in language-defined format (so perl would be foo::bar, while java would be some.damn.long.thing.with.dots), values are the integer offset from the start of the attribute array where that class' attributes start.
The class attribute name hash. Keys are the fully qualified attribute names and the values are the offset from the beginning of the attribute array of the particular attribute.
The class attribute array. This is an array of unqualified attribute names.
Note that the attribute catalog holds all the attributes for an object. This includes the attributes in the object's class as well as all the attributes defined in all the parent classes. (Multiple inheritance makes this necessary -- the offsets of a class' attributes will change from child class to child class)
ParrotClass PMCs also have the "I am a class" flag set on them.
The ParrotObject PMC is an array of meta-information and attributes. The elements of this array are:
The class PMC
The class name PMC
The attributes for the object
Note that ParrotObject PMCs also have the "I am an object" flag set on them.
The following ops are provided to deal with objects. Please note that method calls are governed by parrot's calling conventions, and as such objects, method PMCs, return continuations, and parameters must be in the right places, though some ops will put parameters where they need to go.
Returns the offset of the first attribute for class Sz in object Py.
Returns attribute Iz of object Py and puts it in Px. Note that the attribute number is an absolute offset.
Get the attribute with the fully qualified name Sz from object Py and put it in Px.
Set the attribute Iy of object Px to Pz. Note that this op stores the actual PMC rather than a copy, and so if the PMC's value is subsequently changed, the value of the attribute will also change.
Set the attribute of object Px with the fully qualified name Sy to Pz
Find the PMC for method Sz of object Py, and put it in Px. Note that how the method PMC returned behaves if it goes out of scope or if the class hierarchy changes or the method definitions change is entirely up to the class that provides the PMC.
Call a method. If the method name is provided, we find the PMC for the named method and put it in the sub/method slot. If no name is provided we assume that all the calling conventions have already been set up and the method PMC is already in the proper place.
Make a method call, automatically generating a return continuation. If a method name is passed in we look up the method PMC for the object and put it in the method slot. If a method name isn't provided then we assume that things are already properly set up.
Make a tailcall to method Sx. If no method name is given, we assume everything is already set up properly.
Create a new base class named Sy, and put the PMC for it in Px
Create a new class, named Sz, which has Py as its immediate parent.
Add class Py to the end of the list of immediate parents of class Px. Adds any attributes of Py (and its parent classes) that aren't already in Px.
Remove class Py from the parent list of Px. All parent classes of Py which aren't parent classes of what remains of Px's parent list are removed, as are their attributes.
Add attribute Sy to class Px.
This will add the attribute slot to all objects of class Px and children of class Px,
with a default value of Null.
Remove the attribute Sy from class Px, all objects of class Px, and all objects of a child of class Px.
Instantiate a brand new class, based on the metadata in Py, named Sz.
To make this work all PMCs must have the following vtable entries. They may, for non-objects, throw an exception.
The catalog metadata for objects is considered to be attributes on the class, so to get the offset for a class for an object, you fetch the object's class then look up the offset attribute from it. (The class attributes are detailed later) This is safe in general, since the only code reasonably querying a class' attribute list is the class code itself, and if a class doesn't know whether it's a ParrotClass-style class or not you've got bigger problems.
Returns the PMC for the named method. If no method of this name exists, nor can be constructed, returns a Null PMC.
Note that for languages which support default fallback methods, such as Perl 5's AUTOLOAD, this would be the place to return it if a normal lookup fails.
Returns true or false if the class passed in as a parameter is in the inheritance hierarchy of the object.
Returns true or false if the object can perform the requested method. (Including with an AUTOLOAD)
Returns true or false to note whether the object in question implements the interface passed in.
Returns the attribute at the passed-in offset for the object.
Returns the attribute with the fully qualified name for the object.
Sets the attribute for the passed-in offset to the passed-in PMC value
Set the attribute with the fully qualified name for the object.
Returns the class PMC for the object.
Currently Parrot only supports mutating a class' metainformation for ParrotClass classes. This is a restriction which will be lifted at some point soon.
The bytecode is isolated from most of the internal details of the implementation. This allows both for flexibility in the implementation and forward compatibility, generally good things. It also allows for multiple concurrent interoperable object systems. The major thrust is for transparent use of objects, though most class activity (including creation of subclasses and modifications of existing classes) should be transparent as well.
The following examples all assume we're working with basic ParrotObject objects and ParrotClass classes.
To create a new class Foo which has no parent classes:
newclass $P0, "Foo"
To create a class Foo with the parents A and B, the code would be:
getclass $P0, "A" getclass $P1, "B" subclass $P2, $P0, "Foo" addparent $P2, $P1
Adding the attributes a and b to the new class Foo:
newclass $P0, "Foo" addattribute $P0, "a" # This is offset 0 + classoffset addattribute $P0, "b" # This is offset 1 + classoffset
Assuming we want an object of class Foo:
.local int FooType .local pmc MyObject find_type FooType, "Foo" new MyObject, FooType
Calling the method Xyzzy on an object, assuming the PDD03 calling conventions are respected:
callmethod "Xyzzy" set S0, "Xyzzy" callmethod
Or, if a return continuation needs constructing:
callmethodcc "Xyzzy" set S0, "Xyzzy" callmethodcc
Assuming we've an object that has class Foo in it somewhere and want to get the second attribute b out of it:
.local int BaseOffset .local int BOffset classoffset BaseOffset, $P0, "Foo" BOffset = BaseOffset + 1 getattribute $P1, $P0, BOffset
Or with named access, if it isn't time critical:
getattribute $P1, $P0, "Foo\x0b"
To get a new class, you can do a newclass, which creates a new class with no parents besides parrot's default super-ish parent class. (Which doesn't appear in the class list anywhere, though arguably it ought to)
To get a new child class, you have two potential options:
Both ways work. It is, however, more efficient to use the first method, and just subclass the immediate parent class of your new class.
When adding in extra parents in a multiple-inheritance scenario, subclass the first class in the immediate parent list then use the addparent op to add in the rest of the immediate parents.
Do be aware that, right now, you should not add attributes or parents to a class that's been subclassed or has had objects instantiated. This will leave the internal structures of the classes and objects in an inconsistent state and things won't work at all the way you want them to. At the moment parrot won't warn if you do this, but it will soon. The restriction on parent list changes and attribute addition will be lifted in future releases, though doing so will be an expensive operation.
Classes may override the vtable methods, allowing objects of a class to behave like a primitive PMC. Each vtable slot has a corresponding named method that parrot looks for in your class hierarchy when an object is used in a primitive context.
To use these properly at a low-level requires a good working knowledge of the way Parrot works--generally for higher-level languages the language compiler or runtime will provide easier-to-use wrappers. These methods are all prototyped, and take a single fixed argument list, and return at most a single value.
While vtable methods may take a continuation, those continuations may not escape the vtable method's execution. This is due to the way that vtable methods are called by the interpreter--once a vtable method is exited any continuation taken within it is no longer valid and may not be used.
Note that any class method that wishes to use parrot's multi-method dispatch system may do so. This is, in fact, encouraged, though it is not required. In the absence of explicit multimethod dispatch, a left-side wins scheme is used.
The following list details the raw method names:
Called when the object is first created.
Called when the DOD is tracing live PMCs. If this method is called then the code must mark all strings and PMCs that it contains as live, otherwise they may be collected.
This method is only called if the PMC is flagged as having a special mark routine, and is not necessary for normal objects.
Called when the object is destroyed. This method is only called if the PMC is marked as having an active finalizer.
Return the integer value of the object
Return the floating-point value of the object
Return the extended precision numeric value of the PMC
Return the string value of the PMC
Return the true/false value of the PMC
Return the PMC for this PMC.
Set the integer value of this PMC
Set the floating-point value of this PMC
Set the extended-precision value of this PMC
Set the string value of this PMC
Set the true/false value of this PMC
Set the PMC to the PMC passed in
Return the number of elements in the PMC, if the PMC is treated as an aggregate.