Common vtable format for all variables
Maintainer: Dan Sugalski <dan@sidhe.org> Class: Internals PDD Number: 2 Version: 1.3 Status: Developing Last Modified: 27 July 2003 PDD Format: 1 Language: English
27 July 2003
22 June 2002
13 May 2002
None. First version
Added a number of missing method definitions. Many other minor cleanups.
Many cleanups and clarifications. Much detail added. Many missing methods added.
Cleaned up the definition. It was a mess.
This PDD presents the vtable entries, and their order, that all variables MUST provide.
All parrot variables hide their guts behind a magic parrot structure generally referred to as a PMC, or Parrot Magic Cookie. Nothing outside the core of parrot (in fact, nothing outside the data type's vtable routines) should infer anything about a PMC (hence the Magic part).
The first parameter to any vtable routine should be the current interpreter. The second parameter should be the PMC itself.
vtables are neat because they decouple the interface and implementation of various object functions. This does mean, though, that you need to either know what functions are available and what they do, or have some method of finding out. It's faster if you know which vtable entry does what, so that's the method parrot's using.
The actual vtable structure contains pointers to functions that implement the methods for that particular vtable. All pointers must point to valid functions with appropriate prototypes.
This is a list of each of the vtable methods, their prototypes, and a description of the method.
The following functions are singleton functions. (There are no keyed versions of these)
The init vtable method takes an unused PMC as a parameter and turns it into a PMC appropriate for the class owning the vtable. Called as a class method. There is also a form that accepts a PMC initializer as a third argument.
This form of the init method takes a single initializer parameter. The initializer is an array that contains keys and values. The meaning of the keys and their corresponding values is left up to the PMC.
Keys are either strings or integers. If strings, the PMC is responsible for figuring out what the string represents. If integers, it means the meaning has been pre-figured based on meta-information from the class.
For example, if a class has the known properties "Size", "Dimension" and "Color", they may be assigned the values 100, 101, and 102. If the creator of the PMC knows enough about the class to make the translation to numbers it may; otherwise, the raw strings may be used. So, for the declaration:
my @foo Size(12), Dimension(3), Color("Green");
the init array may be [100, 12, 101, 3, 102, "Green"] or ["Size", 12, "Dimension", 3, "Color", "Green"]. Note that, in all cases, the array is an array of PMCs. (So you get either an int PMC or a string PMC in the list of keys).
XXX: what does this do?
Turn the PMC into a PMC of type type. If the morphing can't be done in any reasonable way -- for instance if an integer is asked to turn into an Array -- then the PMC is first destroyed, then recreated as an empty PMC of the new type.
type
This method is primarily used when the interpreter has need of coercing a PMC to a particular type, and isn't meant as a general purpose casting tool. Compilers should only emit valid transformations.
Called by the DOD when it is sweeping through the PMCs and has detected that this PMC is both alive and has a custom mark routine (as indicated by the custom mark PMC flag).
If a PMC has this flag set, then it is responsible for marking all buffers and PMCs under its control as alive. If it does not, those PMCs or buffers may be collected later. This method does not have to call the mark method on any PMCs it marks--the DOD system takes care of that. (So no need to recurse into aggregate PMCs or anything of the sort).
mark
This method may allocate no memory from Parrot, nor may it alter Parrot's internal structures. It should have no side-effects from the C level either.
This routine may not throw an exception.
This method is called by the DOD when it determines that a PMC is dead and that the PMC has marked itself as having a destroy method.
When this method finishes, the PMC will be marked as dead. As such you should make sure that you do not leave any references to it in any parrot structure by the end of the method.
This method may not throw an exception. It will be ignored if it does.
Return the value from the property hash of self keyed by key. The key should not be NULL.
Set the value in the property hash of self that is keyed by key to the value of value. The key should not be NULL.
Delete the value from the property hash of self keyed by key. The key should not be NULL.
Return the entire property hash for self.
The following functions have a plain form, a _keyed form, and a _keyed_int form. The keyed forms take a KEY* or INTVAL* for each PMC parameter. The KEY*/INTVAL* parameter for each PMC is NULL if there is no key for that PMC; this means that that argument is unkeyed.
In some cases, the caller must provide a non-NULL key. Those cases are explicitly stated below. In the other cases, you may have to implement the keyed vtable methods and check for a NULL self key even if you are implementing a non-aggregate type. If the self key is non-NULL and the PMC class is a non-aggregate type, the _keyed_* methods should throw an exception.
If you do not implement the _keyed_int methods, the default will convert the INTVAL into a KEY and call the corresponding _keyed method.
The keyed methods should NOT assume that the key pointer will be valid after the method exits. The pointer may be to a stack variable in the calling function.
Return the type of the PMC. Type is a unique tag associated with the PMC when the PMC's class is loaded. Negative numbers are considered interpreter-specific, non-public types.
Return the type of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the subtype of a PMC. (Note that this may be unimplemented, and may go away). This is intended to return information about the PMC--what type of number or string it is, whether it's a scalar, hash, array, or list, and suchlike things.
Return the subtype of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the name of the class for the PMC.
Return the name of the class of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Make dest a clone of yourself. dest is a PMC of the same type, created via pmc_new_noinit.
Make dest a clone of the PMC indexed by key. If the PMC is fake, for example we're asking for a clone of an element of an integer array, this must return an appropriate real PMC that holds the fake information. The key parameter is guaranteed not to be NULL for this method.
Return a subroutine PMC for the passed method name. This subroutine PMC may be cached, so the method must return an equivalent sub PMC each time, or be capable of dealing with the returned sub PMCs being reused.
Return a subroutine PMC for the passed method name. This subroutine PMC may be cached, so the method must return an equivalent sub PMC each time, or be capable of dealing with the returned sub PMCs being reused. The key parameter is guaranteed not to be NULL for this method.
Return the native integer value of the PMC.
Return the native integer value of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the native floating-point value of the PMC.
Return the native floating-point value of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the value of the PMC as a bignum.
Return the bignum value of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the native string value of the PMC. This may be in the encoding of the PMC's choice.
Return the string value of the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the constant TRUE if the PMC is true, or FALSE if the PMC is false. The definition of truth for a given PMC will depend on the type of the PMC: for a scalar, it may be as simple as 0 or "" being false, and any other value being true.
Return the constant TRUE if the PMC indexed by key is true, or FALSE if the PMC indexed by key is false. The key parameter is guaranteed not to be NULL for this method.
Return the number of elements in the PMC.
Return the number of elements in the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return the PMC for this PMC. While this may seem nonsensical, it's useful in several circumstances. If the thing being accessed may return something odd, for example a reference, it may return a value different from the PMC that get_pmc is being called on.
Return the PMC indexed by key. The key parameter is guaranteed not to be NULL for this method.
Return TRUE if the PMCs are the same, and FALSE if they're not. In this case, "the same" means identical at a low level. For plain equality, use the is_equal method.
Return TRUE if the PMC keyed by key is the same as the PMC in value keyed by value_key. At least one of the two keys is guaranteed not to be NULL.
Sets the PMC to the integer value of the PMC in value. What the PMC does with the passed in integer depends on the class.
Sets the PMC to the integer value passed.
Sets the PMC to the integer value of the PMC in value. In this case, value is guaranteed to be of the same type as self so optimizations may be made.
Sets the PMC indexed by key to the integer value passed in value. The key parameter is guaranteed not to be NULL for this method.
Sets the PMC to the floating-point value of the PMC in value.
Sets the PMC to the floating-point value passed.
Sets the PMC to the floating-point value of the PMC in value. In this case, value is guaranteed to be of the same type as self so optimizations may be made.
Sets the PMC indexed by key to the floating-point value passed in value. The key parameter is guaranteed not to be NULL for this method.
Sets the PMC to the bignum value of value.
Sets the PMC to the passed in bignum value.
Sets the PMC to the bignum value of value. In this case, value is guaranteed to be of the same type as self so optimizations may be made.
Sets the PMC indexed by key to the bignum value passed in value. The key parameter is guaranteed not to be NULL for this method.
Sets the PMC to the string value of value.
Sets the PMC to the passed in string value.
Sets the PMC to the string value of value. In this case, value is guaranteed to be of the same type as self so optimizations may be made.
Sets the PMC indexed by key to the string value passed in value. The key parameter is guaranteed not to be NULL for this method.
Sets the value of the PMC in self to the value of the PMC in value.
Sets the value of the PMC keyed by key to the value of the PMC in value keyed by value_key. At least one of the two keys is guaranteed not to be NULL.
A shortcut version of set_pmc in those cases where the interpreter knows the source and destination PMCs are of the same type.
set_pmc
Sets the value keyed by key to the value of value keyed by value_key. Both self and value are guaranteed to be of the same type so optimizations may be made.
At least one of the two keys is guaranteed not to be NULL.
Because the two PMCs are guaranteed to be of the same type, this method may throw an exception if the PMC class is a non-aggregate type.
Return the integer value of the last item on the list, removing that item.
Return the integer value of the last item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the floating-point value of the last item on the list, removing that item.
Return the floating-point value of the last item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the bignum value of the last item on the list, removing that item.
Return the bignum value of the last item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the string value of the last item on the list, removing that item.
Return the string value of the last item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the PMC value of the last item on the list, removing that item.
Return the PMC value of the last item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Add the passed in integer value to the end of the list.
Add the passed in integer value to the end of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in floating-point number to the end of the list.
Add the passed in floating-point value to the end of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in bignum to the end of the list.
Add the passed in bignum to the end of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in string to the end of the list.
Add the passed in string to the end of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in PMC to the end of the list.
Add the passed in PMC to the end of the list keyed by key. At least one of the two keys is guaranteed not to be NULL. If key is NULL then the method will use self. If value_key is NULL then the method will use value.
Return the integer value of the first item on the list, removing that item.
Return the integer value of the first item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the floating-point value of the first item on the list, removing that item.
Return the floating-point value of the first item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the bignum value of the first item on the list, removing that item.
Return the bignum value of the first item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the string value of the first item on the list, removing that item.
Return the string value of the first item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Return the PMC value of the first item on the list, removing that item.
Return the PMC value of the first item of the list keyed by key, removing that item from the list. The key parameter is guaranteed not to be NULL for this method.
Add the passed in integer value to the beginning of the list.
Add the passed in integer value to the beginning of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in floating-point number to the beginning of the list.
Add the passed in floating-point value to the beginning of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in bignum to the beginning of the list.
Add the passed in bignum to the beginning of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in string to the beginning of the list.
Add the passed in string to the beginning of the list keyed by key. The key parameter is guaranteed not to be NULL for this method.
Add the passed in PMC to the beginning of the list.
Add the passed in PMC to the beginning of the list keyed by key. At least one of the two keys is guaranteed not to be NULL.
Replace the count PMCs at offset offset from the beginning of self with the PMCs in the aggregate value.
Replace the count PMCs at offset offset from the beginning of the list in self keyed by key with the PMCs in the list in value keyed by value_key.
NOTE: the _keyed and _keyed_int variants of push, pop, shift, unshift and splice are not currently implemented and may go away.
Add self to value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Add self to value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Add the value in self keyed by key to the value in value keyed by value_key and store the result in dest keyed by dest_key.
At least one of the three keys is guaranteed to not be NULL.
Subtract value from self and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Subtract value from self and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Subtract the value in value keyed by key from the value in self keyed by value_key and store the result in dest keyed by dest_key.
Multiply value by self and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Multiply value by self and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Multiply the value in self keyed by key by the value in value keyed by value_key and store the result in dest keyed by dest_key.
Divide self by value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Divide self by value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Divide the value in self keyed by key by the value in value keyed by value_key and store the result in dest keyed by dest_key.
Divide self by value and store the remainder in dest. Note that dest may be equal to self; in that case optimizations may be made.
Divide self by value and store the remainder in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Divide the value in self keyed by key by the value in value keyed by value_key and store the remainder in dest keyed by dest_key.
NOTE: the _keyed and _keyed_int variants of add, subtract, multiply, divide and modulus are not currently implemented and may go away.
Negate the sign of self and store the result in dest. Note that self and dest may refer to the same PMC, in which case optimizations may be made.
Calculate the bitwise-OR of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Calculate the bitwise-OR of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Calculate the bitwise-OR of self keyed by key and value keyed by value_key, and store the result in dest_key.
At least one of the keys is guaranteed to be non-NULL.
Calculate the bitwise-AND of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Calculate the bitwise-AND of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Calculate the bitwise-AND of self keyed by key and value keyed by value_key, and store the result in dest keyed by dest_key.
Calculate the bitwise-XOR of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made.
Calculate the bitwise-XOR of self and value and store the result in dest. Note that dest may be equal to self; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Calculate the bitwise-XOR of self keyed by key and value keyed by value_key, and store the result in dest keyed by dest_key.
Apply a bitwise negation to self and store the result in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made.
Apply a bitwise negation to self keyed by key and store the result in dest keyed by dest_key.
At least one key is guaranteed to be non-NULL.
Apply a leftward shift of value bits to the number stored in self, and place the resulting value in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made.
Apply a leftward shift of value bits to the number stored in self, and place the resulting value in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Apply a leftward shift to the value in self keyed by key; the number of bits by which to shift is taken from the value in value keyed by value_key. Store the result in dest keyed by dest_key.
Applies a rightward shift of value bits to the number stored in self, and places the resulting value in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made.
Applies a rightward shift of value bits to the number stored in self, and places the resulting value in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made. In this case, it is guaranteed that self and value are of the same type.
Apply a rightward shift to the value in self keyed by key; the number of bits by which to shift is taken from the value in value keyed by value_key. Store the result in dest keyed by dest_key.
NOTE: the _keyed and _keyed_int variants of the bitwise methods are not currently implemented and may go away.
Concatenate the strings in self and value and store the result in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made.
Concatenate the strings in self and value and store the result in dest. Note that self and dest may refer to the same PMC; in that case optimizations may be made. In this case, self and value are guaranteed to be of the same type.
Concatenate the string in value keyed by value_key onto the string in self keyed by key and store the result in dest keyed by dest_key.
Return TRUE if the two PMCs are generically equivalent, or FALSE if they aren't.
Return TRUE if the PMC at self keyed by key is generally equivalent to the PMC at value keyed by value_key, or FALSE if they aren't.
Compare the two PMCs as PMCs (whatever that means for the class). Return -1 if self is smaller, 0 if the two are equal, and 1 if value is smaller.
Compare the PMC at self keyed by key with the PMC at value keyed by value_key as PMCs (whatever that means for the class). Return -1 if self is smaller, 0 if the two are equal, and 1 if value is smaller.
Compare the two PMCs numerically. Return -1 if self is smaller, 0 if the two are equal, and 1 if value is smaller.
Compare the PMC at self keyed by key with the PMC at value keyed by value_key numerically. Return -1 if self is smaller, 0 if the two are equal, and 1 if value is smaller.
Compare the two PMCs as strings. Return -1 if self is smaller, 0 if the two are equal, and 1 if value is smaller.
Do a short-circuiting logical-OR of self and value, storing the winner in dest.
Do a short-circuiting logical-OR of self keyed by key and value keyed by value_key, storing the winner in dest keyed by dest_key.
Do a short-circuiting logical-AND of self and value, storing the winner in dest.
Do a short-circuiting logical-AND of self keyed by key and value keyed by value_key, storing the winner in dest keyed by dest_key.
If exactly one of self or value is true, store it in dest. Else set dest to be false.
If exactly one of self keyed by key or value keyed by value_key is true, store it in dest keyed by dest_key. Else set dest keyed by dest_key to be false.
Do a logical-NOT on self and stores the result in dest.
Do a logical-NOT on self keyed by key and stores the result in dest keyed by dest_key.
Repeat the string value of self value times and store the resultant string in dest.
Repeat the string in self keyed by key by the quantity of value keyed by value_key and store the result in dest keyed by dest_key.
Repeat the string in self keyed by key value times and store the result in dest keyed by dest_key.
Auto-increment the PMC.
Auto-increment the PMC keyed by key. The key is guaranteed to be non-NULL.
Auto-decrement the PMC.
Auto-decrement the PMC keyed by key. The key is guaranteed to be non-NULL.
This is only valid for keyed access. Return TRUE if the key exists in the aggregate being queried; otherwise, return FALSE.
The key is guaranteed to be non-NULL.
Check to see if the PMC is defined. Return TRUE if it is; otherwise, return FALSE.
Return TRUE if the value of self keyed by key is defined; otherwise, return FALSE.
Delete the specified entry from the aggregate.
Given the passed in key for the PMC, return the next key.
Place the value of the substring of self at offset offset and with length length into dest.
Place the value of the substring of self keyed by key into dest keyed by dest_key.
Return the substring of self at offset offset and with length length.
Return a substring with offset offset and with length length of the string in self that is keyed by key.
The key is guaranteed to be not NULL.
Invoke the subroutine/method in the given PMC.
It should set up the environment for the sub, and should return the location at which operation flow should continue after the subroutine returns. (Note that this will generally be the address of the next instruction).
It is NOT responsible for preserving any of the current context; the caller should have preserved anything that they want preserved before calling this method.
See pdd03_calling_conventions.pod for more details.
XXX: I still don't understand what *next does. XXX: Is invoke_pmc used?
Determine whether the PMC can perform the method specified by name in method. Returns TRUE if it can; otherwise, returns FALSE.
Determine whether the PMC in self keyed by key can perform the method specified by name in method. Returns TRUE if it can; otherwise, returns FALSE.
Determine whether the PMC implements the interface specified by name in method. Returns TRUE if it can; otherwise, returns FALSE.
Determine whether the PMC in self keyed by key implements the interface specified by name in method. Returns TRUE if it can; otherwise, returns FALSE.
See also pdd15_objects.pod.
To install Make, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Make
CPAN shell
perl -MCPAN -e shell install Make
For more information on module installation, please visit the detailed CPAN module installation guide.