[svn:parrot] r38816 - in trunk/docs: imcc pdds pdds/draft
coke at svn.parrot.org
coke at svn.parrot.org
Sat May 16 04:08:24 UTC 2009
Author: coke
Date: Sat May 16 04:08:22 2009
New Revision: 38816
URL: https://trac.parrot.org/parrot/changeset/38816
Log:
[docs] Mark & test more pasm/pir.
This marks most of what's left in docs,
- upgrading some samples to compile
- documenting the ones that already did,
- and marking the rest as INVALID/TODO, hopefully appropriately.
Modified:
trunk/docs/imcc/operation.pod
trunk/docs/pdds/draft/pdd08_keys.pod
trunk/docs/pdds/draft/pdd16_native_call.pod
trunk/docs/pdds/draft/pdd29_compiler_tools.pod
trunk/docs/pdds/pdd03_calling_conventions.pod
trunk/docs/pdds/pdd15_objects.pod
trunk/docs/pdds/pdd17_pmc.pod
trunk/docs/pdds/pdd19_pir.pod
trunk/docs/pdds/pdd20_lexical_vars.pod
trunk/docs/pdds/pdd21_namespaces.pod
trunk/docs/pdds/pdd22_io.pod
trunk/docs/pdds/pdd23_exceptions.pod
trunk/docs/pdds/pdd24_events.pod
trunk/docs/pdds/pdd25_concurrency.pod
trunk/docs/pdds/pdd27_multiple_dispatch.pod
Modified: trunk/docs/imcc/operation.pod
==============================================================================
--- trunk/docs/imcc/operation.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/imcc/operation.pod Sat May 16 04:08:22 2009 (r38816)
@@ -68,7 +68,7 @@
This also means that you currently can't use the same global symbol (e.g.
subroutine name) in different namespaces. The following creates invalid code:
-=begin PIR_INVALID
+=begin PIR
.sub main
#...
@@ -79,7 +79,7 @@
#...
.end
-=end PIR_INVALID
+=end PIR
Local labels in different I<compilation units> with the same name are
allowed, though assembling the generated PASM doesn't work. However,
Modified: trunk/docs/pdds/draft/pdd08_keys.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd08_keys.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/draft/pdd08_keys.pod Sat May 16 04:08:22 2009 (r38816)
@@ -212,19 +212,35 @@
constant keys have the signature C<kc>. Integer register and constant keys are
encoded as C<ki> and C<kic> respectively.
- set P1["hi"], 1234
+=begin PIR_FRAGMENT
+
+ set $P1["hi"], 1234
+
+=end PIR_FRAGMENT
finds an op named C<set_p_kc_i>. On the other hand,
- set P1[P1], 1234
+=begin PIR_FRAGMENT
+
+ set $P1[$P1], 1234
+
+=end PIR_FRAGMENT
produces an op named C<set_p_k_i>. Likewise, this:
- set P1[1], 1234
+=begin PIR_FRAGMENT
+
+ set $P1[1], 1234
+
+=end PIR_FRAGMENT
produces an op named C<set_p_kic>, and this:
- set P1[I1], 1234
+=begin PIR_FRAGMENT
+
+ set $P1[$I1], 1234
+
+=end PIR_FRAGMENT
produces an op named C<set_p_ki>.
Modified: trunk/docs/pdds/draft/pdd16_native_call.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd16_native_call.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/draft/pdd16_native_call.pod Sat May 16 04:08:22 2009 (r38816)
@@ -235,12 +235,16 @@
When the callback function is invoked by the external library, the function
itself should look like:
+=begin PIR
+
.sub _my_callback
.param pmc my_data
.param pmc library_data # type depends on signature
# Do something with the passed in data
.end
+=end PIR
+
Parrot itself handles all the nasty bits involved in collecting up the
interpreter pointer, creating the wrapping PMCs, stuffing data various places,
and generally dealing with the bookkeeping.
@@ -250,6 +254,8 @@
This section contains an example to register a callback function and have
it call back into Parrot.
+=begin PIR
+
.sub main
# set up callback
@@ -280,6 +286,8 @@
print "Foo callback\n"
.end
+=end PIR
+
The C code contains the function to be invoked through NCI. In the function
C<sayhello> a function call is done to a Parrot subroutine. The C<sayhello>
function gets a reference to this callback function, so its signature needs
Modified: trunk/docs/pdds/draft/pdd29_compiler_tools.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd29_compiler_tools.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/draft/pdd29_compiler_tools.pod Sat May 16 04:08:22 2009 (r38816)
@@ -31,6 +31,8 @@
Creating a PCT-based compiler can be done as follows:
+=begin PIR
+
.sub 'onload' :anon :load :init
load_bytecode 'PCT.pbc'
$P0 = get_hll_global ['PCT'], 'HLLCompiler'
@@ -46,6 +48,8 @@
$P1 = $P0.'command_line'(args)
.end
+=end PIR
+
{{ this is the most important part; is this enough? }}
The Parrot distribution contains a Perl script to generate a compiler
@@ -303,19 +307,35 @@
=item language
-$P0.'language'('Foo')
+=begin PIR_FRAGMENT
+
+ $P0.'language'('Foo')
+
+=end PIR_FRAGMENT
=item parsegrammar
-$P0.'parsegrammar'('Foo::Grammar')
+=begin PIR_FRAGMENT
+
+ $P0.'parsegrammar'('Foo::Grammar')
+
+=end PIR_FRAGMENT
=item parseactions
-$P0.'parseactions('Foo::Grammar::Actions')
+=begin PIR_FRAGMENT
+
+ $P0.'parseactions'('Foo::Grammar::Actions')
+
+=end PIR_FRAGMENT
=item commandline_prompt
-$P0.'commandline_prompt'($S0)
+=begin PIR_FRAGMENT
+
+ $P0.'commandline_prompt'($S0)
+
+=end PIR_FRAGMENT
sets the string in C<$S0> as a commandline prompt on the compiler in C<$P0>.
The prompt is the text that is shown on the commandline before a command is
@@ -323,7 +343,11 @@
=item commandline_banner
-$P0.'commandline_banner'($S0)
+=begin PIR_FRAGMENT
+
+ $P0.'commandline_banner'($S0)
+
+=end PIR_FRAGMENT
sets the string in C<$S0> as a commandline banner on the compiler in C<$P0>.
The banner is the first text that is shown when the compiler is started in
Modified: trunk/docs/pdds/pdd03_calling_conventions.pod
==============================================================================
--- trunk/docs/pdds/pdd03_calling_conventions.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd03_calling_conventions.pod Sat May 16 04:08:22 2009 (r38816)
@@ -342,6 +342,10 @@
=head3 Function Calls
+=begin PIR_FRAGMENT_INVALID
+
+ .local pmc foo, i, ar, y, p, value, kw, a, b, c, z
+ # ...
foo(1, i) # 2 positional arguments
foo(x, ar :flat, y) # flattening array
foo(p, 'key' => value) # named argument
@@ -351,24 +355,45 @@
# all together now: three positional (one flat) with two named (one flat)
foo(a, b, c :flat, 'x' => 3, 'y' => 4, z :flat :named('z'))
+=end PIR_FRAGMENT_INVALID
+
=head3 Parameters
- .param int i # positional parameter
- .param pmc argv :slurpy # slurpy array
- .param pmc value :named('key') # named parameter
- .param int x :optional # optional parameter
- .param int has_x :opt_flag # flag 0/1 x was passed
- .param pmc kw :slurpy :named # slurpy hash
+=begin PIR
+
+ .sub foo
+ .param int i # positional parameter
+ .param pmc argv :slurpy # slurpy array
+ .param pmc value :named('key') # named parameter
+ .param int x :optional # optional parameter
+ .param int has_x :opt_flag # flag 0/1 x was passed
+ .param pmc kw :slurpy :named # slurpy hash
+ # ...
+ .end
+
+=end PIR
=head3 Return Values
- .return (i, ar: flat, value :named('key') )
+=begin PIR_INVALID
+
+ .sub foo
+ .local pmc i, ar, value
+ .return (i, ar: flat, value :named('key') )
+ .end
+
+=end PIR_INVALID
=head3 Call Results
+=begin PIR_FRAGMENT
+
+ .local pmc x, foo, i, j, ar, value
x = foo() # single result
(i, j :optional, ar :slurpy, value :named('key') ) = foo()
+=end PIR_FRAGMENT
+
=head2 Attachments
None.
Modified: trunk/docs/pdds/pdd15_objects.pod
==============================================================================
--- trunk/docs/pdds/pdd15_objects.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd15_objects.pod Sat May 16 04:08:22 2009 (r38816)
@@ -418,7 +418,11 @@
=item name
- $P1 = $P2.name( $S3 )
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'name'( $S3 )
+
+=end PIR_FRAGMENT
The accessor for the name attribute. With no argument, it simply returns
the current value for name. When passed an argument, it sets the name of
@@ -427,13 +431,21 @@
=item namespace
- $P1 = $P2.namespace()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'namespace'()
+
+=end PIR_FRAGMENT
Retrieve the namespace object associated with the class.
=item new
- $P1 = $P2.new( 'myattrib' => "Foo" )
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'new'( 'myattrib' => "Foo" )
+
+=end PIR_FRAGMENT
Create a new instance object from the class object. It takes an optional,
slurpy, named list of attributes and values to initialize the object.
@@ -441,9 +453,13 @@
=item add_attribute
- $P1.add_attribute($S2)
- $P1.add_attribute($S2, $S3)
- $P1.add_attribute($S2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_attribute'($S2)
+ $P1.'add_attribute'($S2, $S3)
+ $P1.'add_attribute'($S2, $P3)
+
+=end PIR_FRAGMENT
Adds a single attribute to the class. It takes a simple string name and,
optionally, a simple string value or key specifying a type name. (A type
@@ -456,7 +472,11 @@
=item attributes
- $P1 = $P2.attributes()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'attributes'()
+
+=end PIR_FRAGMENT
An accessor for the attributes of the class. It returns the a Hash of
all attributes, with a key of the attribute name and a value of a Hash
@@ -464,8 +484,12 @@
=item add_method
- $P1.add_method($S2, $P3)
- $P1.add_method($S2, $P3, 'vtable' => 1)
+=begin PIR_FRAGMENT
+
+ $P1.'add_method'($S2, $P3)
+ $P1.'add_method'($S2, $P3, 'vtable' => 1)
+
+=end PIR_FRAGMENT
Adds a method to the class. It takes a simple string name and a method
PMC. If the method already exists (and isn't a Multi) it will replace
@@ -477,7 +501,11 @@
=item methods
- $P1 = $P2.methods()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'methods'()
+
+=end PIR_FRAGMENT
An accessor for the methods of the class. It returns a Hash of all
methods, with a key of the method name and a value of an invokable PMC.
@@ -486,27 +514,43 @@
=item add_parent
- $P1.add_parent($P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_parent'($P3)
+
+=end PIR_FRAGMENT
Adds a single parent to the class. It takes an instance of the Class PMC.
=item parents
- $P1 = $P2.parents()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'parents'()
+
+=end PIR_FRAGMENT
An accessor for the parents of the class. It returns an Array of all
parents. The accessor is read-only.
=item roles
- $P1 = $P2.roles()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'roles'()
+
+=end PIR_FRAGMENT
An accessor for the roles of the class. It returns an Array of all
roles. The accessor is read-only.
=item add_role
- $P1.add_role($P2, [named])
+=begin PIR_FRAGMENT_INVALID
+
+ $P1.'add_role'($P2, [named])
+
+=end PIR_FRAGMENT_INVALID
Adds a single role to the class. It takes an instance of the Role PMC as a
required positional parameter, and the optional named parameters C<exclude>
@@ -514,13 +558,21 @@
=item subclass
- $P1 = $P2.subclass($S3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'subclass'($S3)
+
+=end PIR_FRAGMENT
Create a subclass of $P2 with name $S3 and return it in $P1.
=item isa
- $I1 = $P2.isa($S3)
+=begin PIR_FRAGMENT
+
+ $I1 = $P2.'isa'($S3)
+
+=end PIR_FRAGMENT
Returns true if the class name passed in as a parameter is in the inheritance
hierarchy of the class (this is not the same as the inheritance hierarchy of
@@ -528,7 +580,11 @@
=item can
- $I1 = $P2.can($S3)
+=begin PIR_FRAGMENT
+
+ $I1 = $P2.'can'($S3)
+
+=end PIR_FRAGMENT
Returns true if the class object can perform the requested method, false
otherwise.
@@ -537,7 +593,11 @@
=item does
- $I1 = $P2.does($S3)
+=begin PIR_FRAGMENT
+
+ $I1 = $P2.'does'($S3)
+
+=end PIR_FRAGMENT
Returns true if the object in question implements the role, class, type,
or behavior passed in, false otherwise.
@@ -548,8 +608,12 @@
=item inspect
- $P1 = $P2.inspect()
- $P1 = $P2.inspect($S3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'inspect'()
+ $P1 = $P2.'inspect'($S3)
+
+=end PIR_FRAGMENT
Return introspection information for the class.
@@ -798,7 +862,11 @@
=item name
- $P1 = $P2.name( $S3 )
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'name'( $S3 )
+
+=end PIR_FRAGMENT
The accessor for the name attribute. With no argument, it simply returns
the current value for name. When passed an argument, it sets the name of
@@ -806,13 +874,21 @@
=item namespace
- $P1 = $P2.namespace()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'namespace'()
+
+=end PIR_FRAGMENT
Retrieve the namespace object associated with the role.
=item attributes
- $P1 = $P2.attributes()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'attributes'()
+
+=end PIR_FRAGMENT
An accessor for the attributes of the role. It returns the Hash of all
attributes, with a key of the attribute name, and a value of the
@@ -820,9 +896,13 @@
=item add_attribute
- $P1.add_attribute($S2)
- $P1.add_attribute($S2, $S3)
- $P1.add_attribute($S2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_attribute'($S2)
+ $P1.'add_attribute'($S2, $S3)
+ $P1.'add_attribute'($S2, $P3)
+
+=end PIR_FRAGMENT
Adds a single attribute to the role. It takes a simple string name, and
optionally, a simple string value or key specifying a type name. (A type
@@ -831,7 +911,11 @@
=item add_role
- $P1.add_role($P2, [named])
+=begin PIR_FRAGMENT_INVALID
+
+ $P1.'add_role'($P2, [named])
+
+=end PIR_FRAGMENT_INVALID
Adds a single role to the role. It takes an instance of the Role PMC as a
required positional parameter, and the optional named parameters C<exclude>
@@ -839,7 +923,11 @@
=item roles
- $P1 = $P2.roles()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'roles'()
+
+=end PIR_FRAGMENT
An accessor for the roles composed into the role. It returns an Array of all
roles as PMC objects. If any roles that were composed into this one were
@@ -849,8 +937,12 @@
=item add_method
- $P1.add_method($S2, $P3)
- $P1.add_method($S2, $P3, 'vtable' => 1)
+=begin PIR_FRAGMENT
+
+ $P1.'add_method'($S2, $P3)
+ $P1.'add_method'($S2, $P3, 'vtable' => 1)
+
+=end PIR_FRAGMENT
Adds a method to the role. It takes a simple string name and a method
PMC. If the method already exists (and isn't a Multi) it will replace
@@ -862,7 +954,11 @@
=item methods
- $P1 = $P2.methods()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'methods'()
+
+=end PIR_FRAGMENT
An accessor for the methods of the role. It returns a Hash of all methods,
with a key of the method name and a value of an invokable PMC. The list will
@@ -871,8 +967,12 @@
=item inspect
- $P1 = $P2.inspect()
- $P1 = $P2.inspect($S3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'inspect'()
+ $P1 = $P2.'inspect'($S3)
+
+=end PIR_FRAGMENT
Return introspection information for the role.
@@ -935,9 +1035,13 @@
=item getattribute
+=begin PIR_FRAGMENT
+
$P1 = getattribute $P2, $S3
$P1 = getattribute $P2, $P3, $S4
+=end PIR_FRAGMENT
+
Get the attribute with the fully qualified name $S3 from object $P2 and put it
in $P1. To get an attribute for a parent class that has the same name as an
attribute in the child class, pass an optional class object or namespace key
@@ -948,9 +1052,13 @@
=item setattribute
+=begin PIR_FRAGMENT
+
setattribute $P1, $S2, $P3
setattribute $P1, $P2, $S3, $P4
+=end PIR_FRAGMENT
+
Set the attribute of object $P1 with the attribute name $S2 to $P3. To set an
attribute for a parent class that has the same name as an attribute in the
child class, pass an optional class object or namespace key $P2 for the parent
@@ -960,14 +1068,22 @@
=item callmethod
+=begin PIR_FRAGMENT
+
callmethod $P1, $S1, $P2
+=end PIR_FRAGMENT
+
Call the method specified in the attribute $S1 using $P1 as the invocant and
using the continuation passed in $P2. If you need to create a new continuation
use C<callmethodcc>.
+=begin PIR_FRAGMENT
+
callmethod $P1, $P2, $P3
+=end PIR_FRAGMENT
+
Call the method specified in the Sub object $P2 using $P1 as the invocant and
using the continuation passed in $P3. If you need to create a new continuation
use C<callmethodcc>.
@@ -975,9 +1091,13 @@
=item callmethodcc
+=begin PIR_FRAGMENT
+
callmethodcc $P1, $S1
callmethodcc $P1, $P2
+=end PIR_FRAGMENT
+
Call the method specified in the attribute $S1, or in the Sub object $P2,
using $P1 as the invocant for method lookup and generate a new return
continuation.
@@ -986,9 +1106,13 @@
=item callmethodsupercc [hypothetical, 2.0 or later]
+=begin PIR_FRAGMENT_TODO
+
callmethodsupercc $P1, $S1
callmethodsupercc $P1, $P2
+=end PIR_FRAGMENT_TODO
+
Call the method specified in the attribute $S1, or in the Sub object $P2,
using $P1 as the invocant for method lookup and generate a new return
continuation. This is a variant of C<callmethodcc> that skips over the
@@ -997,9 +1121,13 @@
=item callmethodnextcc [hypothetical, 2.0 or later]
+=begin PIR_FRAGMENT_TODO
+
callmethodnextcc $P1, $S1
callmethodnextcc $P1, $P2
+=end PIR_FRAGMENT_TODO
+
Call the method specified in the attribute $S1, or in the Sub object $P2,
using $P1 as the invocant for method lookup and generate a new return
continuation. A variant of C<callmethodcc> that picks up an existing
@@ -1010,14 +1138,20 @@
=item newclass
+=begin PIR_FRAGMENT_INVALID
+
$P1 = newclass $S2
$P1 = newclass $S2, $P3
+=end PIR_FRAGMENT_INVALID
+
Create a new base class named $S2, and put the PMC for it in $P1. You may
optionally pass a hash of initialization parameters for the class in $P3.
=item subclass
+=begin PIR_FRAGMENT
+
$P1 = subclass $S2
$P1 = subclass $P2
$P1 = subclass $S2, $S3
@@ -1025,15 +1159,21 @@
$P1 = subclass $S2, $P3
$P1 = subclass $P2, $P3
+=end PIR_FRAGMENT
+
Create a new class, named $S3, which has $P2 as its immediate parent. $P2 may
be either another high-level class based on the Class PMC, or it may be a
low-level PMC such as C<Integer> or C<ResizablePMCArray>.
=item get_class
+=begin PIR_FRAGMENT
+
$P1 = get_class $S2
$P1 = get_class $P2
+=end PIR_FRAGMENT
+
Retrieve a class object for the class identified by the string name in
$S2, or by the PMC key or namespace object in $P2.
@@ -1046,9 +1186,13 @@
=item typeof
+=begin PIR_FRAGMENT
+
$S1 = typeof $P2
$P1 = typeof $P2
+=end PIR_FRAGMENT
+
Lookup the type of the instance object in $P2. Return the string name if the
destination is a string register or variable. If the destination is a PMC
register or variable, return the class object for an instance of a high-level
@@ -1056,37 +1200,53 @@
=item new
+=begin PIR_FRAGMENT
+
$P1 = new $S2
$P1 = new $S2, $P3
$P1 = new $P2
$P1 = new $P2, $P3
+=end PIR_FRAGMENT
+
Create a new object from the class named by $S2 or $P2 (a string PMC,
namespace key, or class object), and put the PMC for it in $P1. You may
optionally pass a hash of initialization parameters for the class in $P3.
=item addparent
+=begin PIR_FRAGMENT
+
addparent $P1, $P2
+=end PIR_FRAGMENT
+
Add class $P2 to the end of the list of immediate parents of class $P1.
Adds any attributes of $P2 (and its parent classes) that aren't already
in $P1.
=item removeparent
+=begin PIR_FRAGMENT
+
removeparent $P1, $P2
+=end PIR_FRAGMENT
+
Remove class $P2 from the parent list of $P1. All parent classes of $P2
which aren't parent classes of what remains of $P1's parent list are
removed, as are their attributes.
=item addattribute
+=begin PIR_FRAGMENT_INVALID
+
addattribute $P1, $S2
addattribute $P1, $S2, $S3
addattribute $P1, $S2, $P3
+=end PIR_FRAGMENT_INVALID
+
Add attribute $S2 to class or role $P1. This will add the attribute slot
to all objects of class $P1, classes that inherit from class $P1, or
classes that compose the role $P1, with a default value of C<Null>. It
@@ -1095,8 +1255,12 @@
=item removeattribute
+=begin PIR_FRAGMENT
+
removeattribute $P1, $S2
+=end PIR_FRAGMENT
+
Remove the attribute $S2 from class or role $P1. This will not remove
the attribute from any objects that have already been instantiated, but
it will be absent from all future objects of class $P1, of classes that
@@ -1104,16 +1268,24 @@
=item addrole
+=begin PIR_FRAGMENT
+
addrole $P1, $P2
+=end PIR_FRAGMENT
+
Add role $P2 to the end of the list of roles of class or role $P1. Adds
any methods and attributes of $P2 that aren't already in $P1.
=item inspect
+=begin PIR_FRAGMENT
+
$P1 = inspect $P2
$P1 = inspect $P2, $S3
+=end PIR_FRAGMENT
+
Return introspection information for the PMC. Without the optional string
argument, return a data structure of all information relevant to
introspection. With the optional string argument, return a PMC Hash, Array,
@@ -1130,18 +1302,26 @@
=item :method
+=begin PIR
+
.sub custom_method :method
# ...
.end
+=end PIR
+
Flags the code entity as a method.
=item :vtable
+=begin PIR
+
.sub get_integer :vtable
# ...
.end
+=end PIR
+
Flags the code entity as a vtable override.
=back
@@ -1187,57 +1367,85 @@
To create a new class C<Foo> which has no parent classes:
+=begin PIR_FRAGMENT
+
newclass $P0, "Foo"
+=end PIR_FRAGMENT
+
=head3 Creating a new class with multiple parents
To create a class C<Foo> with the parents C<A> and C<B>, the code would be:
+=begin PIR_FRAGMENT
+
get_class $P0, "A"
get_class $P1, "B"
subclass $P2, $P0, "Foo"
addparent $P2, $P1
+=end PIR_FRAGMENT
+
=head3 Creating a new class with attributes
Adding the attributes C<a> and C<b> to the new class C<Foo>:
+=begin PIR_FRAGMENT
+
$P0 = newclass "Foo"
addattribute $P0, "a"
addattribute $P0, "b"
+=end PIR_FRAGMENT
+
=head3 Instantiating an object
Assuming we want an object of class C<Foo>:
+=begin PIR_FRAGMENT
+
.local pmc FooClass
.local pmc MyObject
FooClass = get_class "Foo"
- MyObject = FooClass.new()
+ MyObject = FooClass.'new'()
+
+=end PIR_FRAGMENT
=head3 Calling a method on an object
Calling the method C<Xyzzy> on an object, assuming the PDD03 calling
conventions are respected:
+=begin PIR_FRAGMENT_INVALID
+
callmethod "Xyzzy"
set S0, "Xyzzy"
callmethod
+=end PIR_FRAGMENT_INVALID
+
Or, if a return continuation needs constructing:
+=begin PIR_FRAGMENT_INVALID
+
callmethodcc "Xyzzy"
set S0, "Xyzzy"
callmethodcc
+=end PIR_FRAGMENT_INVALID
+
=head3 Accessing attributes from within a class
With named access:
+=begin PIR_FRAGMENT
+
getattribute $P1, $P0, "Foo\x0b"
+=end PIR_FRAGMENT
+
=head2 Explanations
To get a new class, you can do a C<newclass>, which creates a new class
Modified: trunk/docs/pdds/pdd17_pmc.pod
==============================================================================
--- trunk/docs/pdds/pdd17_pmc.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd17_pmc.pod Sat May 16 04:08:22 2009 (r38816)
@@ -310,9 +310,13 @@
retrieving the namespace object, and then instantiating from that
namespace.
+=begin PIR_FRAGMENT
+
$P0 = get_root_namespace ['parrot'; 'Integer']
$P1 = new $P0
+=end PIR_FRAGMENT
+
HLLs can choose to provide direct access to Parrot's core PMC types by
aliasing them within the HLL namespace.
@@ -380,14 +384,22 @@
Therefore, subclassing a PMC looks, at a PIR level, like subclassing a high
level class.
+=begin PIR_FRAGMENT
+
$P0 = get_class 'Hash'
$P1 = newclass 'MyClass'
addparent $P1, $P0 # The new class inherits from the Hash PMC
+=end PIR_FRAGMENT
+
Or, more briefly:
+=begin PIR_FRAGMENT
+
$P1 = subclass 'Hash', 'MyClass'
+=end PIR_FRAGMENT
+
PMCs store state in a very different way to PDD15 objects. When a method
inherited from a PMC is called on a PDD15 object, that method needs to
access the attributes of the inherited low-level PMC. Further, if
Modified: trunk/docs/pdds/pdd19_pir.pod
==============================================================================
--- trunk/docs/pdds/pdd19_pir.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd19_pir.pod Sat May 16 04:08:22 2009 (r38816)
@@ -89,17 +89,25 @@
name must be unique within a subroutine, but it can be reused in other
subroutines.
+=begin PIR_FRAGMENT
+
goto label1
- ...
+ # ...
label1:
+=end PIR_FRAGMENT
+
=head4 Registers and Variables
There are two ways of referencing Parrot's registers. The first is
through named local variables declared with C<.local>.
+=begin PIR_FRAGMENT
+
.local pmc foo
+=end PIR_FRAGMENT
+
The type of a named variable can be C<int>, C<num>, C<string> or C<pmc>,
corresponding to the types of registers. No other types are used.
@@ -140,33 +148,48 @@
Assignment of a heredoc:
+=begin PIR_FRAGMENT
+
$S0 = <<"EOS"
...
- EOS
+EOS
+
+=end PIR_FRAGMENT
A heredoc as an argument:
+=begin PIR_FRAGMENT
+
+ .local pmc function, arg
+ # ...
+
function(<<"END_OF_HERE", arg)
...
- END_OF_HERE
+END_OF_HERE
- .return(<<'EOS')
+ .yield(<<'EOS')
...
- EOS
+EOS
- .yield(<<'EOS')
+ .return(<<'EOS')
...
- EOS
+EOS
+
+=end PIR_FRAGMENT
Although currently not possible, a future implementation of the PIR
language will allow you to use multiple heredocs within a single
statement or directive:
+=begin PIR_FRAGMENT_TODO
+
function(<<'INPUT', <<'OUTPUT', 'some test')
...
- INPUT
+INPUT
...
- OUTPUT
+OUTPUT
+
+=end PIR_FRAGMENT_TODO
=item charset:"string constant"
@@ -247,19 +270,31 @@
Declare a lexical variable that is an alias for a PMC register. For example,
given this preamble:
+=begin PIR_FRAGMENT
+
.lex '$a', $P0
$P1 = new 'Integer'
+=end PIR_FRAGMENT
+
These two opcodes have an identical effect:
+=begin PIR_FRAGMENT
+
$P0 = $P1
store_lex '$a', $P1
+=end PIR_FRAGMENT
+
And these two opcodes also have an identical effect:
+=begin PIR_FRAGMENT
+
$P1 = $P0
$P1 = find_lex '$a'
+=end PIR_FRAGMENT
+
=item .const <type> <identifier> = <const>
Define a constant named I<identifier> of type I<type> and assign value
@@ -312,8 +347,12 @@
You can specify the root namespace by using empty brackets, such as:
+=begin PIR
+
.namespace [ ]
+=end PIR
+
The brackets are not optional, although the key inside them is.
=item .loadlib 'lib_name'
@@ -349,10 +388,14 @@
Makes an entry in the bytecode annotations table. This is used to store high
level language debug information. Examples:
+=begin PIR_FRAGMENT
+
.annotate "file", "aardvark.p6"
.annotate "line", 5
.annotate "column", 24
+=end PIR_FRAGMENT
+
An annotation stays in effect until the next annotation with the same key or
the end of the current compilation unit (that is, if you use a tool such as
C<pbc_merge> to link multiple bytecode files, then annotations will not spill
@@ -362,14 +405,22 @@
line of HLL code is 15 lines of PIR, you only need to emit one annotation
before the first of those 15 lines to set the line number.
+=begin PIR_FRAGMENT
+
.annotate "line", 42
+=end PIR_FRAGMENT
+
The key must always be a quoted string. The value may be an integer, a number
or a quoted string. Note that integer values are stored most compactly; should
you instead of the above annotate directive emit:
+=begin PIR_FRAGMENT
+
.annotate "line", "42"
+=end PIR_FRAGMENT
+
then instead "42" is stored as a string, taking up more space in the resulting
bytecode file.
@@ -430,6 +481,8 @@
'init' in the constants table, the value returned by 'init' is stored,
which in this example is a FixedIntegerArrray.
+=begin PIR
+
.sub main :main
.const "Sub" initsub = "init"
.end
@@ -443,6 +496,7 @@
.return (array)
.end
+=end PIR
=item :postcomp
@@ -452,12 +506,18 @@
As an example, suppose file C<main.pir> contains:
+=begin PIR
+
.sub main
load_bytecode 'foo.pir'
.end
+=end PIR
+
and the file C<foo.pir> contains:
+=begin PIR
+
.sub foo :immediate
print '42'
.end
@@ -466,6 +526,8 @@
print '43'
.end
+=end PIR
+
Executing C<foo.pir> will run both C<foo> and C<bar>. On the other hand,
executing C<main.pir> will run only C<foo>. If C<foo.pir> is compiled to
bytecode, only C<foo> will be run, and loading C<foo.pbc> will not run either
@@ -473,8 +535,17 @@
=item :method
+=begin PIR
+
.sub bar :method
+ # ...
+ .end
+
.sub bar :method('foo')
+ # ...
+ .end
+
+=end PIR
The marked C<.sub> is a method, added as a method in the class that
corresponds to the current namespace, and not stored in the namespace.
@@ -485,8 +556,17 @@
=item :vtable
+=begin PIR
+
.sub bar :vtable
+ # ...
+ .end
+
.sub bar :vtable('foo')
+ # ...
+ .end
+
+=end PIR
The marked C<.sub> overrides a vtable function, and is not stored in the
namespace. By default, it overrides a vtable function with the same name
@@ -619,12 +699,17 @@
retrieve the thrown exception, use the C<.get_results> directive. This
directive always takes one argument: an exception object.
+=begin PIR_FRAGMENT
+
push_eh handler
- ...
+ # ...
handler:
.local pmc exception
.get_results (exception)
- ...
+ # ...
+
+=end PIR_FRAGMENT
+
This is syntactic sugar for the C<get_results> op, but any flags set on the
targets will be handled automatically by the PIR compiler.
@@ -634,12 +719,17 @@
To resume execution after handling the exception, just invoke the continuation
stored in the exception.
- ...
+=begin PIR_FRAGMENT
+
+ .local pmc exception, continuation
+ # ...
.get_results(exception)
- ...
+ # ...
continuation = exception['resume']
continuation()
- ...
+ # ...
+
+=end PIR_FRAGMENT
See L<PDD23|pdds/pdd23_exceptions.pod> for accessing the various attributes
of the exception object.
@@ -739,12 +829,20 @@
opcode is placed before the C<=>, and all remaining arguments go after the
opcode name. For example:
+=begin PIR_FRAGMENT
+
new $P0, 'Type'
+=end PIR_FRAGMENT
+
becomes:
+=begin PIR_FRAGMENT
+
$P0 = new 'Type'
+=end PIR_FRAGMENT
+
Note that this only works for opcodes that have have a leading C<OUT>
parameter. [this restriction unimplemented: RT #36283]
@@ -848,8 +946,12 @@
=item * C<.macro_const> <identifier> (<literal>|<reg>)
+=begin PIR
+
.macro_const PI 3.14
+=end PIR
+
The C<.macro_const> directive is a special type of macro; it allows the user
to use a symbolic name for a constant value. Like C<.macro>, the substitution
occurs at compile time. It takes two arguments (not comma separated), the
@@ -868,10 +970,14 @@
A macro expansion is a dot-prefixed identifier. For instance, if a macro
was defined as shown below:
+=begin PIR
+
.macro foo(bar)
- ...
+ # ...
.endm
+=end PIR
+
this macro can be expanded by writing C<.foo(42)>. The body of the macro
will be inserted at the point where the macro expansion is written.
@@ -885,10 +991,14 @@
The parameter list for a macro is specified in parentheses after the name of
the macro. Macro parameters are not typed.
+=begin PIR
+
.macro foo(bar, baz, buz)
- ...
+ # ...
.endm
+=end PIR
+
The number of arguments in the call to a macro must match the number of
parameters in the macro's parameter list. Macros do not perform multidispatch,
so you can't have two macros with the same name but different parameters.
@@ -897,17 +1007,25 @@
If a macro defines no parameter list, parentheses are optional on both the
definition and the call. This means that a macro defined as:
+=begin PIR
+
.macro foo
- ...
+ # ...
.endm
+=end PIR
+
can be expanded by writing either C<.foo> or C<.foo()>. And a macro definition
written as:
+=begin PIR
+
.macro foo()
- ...
+ # ...
.endm
+=end PIR
+
can also be expanded by writing either C<.foo> or C<.foo()>.
B<Note: IMCC requires you to write parentheses if the macro was declared with
@@ -922,6 +1040,8 @@
implementation of PIR ("PIRC") will be able to handle this correctly.
This means that, currently, when using IMCC, the following is not allowed:
+=begin PIR_TODO
+
.macro foo(bar)
...
.endm
@@ -930,13 +1050,16 @@
This is a heredoc
string.
- EOS
+EOS
+=cut PIR_TODO
Using braces, { }, allows you to span multiple lines for an argument.
See runtime/parrot/include/hllmacros.pir for examples and possible usage.
A simple example is this:
+=begin PIR
+
.macro foo(a,b)
.a
.b
@@ -951,8 +1074,12 @@
})
.end
+=cut PIR
+
This will expand the macro C<foo>, after which the input to the PIR parser is:
+=begin PIR
+
.sub main
print "1"
print "2"
@@ -960,6 +1087,8 @@
print "4"
.end
+=cut PIR
+
which will result in the output:
1234
@@ -971,12 +1100,15 @@
Within the macro body, the user can declare a unique label identifier using
the value of a macro parameter, like so:
+=begin PIR
+
.macro foo(a)
- ...
+ # ...
.label $a:
- ...
+ # ...
.endm
+=cut PIR
=head4 Unique local variables
@@ -985,41 +1117,53 @@
Within the macro body, the user can declare a local variable with a unique
name.
+=begin PIR
+
.macro foo()
- ...
+ # ...
.macro_local int b
- ...
+ # ...
.b = 42
print .b # prints the value of the unique variable (42)
- ...
+ # ...
.endm
+=cut PIR
+
The C<.macro_local> directive declares a local variable with a unique name in
the macro. When the macro C<.foo()> is called, the resulting code that is
given to the parser will read as follows:
+=begin PIR
+
.sub main
.local int local__foo__b__2
- ...
+ # ...
local__foo__b__2 = 42
print local__foo__b__2
.end
+=cut
+
The user can also declare a local variable with a unique name set to the
symbolic value of one of the macro parameters.
+=begin PIR
+
.macro foo(b)
- ...
+ # ...
.macro_local int $b
- ...
+ # ...
.$b = 42
print .$b # prints the value of the unique variable (42)
print .b # prints the value of parameter "b", which is
# also the name of the variable.
- ...
+ # ...
.endm
+=end PIR
+
So, the special C<$> character indicates whether the symbol is interpreted as
just the value of the parameter, or that the variable by that name is meant.
Obviously, the value of C<b> should be a string.
@@ -1027,6 +1171,8 @@
The automatic name munging on C<.macro_local> variables allows for using
multiple macros, like so:
+=begin PIR
+
.macro foo(a)
.macro_local int $a
.endm
@@ -1040,13 +1186,19 @@
.bar("x")
.end
+=end PIR
+
This will result in code for the parser as follows:
+=begin PIR
+
.sub main
.local int local__foo__x__2
.local int local__bar__x__4
.end
+=end PIR
+
Each expansion is associated with a unique number; for labels declared with
C<.macro_label> and locals declared with C<.macro_local> expansions, this
means that multiple expansions of a macro will not result in conflicting
@@ -1056,24 +1208,38 @@
Defining a non-unique variable can still be done, using the normal syntax:
+=begin PIR
+
.macro foo(b)
.local int b
.macro_local int $b
.endm
+=end PIR
+
When invoking the macro C<foo> as follows:
+=begin PIR_FRAGMENT
+
.foo("x")
+=end PIR_FRAGMENT
+
there will be two variables: C<b> and C<x>. When the macro is invoked twice:
+=begin PIR
+
.sub main
.foo("x")
.foo("y")
.end
+=begin PIR
+
the resulting code that is given to the parser will read as follows:
+=begin PIR
+
.sub main
.local int b
.local int local__foo__x
@@ -1081,6 +1247,8 @@
.local int local__foo__y
.end
+=end PIR
+
Obviously, this will result in an error, as the variable C<b> is defined
twice. If you intend the macro to create unique variables names, use
C<.macro_local> instead of C<.local> to take advantage of the name munging.
@@ -1092,6 +1260,8 @@
A simple subroutine, marked with C<:main>, indicating it's the entry point
in the file. Other sub flags include C<:load>, C<:init>, etc.
+=begin PIR
+
.sub sub_label :main
.param int a
.param int b
@@ -1103,11 +1273,15 @@
.end
+=end PIR
+
=head3 Subroutine Call
Invocation of a subroutine. In this case a continuation subroutine is
created.
+=begin PIR_FRAGMENT
+
.const "Sub" $P0 = "sub_label"
$P1 = new 'Continuation'
set_addr $P1, ret_addr
@@ -1125,8 +1299,12 @@
.get_result r
.end_call
+=end PIR_FRAGMENT
+
=head3 NCI Call
+=begin PIR_FRAGMENT
+
load_lib $P0, "libname"
dlfunc $P1, $P0, "funcname", "signature"
# ...
@@ -1139,28 +1317,39 @@
.get_result r
.end_call
+=end PIR_FRAGMENT
+
=head3 Subroutine Call Syntactic Sugar
Below there are three different ways to invoke the subroutine C<sub_label>.
The first retrieves a single return value, the second retrieves 3 return
values, whereas the last discards any return values.
+=begin PIR_FRAGMENT
+
.local int r0, r1, r2
r0 = sub_label($I0, $I1, $I2)
(r0, r1, r2) = sub_label($I0, $I1, $I2)
sub_label($I0, $I1, $I2)
+=end PIR_FRAGMENT
+
This also works for NCI calls, as the subroutine PMC will be
a NCI sub, and on invocation will do the Right Thing.
Instead of the label a subroutine object can be used too:
+=begin PIR_FRAGMENT
+
get_global $P0, "sub_label"
$P0(args)
+=end PIR_FRAGMENT
=head3 Methods
+=begin PIR
+
.namespace [ "Foo" ]
.sub _sub_label :method [,Subpragma, ...]
@@ -1176,6 +1365,8 @@
...
.end
+=end PIR
+
The variable "self" automatically refers to the invocating object, if the
subroutine declaration contains "method".
@@ -1184,6 +1375,8 @@
The syntax is very similar to subroutine calls. The call is done with
C<.meth_call> which must immediately be preceded by the C<.invocant>:
+=begin PIR_FRAGMENT
+
.local int x, y, z
.local pmc class, obj
newclass class, "Foo"
@@ -1199,6 +1392,9 @@
.end_call
...
+=end PIR_FRAGMENT
+
+
The return continuation is optional. The method can be a string
constant or a string variable.
Modified: trunk/docs/pdds/pdd20_lexical_vars.pod
==============================================================================
--- trunk/docs/pdds/pdd20_lexical_vars.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd20_lexical_vars.pod Sat May 16 04:08:22 2009 (r38816)
@@ -14,9 +14,11 @@
=head2 Synopsis
+=begin PIR
+
.sub 'foo'
.lex "$a", $P0
- $P1 = new Integer
+ $P1 = new 'Integer'
$P1 = 13013
store_lex "$a", $P1
print $P0 # prints 13013
@@ -44,13 +46,14 @@
.sub grault :lex # without ":lex", Tcl subs have no lexicals
$P0 = find_lex "x" # FAILS
- $P0 = new Integer # really TclInteger
- $P0 = 42
+ box $P0, 42 # really TclInteger
store_lex "x", $P0 # creates lexical "x"
$P0 = find_lex "x" # SUCCEEDS
.end
+=end PIR
+
=head2 Description
For Parrot purposes, "lexical variables" are variables stored in a
@@ -125,7 +128,13 @@
This is normally a static attribute of a Sub, but can be changed
dynamically using the C<set_outer> method.
+=begin PIR
+
.sub 'a' :outer('foo')
+ # ...
+ .end
+
+=end PIR
The value of C<:outer> identifies a subroutine by its C<:subid>
flag; subroutine definitions that do not have an explicit C<:subid>
@@ -142,9 +151,11 @@
the current sub. This is normally done either when the outer
sub is entered or just prior to invoking the inner sub.
+=begin PIR
+
.sub 'a'
.lex '$a', $P0
- ...
+ # ...
# capture current lexical environment for inner sub 'foo'
.const 'Sub' $P0 = 'foo'
capture_lex $P0
@@ -152,9 +163,13 @@
'foo'()
.end
+=end PIR
+
The C<newclosure> opcode will clone a subroutine and then perform
C<capture_lex> on the newly cloned sub.
+=begin PIR
+
.sub 'a'
.lex '$a', $P0
@@ -164,6 +179,8 @@
$P1()
.end
+=end PIR
+
=head4 Lexical Lookup Algorithm
When a subroutine is invoked, its newly created call frame
@@ -256,19 +273,31 @@
compiler calls this method in response to a C<.lex STRING, PREG> directive.
For example, given this preamble:
+=begin PIR_FRAGMENT
+
.lex "$a", $P0
- $P1 = new Integer
+ $P1 = new 'Integer'
+
+=end PIR_FRAGMENT
These two opcodes have an identical effect:
+=begin PIR_FRAGMENT
+
$P0 = $P1
store_lex "$a", $P1
+=end PIR_FRAGMENT
+
And these two opcodes also have an identical effect:
+=begin PIR_FRAGMENT
+
$P1 = $P0
$P1 = find_lex "$a"
+=end PIR_FRAGMENT
+
=back
=head4 LexPad
@@ -314,36 +343,56 @@
For example, to get the immediate caller's LexPad, use:
+=begin PIR_FRAGMENT
+
$P0 = getinterp
$P1 = $P0["lexpad"; 1]
+=end PIR_FRAGMENT
+
To access a sub's C<:outer> subroutine, use the C<get_outer()> method:
+=begin PIR_FRAGMENT
+
.include "interpinfo.pasm"
interpinfo $P1, .INTERPINFO_CURRENT_SUB
$P2 = $P1."get_outer"()
+=end PIR_FRAGMENT
+
Here, C<$P1> contains information on the current subroutine. C<$P2> will
contain C<$P1>'s outer subroutine.
To get C<$P2>'s outer subroutine (if any), the same method can be used on
C<$P2> itself:
+=begin PIR_FRAGMENT
+
$P3 = $P2."get_outer"()
+=end PIR_FRAGMENT
Using the C<interpinfo> instruction is one way to do it. Another way is this:
+=begin PIR_FRAGMENT
+
$P0 = getinterp
$P1 = $P0["outer"; "sub"]
$P2 = $P0["outer"; "sub"; 2] # get the outer sub of the current's outer
# subroutine
+=end PIR_FRAGMENT
+
+
It is also possible to get the C<:outer> sub's LexPad, as above:
+=begin PIR_FRAGMENT
+
$P0 = getinterp
$P1 = $P0["outer"; "lexpad"]
+=end PIR_FRAGMENT
+
See [1] for an example.
It's likely that this interface will continue to be available even once call
Modified: trunk/docs/pdds/pdd21_namespaces.pod
==============================================================================
--- trunk/docs/pdds/pdd21_namespaces.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd21_namespaces.pod Sat May 16 04:08:22 2009 (r38816)
@@ -139,7 +139,11 @@
=item C<get_name>
- $P1 = $P2.get_name()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'get_name'()
+
+=end PIR_FRAGMENT
Gets the name of the namespace $P2 as an array of strings. For example,
if $P2 is a Perl 5 namespace "Some::Module", within the Perl 5 HLL, then
@@ -172,19 +176,31 @@
=item C<add_namespace>
- $P1.add_namespace($S2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_namespace'($S2, $P3)
+
+=end PIR_FRAGMENT
Store $P3 as a namespace under the namespace $P1, with the name of $S2.
=item C<add_sub>
- $P1.add_sub($S2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_sub'($S2, $P3)
+
+=end PIR_FRAGMENT
Store $P3 as a subroutine with the name of $S2 in the namespace $P1.
=item C<add_var>
- $P1.add_var($S2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'add_var'($S2, $P3)
+
+=end PIR_FRAGMENT
Store $P3 as a variable with the name of $S2 in the namespace $P1.
@@ -195,17 +211,25 @@
=item C<del_namespace>, C<del_sub>, C<del_var>
- $P1.del_namespace($S2)
- $P1.del_sub($S2)
- $P1.del_var($S2)
+=begin PIR_FRAGMENT
+
+ $P1.'del_namespace'($S2)
+ $P1.'del_sub'($S2)
+ $P1.'del_var'($S2)
+
+=end PIR_FRAGMENT
Delete the sub, namespace, or variable named $S2 from the namespace $P1.
=item C<find_namespace>, C<find_sub>, C<find_var>
- $P1 = $P2.find_namespace($S3)
- $P1 = $P2.find_sub($S3)
- $P1 = $P2.find_var($S3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'find_namespace'($S3)
+ $P1 = $P2.'find_sub'($S3)
+ $P1 = $P2.'find_var'($S3)
+
+=end PIR_FRAGMENT
Find the sub, namespace, or variable named $S3 in the namespace $P2.
@@ -217,7 +241,11 @@
=item C<export_to>
- $P1.export_to($P2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'export_to'($P2, $P3)
+
+=end PIR_FRAGMENT
Export items from the namespace $P1 into the namespace $P2. The items to
export are named in $P3, which may be an array of strings, a hash, or null.
@@ -266,7 +294,11 @@
=item C<parse_name>
- $P1 = $P2.parse_name($S3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'parse_name'($S3)
+
+=end PIR_FRAGMENT
Parse the name in $S3 using the rules specific to the compiler $P2, and
return an array of individual name elements.
@@ -278,7 +310,11 @@
=item C<get_namespace>
- $P1 = $P2.get_namespace($P3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'get_namespace'($P3)
+
+=end PIR_FRAGMENT
Ask the compiler $P2 to find its namespace which is named by the
elements of the array in $P3. If $P3 is a null PMC or an empty array,
@@ -298,7 +334,11 @@
=item C<load_library>
- $P1.load_library($P2, $P3)
+=begin PIR_FRAGMENT
+
+ $P1.'load_library'($P2, $P3)
+
+=end PIR_FRAGMENT
Ask this compiler to load a library/module named by the elements of the array
in $P2, with optional control information in $P3.
@@ -325,7 +365,11 @@
=item C<get_namespace>
- $P1 = $P2.get_namespace()
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'get_namespace'()
+
+=end PIR_FRAGMENT
Retrieve the namespace $P1 where the subroutine $P2 was defined. (As
opposed to the namespace(s) that it may have been exported to.)
@@ -344,40 +388,60 @@
=item C<set_namespace>
- set_namespace [key], $P1
- set_hll_namespace [key], $P1
- set_root_namespace [key], $P1
+=begin PIR_FRAGMENT_INVALID
+
+ set_namespace ['key'], $P1
+ set_hll_namespace ['key'], $P1
+ set_root_namespace ['key'], $P1
+
+=end PIR_FRAGMENT_INVALID
Add the namespace PMC $P1 under the name denoted by a multidimensional
hash key.
+=begin PIR_FRAGMENT_INVALID
+
set_namespace $P1, $P2
set_hll_namespace $P1, $P2
set_root_namespace $P1, $P2
+=end PIR_FRAGMENT_INVALID
+
Add the namespace PMC $P2 under the name denoted by an array of name
strings $P1.
=item C<get_namespace>
+=begin PIR_FRAGMENT
+
$P1 = get_namespace
$P1 = get_hll_namespace
$P1 = get_root_namespace
+=end PIR_FRAGMENT
+
Retrieve the current namespace, the HLL root namespace, or the true
root namespace and store it in $P1.
+=begin PIR_FRAGMENT_INVALID
+
$P1 = get_namespace [key]
$P1 = get_hll_namespace [key]
$P1 = get_root_namespace [key]
+=end PIR_FRAGMENT_INVALID
+
Retrieve the namespace denoted by a multidimensional hash key and
store it in C<$P1>.
+=begin PIR_FRAGMENT
+
$P1 = get_namespace $P2
$P1 = get_hll_namespace $P2
$P1 = get_root_namespace $P2
+=end PIR_FRAGMENT
+
Retrieve the namespace denoted by the array of names $P2 and store it in
C<$P1>.
@@ -385,75 +449,117 @@
the name was known at compile time, you could retrieve the namespace
with a key:
+=begin PIR_FRAGMENT
+
$P0 = get_hll_namespace ["Foo"; "Bar"]
+=end PIR_FRAGMENT
+
If the name was not known at compile time, you would retrieve the
namespace with an array instead:
+=begin PIR_FRAGMENT
+
$P1 = split "::", "Foo::Bar"
$P0 = get_hll_namespace $P1
+=end PIR_FRAGMENT
+
=item C<make_namespace>
+=begin PIR_FRAGMENT_INVALID
+
$P1 = make_namespace [key]
$P1 = make_hll_namespace [key]
$P1 = make_root_namespace [key]
+=end PIR_FRAGMENT_INVALID
+
Create and retrieve the namespace denoted by a multidimensional hash key
and store it in C<$P1>. If the namespace already exists, only retrieve
it.
+=begin PIR_FRAGMENT_INVALID
+
$P1 = make_namespace $P2
$P1 = make_hll_namespace $P2
$P1 = make_root_namespace $P2
+=end PIR_FRAGMENT_INVALID
+
Create and retrieve the namespace denoted by the array of names $P2 and
store it in C<$P1>. If the namespace already exists, only retrieve it.
=item C<get_global>
+=begin PIR_FRAGMENT
+
$P1 = get_global $S2
$P1 = get_hll_global $S2
$P1 = get_root_global $S2
+=end PIR_FRAGMENT
+
Retrieve the symbol named $S2 in the current namespace, HLL root
namespace, or true root namespace.
+=begin PIR_FRAGMENT
+
+ .local pmc key
$P1 = get_global [key], $S2
$P1 = get_hll_global [key], $S2
$P1 = get_root_global [key], $S2
+=end PIR_FRAGMENT
+
Retrieve the symbol named $S2 by a multidimensional hash key relative
to the current namespace, HLL root namespace, or true root namespace.
+=begin PIR_FRAGMENT
+
$P1 = get_global $P2, $S3
$P1 = get_hll_global $P2, $S3
$P1 = get_root_global $P2, $S3
+=end PIR_FRAGMENT
+
Retrieve the symbol named $S3 by the array of names $P2 relative to the
current namespace, HLL root namespace, or true root namespace.
=item C<set_global>
+=begin PIR_FRAGMENT
+
set_global $S1, $P2
set_hll_global $S1, $P2
set_root_global $S1, $P2
+=end PIR_FRAGMENT
+
Store $P2 as the symbol named $S1 in the current namespace, HLL root
namespace, or true root namespace.
+=begin PIR_FRAGMENT
+
+ .local pmc key
set_global [key], $S1, $P2
set_hll_global [key], $S1, $P2
set_root_global [key], $S1, $P2
+=end PIR_FRAGMENT
+
Store $P2 as the symbol named $S1 by a multidimensional hash key,
relative to the current namespace, HLL root namespace, or true root
namespace. If the given namespace does not exist it is created.
+=begin PIR_FRAGMENT
+
set_global $P1, $S2, $P3
set_hll_global $P1, $S2, $P3
set_root_global $P1, $S2, $P3
+=end PIR_FRAGMENT
+
Store $P3 as the symbol named $S2 by the array of names $P1, relative to
the current namespace, HLL root namespace, or true root namespace. If
the given namespace does not exist it is created.
@@ -479,6 +585,8 @@
should map roughly to this PIR:
+=begin PIR
+
.HLL "Perl5"
.loadlib "perl5_group"
.namespace [ "Foo" ]
@@ -488,6 +596,8 @@
set_global "$x", $P0
.end
+=end PIR
+
In this case, the C<main> sub would be tied to Perl 5 by the C<.HLL>
directive, so a Perl 5 namespace would be created.
@@ -503,6 +613,8 @@
these cases, Parrot should create the namespace based on the HLL of the PIR
subroutine that calls the store function.
+=begin PIR
+
.HLL "Perl5"
.loadlib "perl5_group"
.sub main :main
@@ -511,7 +623,7 @@
$P0 = "x"
set_global "$a", $P0
# ${"Foo::$a"} = 5;
- $P1 = new PerlString
+ $P1 = new 'PerlString'
$P1 = "Foo::"
$P1 .= $P0
$S0 = $P1
@@ -523,6 +635,8 @@
set_global $P2, $S0, $P3
.end
+=end PIR
+
In this case, C<set_global> should see that it was called from "main",
which is in a Perl 5 namespace, so it will create the "Foo" namespace as
a Perl 5 namespace.
@@ -572,8 +686,10 @@
PIR:
+=begin PIR
+
.sub main :main
- $P0 = get_name "&foo"
+ $P0 = get_global "&foo"
$P1 = get_namespace ["Foo"]
# A smart perl6 compiler would emit this,
@@ -581,14 +697,16 @@
$P1["&bar"] = $P0
# But a naive perl6 compiler would emit this:
- $P1.add_sub("bar", $P0)
+ $P1.'add_sub'("bar", $P0)
.end
.sub foo
- ...
+ #...
.end
+=end PIR
+
=head4 Cross-language Exportation
Perl 5:
@@ -599,6 +717,8 @@
PIR (without error checking):
+=begin PIR
+
.sub main :main
.local pmc tcl
.local pmc ns
@@ -608,13 +728,15 @@
ns[0] = "Some"
ns[1] = "Module"
null $P0
- tcl.load_library(ns, $P0)
- $P0 = tcl.get_namespace(ns)
+ tcl.'load_library'(ns, $P0)
+ $P0 = tcl.'get_namespace'(ns)
$P1 = get_namespace
- $P0.export_to($P1, 'w*')
+ $P0.'export_to'($P1, 'w*')
"write"("this is a tcl command")
.end
+=end PIR
+
=head2 Attachments
None.
Modified: trunk/docs/pdds/pdd22_io.pod
==============================================================================
--- trunk/docs/pdds/pdd22_io.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd22_io.pod Sat May 16 04:08:22 2009 (r38816)
@@ -87,17 +87,25 @@
=item C<new>
+=begin PIR_FRAGMENT
+
$P0 = new [ 'FileHandle' ]
+=end PIR_FRAGMENT
+
Creates a new I/O stream object. [Note that this is usually performed
via the C<open> opcode.]
=item C<open>
+=begin PIR_FRAGMENT
+
$P0 = $P1.'open'()
$P0 = $P1.'open'($S2)
$P0 = $P1.'open'($S2, $S3)
+=end PIR_FRAGMENT
+
Opens a stream on an existing I/O stream object, and returns a status
object. With no arguments, it can be used to reopen a previously opened
I/O stream. $S2 is a file path and $S3 is an optional mode for the
@@ -115,9 +123,13 @@
=item C<close>
+=begin PIR_FRAGMENT
+
$P0 = $P1.'close'()
$P0 = $P1.'close'($P2)
+=end PIR_FRAGMENT
+
Closes an I/O stream, but leaves destruction of the I/O object to the
GC. The C<close> method returns a PMC status object.
@@ -129,6 +141,8 @@
=item C<print>
+=begin PIR_FRAGMENT
+
$P0 = $P1.'print'($I2)
$P0 = $P1.'print'($N2)
$P0 = $P1.'print'($S2)
@@ -138,6 +152,8 @@
$P0 = $P1.'print'($S2, $P3)
$P0 = $P1.'print'($P2, $P3)
+=end PIR_FRAGMENT
+
Writes an integer, float, string, or PMC value to an I/O stream object.
Returns a PMC status object.
@@ -147,9 +163,13 @@
=item C<read>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'read'($I2)
$P0 = $P1.'read'($I2, $P3)
+=end PIR_FRAGMENT
+
Retrieves a specified number of bytes ($I2) from a stream $P1 into a
string $S0. By default it reads in bytes, but the FileHandle object can
be configured to read in code points instead, by setting the character
@@ -168,9 +188,13 @@
=item C<readline>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'readline'()
$P0 = $P1.'readline'($P2)
+=end PIR_FRAGMENT
+
Retrieves a single line from a stream $P1 into a string $S1. Calling
C<readline> flags the stream as operating in line-buffer mode (see the
C<buffer_type> method below). The C<readline> operation respects the
@@ -184,12 +208,16 @@
=item C<readall>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'readall'()
$P0 = $P1.'readall'($P2)
$S0 = $P1.'readall'($S2)
$P0 = $P1.'readall'($S2, $P3)
+=end PIR_FRAGMENT
+
Retrieves the entire contents from a stream $P1 into a string $S0. On a
previously opened stream, C<readall> will read the entire contents of
the file, and return them as a string. It will respect the read mode of
@@ -206,18 +234,26 @@
=item C<record_separator>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'record_separator'()
$P0.'record_separator'($S1)
+=end PIR_FRAGMENT
+
Accessor (get and set) for the I/O stream's record separator attribute.
The default value is a newline (CR, LF, CRLF, etc. depending on the
platform).
=item C<buffer_type>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'buffer_type'()
$P0.'buffer_type'($S1)
+=end PIR_FRAGMENT
+
Accessor (get and set) for the I/O stream's buffer type attribute. The
attribute is set or returned as a string value of 'unbuffered' (bytes sent as
soon as possible), 'line-buffered' (bytes sent when record separator is
@@ -225,9 +261,13 @@
=item C<buffer_size>
+=begin PIR_FRAGMENT
+
$I0 = $P1.'buffer_size'()
$P0.'buffer_size'($I1)
+=end PIR_FRAGMENT
+
Accessor (get and set) for the I/O stream's buffer size attribute. The
size is specified in bytes (positive integer value), though the buffer
may hold a varying number of characters when dealing with an encoding of
@@ -247,24 +287,36 @@
=item C<mode>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'mode'()
+=end PIR_FRAGMENT
+
Accessor (get only) for the I/O stream's read mode. This returns the mode
string used to open the I/O stream.
=item C<encoding>
+=begin PIR_FRAGMENT
+
$S0 = $P1.'encoding'()
$P0.'encoding'($S1)
+=end PIR_FRAGMENT
+
Accessor (get and set) for the I/O stream's encoding attribute. Currently,
the only valid value to set is 'utf8' which turns on UTF-8 reading/writing
mode for the stream. The default behavior is fixed-width 8-bit characters.
=item C<get_fd> [RT #48312]
+=begin PIR_FRAGMENT
+
$I0 = $P1.'get_fd'()
+=end PIR_FRAGMENT
+
For stream objects that are simple wrappers around a Unix filehandle,
C<get_fd> retrieves the Unix integer file descriptor of the object.
This method will simply return -1 on stream objects that aren't Unix
@@ -280,8 +332,12 @@
=item C<get_integer> (vtable)
+=begin PIR_FRAGMENT
+
$I0 = $P1
+=end PIR_FRAGMENT
+
Returns an integer status for the status object, 1 for successful
completion, -1 for an error, and 0 while still running. [Discuss: This
is largely to preserve current expectations of -1 for an error. If we
@@ -289,23 +345,37 @@
=item C<get_bool> (vtable)
- if $P0 goto ...
+=begin PIR_FRAGMENT
+
+ if $P0 goto L1
+ # ...
+ L1:
+
+=end PIR_FRAGMENT
Returns a boolean status for the status object, C<true> for successful
completion or while still running, C<false> for an error.
=item C<return>
+=begin PIR_FRAGMENT
+
$P0 = $P1.'return'()
+=end PIR_FRAGMENT
+
Retrieves the return value of the asynchronous operation from the status
object. Returns a NULL PMC while still running, or if the operation had
no return value.
=item C<error>
+=begin PIR_FRAGMENT
+
$P0 = $P1.'error'()
+=end PIR_FRAGMENT
+
Retrieves the error object from the status object, if the execution of
the asynchronous operation terminated with an error. The error object is
derived from Exception, and can be thrown from the callback. If there
@@ -314,8 +384,12 @@
=item C<throw>
+=begin PIR_FRAGMENT
+
$P0.'throw'()
+=end PIR_FRAGMENT
+
Throw an exception from the status object if it contains an error
object, otherwise do nothing.
@@ -331,22 +405,34 @@
=item C<new>
+=begin PIR_FRAGMENT
+
new $P0, [ 'Iterator' ], $P1
+=end PIR_FRAGMENT
+
Create a new iterator object $P0 from I/O object $P1.
=item C<shift>
+=begin PIR_FRAGMENT
+
shift $S0, $P1
+=end PIR_FRAGMENT
+
Retrieve the next line/block $S0 from the I/O iterator $P1. The amount
of data retrieved in each iteration is determined by the I/O object's
C<buffer_type> setting: unbuffered, line-buffered, or fully-buffered.
=item C<get_bool> (vtable)
+=begin PIR_FRAGMENT
+
unless $P0 goto iter_end
+=end PIR_FRAGMENT
+
Returns a boolean value for the iterator, C<true> if there is more data
to pull from the I/O object, C<false> if the iterator has reached the
end of the data. [NOTE: this means that an iterator always checks for
@@ -376,11 +462,15 @@
=item C<open>
+=begin PIR_FRAGMENT_INVALID
+
$P0 = open $S1
$P0 = open $S1, $S2
$P0 = open $P1
$P0 = open $P1, $S2
+=end PIR_FRAGMENT_INVALID
+
Opens a stream object based on a file path in $S1 and returns it. The
stream object defaults to read/write mode. The optional string argument
$S2 specifies the mode of the stream (read, write, append, read/write,
@@ -396,9 +486,13 @@
=item C<close>
+=begin PIR_FRAGMENT_INVALID
+
close $P0
close $P0, $P1
+=end PIR_FRAGMENT_INVALID
+
Closes a stream object. It takes a single string object argument and
returns a status object.
@@ -433,6 +527,8 @@
=item C<print>
+=begin PIR_FRAGMENT_INVALID
+
print $I0
print $N0
print $S0
@@ -446,6 +542,8 @@
print $P0, $S1, $P2
print $P0, $P1, $P2
+=end PIR_FRAGMENT_INVALID
+
Writes an integer, float, string, or PMC value to a stream. It
writes to standard output by default, but optionally takes a PMC
argument to select another stream to write to.
@@ -456,11 +554,15 @@
=item C<printerr>
+=begin PIR_FRAGMENT
+
printerr $I0
printerr $N0
printerr $S0
printerr $P0
+=end PIR_FRAGMENT
+
Writes an integer, float, string, or PMC value to standard error.
There is no asynchronous variant of C<printerr>. [It's just a shortcut.
@@ -474,10 +576,14 @@
=item C<read>
+=begin PIR_FRAGMENT_INVALID
+
$S0 = read $I1
$S0 = read $P1, $I2
$P0 = read $P1, $I2, $P3
+=end PIR_FRAGMENT_INVALID
+
Retrieves a specified number of bytes, $I2, from a stream, $P2, into a
string, $S0. [Note this is bytes, not codepoints.] By default it reads
from standard input, but it also takes an alternate stream object source
@@ -490,9 +596,13 @@
=item C<readline>
+=begin PIR_FRAGMENT_INVALID
+
$S0 = readline $P1
$P0 = readline $P1, $P2
+=end PIR_FRAGMENT_INVALID
+
Retrieves a single line from a stream into a string. Calling
C<readline> flags the stream as operating in line-buffer mode.
@@ -503,9 +613,13 @@
=item C<peek>
+=begin PIR_FRAGMENT
+
$S0 = peek
$S0 = peek $P1
+=end PIR_FRAGMENT
+
[C<peek>, C<seek>, C<tell>, and C<poll> are all candidates for moving from
opcodes to FileHandle object methods.]
@@ -525,11 +639,15 @@
=item C<seek>
+=begin PIR_FRAGMENT_INVALID
+
seek $P0, $I1, $I2
seek $P0, $I1, $I2, $I3
seek $P0, $I1, $I2, $P3
seek $P0, $I1, $I2, $I3, $P4
+=end PIR_FRAGMENT_INVALID
+
Sets the current file position of a stream object, $P0, to an integer
byte offset, $I1, from an integer starting position, $I2, (0 for the
start of the file, 1 for the current position, and 2 for the end of the
@@ -544,9 +662,13 @@
=item C<tell>
+=begin PIR_FRAGMENT_INVALID
+
$I0 = tell $P1
($I0, $I1) = tell $P2
+=end PIR_FRAGMENT_INVALID
+
Retrieves the current file position of a stream object. It also has a
64-bit variant that returns the byte offset as two integers (one for the
first 32 bits of the 64-bit offset, and one for the second 32 bits).
@@ -557,8 +679,12 @@
=item C<poll>
+=begin PIR_FRAGMENT_INVALID
+
$I0 = poll $P1, $I2, $I3, $I4
+=end PIR_FRAGMENT_INVALID
+
Polls a stream or socket object for particular types of events (an
integer flag) at a frequency set by seconds and microseconds (the final
two integer arguments). [At least, that's what the documentation in
Modified: trunk/docs/pdds/pdd23_exceptions.pod
==============================================================================
--- trunk/docs/pdds/pdd23_exceptions.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd23_exceptions.pod Sat May 16 04:08:22 2009 (r38816)
@@ -380,6 +380,8 @@
(though it would still be implemented as an exception handler
internally). Something like:
+=begin PIR_FRAGMENT_TODO
+
.local pmc error_code
.capture_start error_code
$P1 = find_lex 'foo'
@@ -387,6 +389,8 @@
# error_code contains what would have been the "error" return value
+=end PIR_FRAGMENT_TODO
+
This could eliminate the need for "defanging" because it would be almost
as easy to use as error codes. It could be implemented once for all
exceptional opcodes, instead of needing to be defined for each one. And,
@@ -399,7 +403,9 @@
The exception message is stored in the 'message' attribute:
- ...
+=begin PIR_FRAGMENT
+
+ # ...
handler:
.local pmc exception
.local string message
@@ -407,6 +413,8 @@
message = exception['message']
say message
+=end PIR_FRAGMENT
+
=head4 Resuming after Exceptions
@@ -423,6 +431,8 @@
You resume from an exception by invoking the return continuation stored
in the 'resume' attribute of the exception.
+=begin PIR_FRAGMENT
+
push_eh handler
$P0 = new 'Exception' # create new exception object
throw $P0 # throw it
@@ -435,6 +445,8 @@
continuation = exception['resume']
continuation()
+=end PIR_FRAGMENT
+
=head2 Attachments
None.
Modified: trunk/docs/pdds/pdd24_events.pod
==============================================================================
--- trunk/docs/pdds/pdd24_events.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd24_events.pod Sat May 16 04:08:22 2009 (r38816)
@@ -243,18 +243,27 @@
=item new
+=begin PIR_FRAGMENT
+
$P1 = new 'Event'
$P1 = new 'EventHandler'
$P1 = new 'EventHandler', $P2
+=end PIR_FRAGMENT
+
+
Creates a new event or event handler.
=item schedule
+=begin PIR_FRAGMENT
+
$P0 = new 'Event'
# set attributes
schedule $P0
+=end PIR_FRAGMENT
+
Register an event with the concurrency scheduler. If the concurrency scheduler
for this interpreter (thread/clustered instance) is linked to another
"primary" concurrency scheduler, this will pass along the event to the
@@ -265,10 +274,14 @@
=item addhandler
+=begin PIR_FRAGMENT
+
$P0 = new 'EventHandler'
# set attributes
addhandler $P0
+=end PIR_FRAGMENT
+
Register an event handler with the concurrency scheduler. If the concurrency
scheduler for this interpreter (thread/clustered instance) is linked to
another "primary" concurrency scheduler, this will pass along the event
Modified: trunk/docs/pdds/pdd25_concurrency.pod
==============================================================================
--- trunk/docs/pdds/pdd25_concurrency.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd25_concurrency.pod Sat May 16 04:08:22 2009 (r38816)
@@ -274,13 +274,21 @@
=item add_handler
- $P1.add_handler($P2)
+=begin PIR_FRAGMENT
+
+ $P1.'add_handler'($P2)
+
+=end PIR_FRAGMENT
Add an event or exception handler to the scheduler's list of handlers.
=item find_handler
- $P1 = $P2.find_handler($P3)
+=begin PIR_FRAGMENT
+
+ $P1 = $P2.'find_handler'($P3)
+
+=end PIR_FRAGMENT
Search for an event or exception handler $P1, in scheduler $P2, for the task
$P3. Returns a null PMC if an appropriate handler is not found.
@@ -365,34 +373,50 @@
=item new
+=begin PIR_FRAGMENT
+
$P1 = new 'Task'
+=end PIR_FRAGMENT
+
Creates a new task. (The Scheduler PMC is never instantiated directly, it is
only used by Parrot internals.)
=item schedule
+=begin PIR_FRAGMENT
+
$P0 = new 'Task'
# set attributes
schedule $P0
+=end PIR_FRAGMENT
+
Register a task with the concurrency scheduler. Details about the task are
stored within the task PMC.
=item join
+=begin PIR_FRAGMENT_INVALID
+
$P0 = new 'Task'
# ... schedule the task, etc.
join $P0
+=end PIR_FRAGMENT_INVALID
+
Wait for a particular task to complete.
=item kill
+=begin PIR_FRAGMENT_INVALID
+
$P0 = new 'Task'
# ... schedule the task, etc.
kill $P0
+=end PIR_FRAGMENT_INVALID
+
Kill a task without waiting for it to complete.
Modified: trunk/docs/pdds/pdd27_multiple_dispatch.pod
==============================================================================
--- trunk/docs/pdds/pdd27_multiple_dispatch.pod Sat May 16 03:50:07 2009 (r38815)
+++ trunk/docs/pdds/pdd27_multiple_dispatch.pod Sat May 16 04:08:22 2009 (r38816)
@@ -157,14 +157,26 @@
=item :multi
+=begin PIR
+
.sub mymultisub :multi(Integer, Integer)
+ # ...
+ .end
+
+=end PIR
The C<:multi> attribute marks a subroutine or method as participating in
multiple dispatch.
=item :invocant
+=begin PIR_INVALID
+
+ .sub mymultisub
.param pmc first :invocant
+ .end
+
+=end PIR_INVALID
Not all elements of a multi-sub's signature are relevant for the purposes of
multiple dispatch. The subroutine parameters that participate in dispatch are
More information about the parrot-commits
mailing list