develooper Front page | perl.cvs.parrot | Postings from December 2008

[svn:parrot] r34069 - trunk/docs

From:
Whiteknight
Date:
December 18, 2008 10:11
Subject:
[svn:parrot] r34069 - trunk/docs
Message ID:
20081218181143.3DCF2CBA12@x12.develooper.com
Author: Whiteknight
Date: Thu Dec 18 10:11:41 2008
New Revision: 34069

Modified:
   trunk/docs/vtables.pod

Log:
[Docs] Removed some old cruft from this file, and add a little bit of new information.

Modified: trunk/docs/vtables.pod
==============================================================================
--- trunk/docs/vtables.pod	(original)
+++ trunk/docs/vtables.pod	Thu Dec 18 10:11:41 2008
@@ -80,21 +80,25 @@
 
     % perl tools/dev/gen_class.pl FoobyNumber > src/pmc/foobynumber.pmc
 
-This will produce a skeleton C file (to be preprocessed by the
-F<tools/build/pmc2c.pl> program) with stubs for all the methods you need to
-fill in. The function C<init> allows you to set up anything you need to set up.
-Comment out the C<namespace> method from the automatically generated set
-of methods (otherwise, the compile will fail).
+This will produce a skeleton PMC file (to be preprocessed into ordinary C
+code by the F<tools/build/pmc2c.pl> program) with stubs for all the methods
+you need to fill in. N<Actually, there are more stubs here then you probably
+I<need> to fill in. Your PMC isn't going to want to support all these
+methods, and in many cases you may want to fall back to default behavior
+instead of implementing a dummy method.> The function C<init> allows you to
+set up anything you need to set up. 
 
 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 C<enum_class_FoobyNumber> in the C<init>
-function. For built-in classes, this is automatically defined in F<pmc.h> when
-you run F<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 F<src/pmc/YOURCLASS.pmc>. Then, change the type of the C<init>
-function to return C<VTABLE>, and then return C<temp_base_vtable> instead of
-assigning to the interpreter specific C<vtables> array.
+writing a built-in class or an extension class. If you're writing a non-core
+PMC, called a "dynpmc", you need to add the argument C<dynpmc> to the line
+that starts with C<pmclass>. Here's an example:
+
+	pmclass FooByNumber dynpmc {
+		...
+
+This alerts the PMC compiler that the PMC type should not be hard-coded into
+Parrot, and that the PMC definition needs to be loaded in to Parrot
+dynamically when the user requires it.
 
 To finish up adding a built-in class:
 
@@ -102,11 +106,11 @@
 
 =item 1.
 
-Add src/pmc/YOURCLASS.pmc to the MANIFEST
+Add src/pmc/YOURCLASS.pmc to the MANIFEST.
 
 =item 2.
 
-Run C<make realclean>, and rerun F<Configure.pl> to add your new PMC to
+Run C<make realclean>, and then run F<Configure.pl> to add your new PMC to
 the set of built-in PMCs.
 
 =back
@@ -120,8 +124,7 @@
 Flags are accessed by C<< 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
-C<Pobj_private0_FLAG> .. C<Pobj_private7_FLAG>. (The '7' may change during the
-early development of parrot, but will become pretty fixed at some point.)
+C<Pobj_private0_FLAG> .. C<Pobj_private7_FLAG>.
 
 Normally, you will want to alias these generic bit names to something more
 meaningful within your class:
@@ -132,12 +135,10 @@
         ....
     };
 
-You're quite at liberty to declare these in a separate header file, but I find
-it more convenient to keep everything together in F<foobynumber.c>.  To
-manipulate the flags, use the macros listed in F<pobj.h>.
+To manipulate the flags, use the macros listed in F<pobj.h>.
 
-You may also use the C<cache> union in the PMC structure to remove some
-extraneous dereferences in your code if that would help.
+PMCs also have the ability to store an arbitrary number of user-defined
+attribute values using the C<ATTR> keyword. 
 
 =head2 Multimethods
 
@@ -156,10 +157,10 @@
 Similar shortcuts exist for strings, (C<native> and C<same>) and floating point
 numbers.
 
-=head2 Implementing methods
+=head2 Implementing VTABLE Interfaces
 
-The master list of vtable methods can be found in F<src/vtable.tbl> in the root
-directory of the Parrot source, with documentation in
+The master list of VTABLE interfaces can be found in F<src/vtable.tbl> in
+the root directory of the Parrot source, with documentation in
 F<docs/pdds/pdd02_vtables.pod>. A few of these are very important, for
 instance:
 
@@ -253,11 +254,6 @@
 
 Set yourself to the passed-in string. This is a string multimethod.
 
-=item C<set_value>
-
-Set your private data to the raw pointer passed in. This will only be used in
-exceptional circumstances.
-
 =item C<add>
 
 Fetch the number part of C<value> and add your numeric value to it, storing the
@@ -304,10 +300,10 @@
 
 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.
+from will throw an exception if the missing method ever gets 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
+inheritance. At the beginning of your VTABLE specification in
 src/pmc/YOURCLASS.pmc, add the C<extends SUPERCLASS> phrase. For example:
 
   pmclass PackedArray extends Array { ...



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About