Skip to content
Newer
Older
100644 399 lines (255 sloc) 11.7 KB
fba2bc1 @coke PDD cleanup (TT #1536); Remove maintainer, changes sections.
coke authored Apr 14, 2010
1 # Copyright (C) 2001-2010, Parrot Foundation.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
2
740e774 @allisonrandal [cage] Cleaning up the PDD titles for better display and
allisonrandal authored Mar 9, 2009
3 =head1 PDD 3: Calling Conventions
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
4
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
5 =head2 Abstract
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
6
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
7 Parrot's inter-routine calling conventions.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
8
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
9 =head2 Synopsis
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
10
11 Not applicable.
12
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
13 =head2 Description
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
14
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
15 This document describes how to pass arguments from registers to subroutines,
16 and how subroutines can extract their parameters into registers for use.
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored May 2, 2003
17
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
18 Since Parrot's calling conventions are continuation-based, there is arguably
19 very little difference between a call and a return. Because of this, the
20 conversion rules are the same regardless of whether code is invoking a
21 subroutine or a return continuation.
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
22
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
23 =head3 Common Features of Argument/Return Opcodes
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
24
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
25 There are four opcodes involved in parameter and return value propagation:
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
26
27 =over 4
28
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
29 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
30
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
31 C<set_args>, for passing arguments;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
32
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
33 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
34
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
35 C<set_returns>, for returning values;
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
36
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
37 =item *
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
38
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
39 C<get_params>, for accepting parameters; and
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
40
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
41 =item *
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored May 2, 2003
42
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
43 C<get_results>, for accepting return values.
b27d0f7 Fixed calling convention docs. Again
Dan Sugalski authored May 2, 2003
44
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
45 =back
8f37cf5 tweak calling conventions
Dan Sugalski authored Feb 6, 2003
46
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
47 FAQ: Given Parrot's internal use of continuation-passing style ["CPS"], it
48 would be possible to use one pair of opcodes for both call and return, since
49 under CPS returns I<are> calls. And perhaps someday we will have only two
2be4a28 * docs/pdds/draft/pdd06_pasm.pod:
Bob Rogers authored Apr 7, 2008
50 opcodes. But for now, certain efficiency hacks are easier with four opcodes.
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
51
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
52 The common syntax of these opcodes is:
8f37cf5 tweak calling conventions
Dan Sugalski authored Feb 6, 2003
53
3b2acaf @paultcochrane [pdd] Removed deprecated opcode syntax as recommended by Allison Rand…
paultcochrane authored Sep 18, 2007
54 <set_opcode> "flags0, flags1, ..., flagsN", VAL0, VAL1, ... VALN
55 <get_opcode> "flags0, flags1, ..., flagsN", REG0, REG1, ... REGN
56 <get_opcode> "..., 0x200, flags0, ...", ..., "name", REG0, ...
8155c8a MMD 16 - builtin infix multis
Leopold Toetsch authored Apr 4, 2005
57
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
58 The flags string is a literal quoted string denoting a list of zero or more
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
59 comma-separated integers. Integers may be specified either in decimal, or if
60 prefixed with "0b"/"0x", in binary/hexadecimal. There must be exactly one
61 integer for each value or register given.
62
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
63 For documentation purposes we'll number the bits 0 (low) through 30 (high).
64 Bit 31 (and higher, where available) will not be used.
65
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
66 Some values and registers do not correspond directly to values passed or
67 received. (See the descriptions of the OPT_FLAG and NAMED bits, below.)
68
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
69 =head4 Flag Words; Common Flag Word Bits
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
70
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
71 Each integer in the flag string controls the processing of the corresponding
72 value or register.
7dccda2 Changes to the calling conventions
Dan Sugalski authored Nov 17, 2003
73
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
74 These bits of each flag word have common meanings for all argument/
75 return-value opcodes:
7dccda2 Changes to the calling conventions
Dan Sugalski authored Nov 17, 2003
76
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
77 0-3 TYPE
78 0b0000 = I
79 0b0001 = S
80 0b0010 = P
81 0b0011 = N
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
82
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
83 Don't set these bits yourself; the assembler will do it.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
84
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
85 =head3 Passing Arguments, Returning Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
86
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
87 Just before calling a subroutine with C<invokecc> or calling a method with
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored Sep 11, 2007
88 C<call_methodcc>, use the C<set_args> opcode to tell Parrot where the
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
89 subroutine's or method's arguments will come from and how they should be
90 expanded by the target.
7ed080d Fixed the PMC parameter passing docs
Dan Sugalski authored Aug 8, 2002
91
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
92 Similarly, just before returning from such a subroutine or method, use
93 the C<set_returns> opcode to tell Parrot where the return values will
94 come from and how to expand them for the caller's use.
7ed080d Fixed the PMC parameter passing docs
Dan Sugalski authored Aug 8, 2002
95
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
96 =head4 Flag Word Bits For 'Setting'
37a10ea Some precursor changes
Dan Sugalski authored Sep 18, 2002
97
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
98 These bits of each flag word have these meanings specific to C<set_args> and
99 C<set_returns>:
37a10ea Some precursor changes
Dan Sugalski authored Sep 18, 2002
100
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
101 =over 4
102
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
103 =item 4 C<CONSTANT>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
104
105 The value is a literal constant, not a register. (Don't set this bit
106 yourself; the assembler will do it.)
107
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
108 =item 5 C<FLAT> (P only)
109
110 If this bit is set on a PMC value, then the PMC must be an aggregate. The
111 contents of the aggregate, rather than the aggregate itself, will be passed.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
112
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
113 If the C<NAMED> bit is also set, the aggregate will be used as a hash; its
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
114 contents, as key/value pairs, will be passed as named arguments. The PMC
18f3b94 @Benabik Auto-replace TT# with GH# as per GH #707
Benabik authored Jan 26, 2012
115 must implement the full hash interface. {{ GH #252: Limit the required
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
116 interface. }}
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
117
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
118 If the C<NAMED> bit is not set, the aggregate will be used as an array; its
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
119 contents will be passed as positional arguments.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
120
121 The meaning of this bit is undefined when applied to integer, number, and
122 string values.
123
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
124 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
125
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
126 =item 7 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
127
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
128 =item 8 (unused)
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
129
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
130 =item 9 C<NAMED> (C<FLAT> or string constant only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
131
132 When the FLAT bit is also set, behavior is as described above in the "FLAT"
133 section. Otherwise, this bit may only be set on a unique string constant
134 specifying the name of the next argument (or returned value).
135
136 =back
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
137
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
138 =head3 Accepting Parameters, Accepting Return Values
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
139
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
140 As the I<first opcode> in a subroutine that will be called with
141 C<invokecc> or a method that will be called with C<call_methodcc>, use
142 the C<get_params> opcode to tell Parrot where the subroutine's or
143 method's arguments should be stored and how they should be expanded.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
144
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
145 Similarly, just I<before> (yes, I<before>) calling such a subroutine or
146 method, use the C<get_results> opcode to tell Parrot where the return
147 values should be stored and how to expand them for your use.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
148
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
149 NOTE: It should be obvious, but in case it's not: You must name only registers
150 as targets of these opcodes, not constants. (You can't store anything into a
151 constant. That would make it a variable.)
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
152
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
153 =head4 Flag Word Bits For 'Getting'
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
154
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
155 These bits of each flag word have these meanings specific to C<get_params> and
156 C<get_results>:
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
157
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
158 =over 4
159
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
160 =item 4 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
161
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
162 =item 5 C<SLURPY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
163
164 If this bit is set on a P register, then it will be populated with an
165 aggregate that will contain all of the remaining values that have not already
166 been stored in other registers.
167
168 All such values will be converted to PMCs according to the detailed rules
169 below, and those PMCs will be stored into the new aggregate.
170
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
171 If the C<NAMED> bit is also set, the aggregate will be the HLL-specific hash
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
172 type and the contents will be all unassigned _named_ arguments.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
173
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
174 If the C<NAMED> bit is not set, the aggregate will be the HLL-specific array
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
175 type and the contents will be all unassigned positional arguments.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
176
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
177 =item 6 (unused)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
178
f40e752 @ambs Some more POD issues for printer-friendly LaTeX version
ambs authored Nov 3, 2006
179 =item 7 C<OPTIONAL>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
180
181 If this bit is set on a register for which no value has been passed, no
182 exception will be raised; rather, the register will be set to a default value:
183 a Null PMC for P, an empty string for S, or zero for N or I.
184
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
185 =item 8 C<OPT_FLAG> (I only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
186
187 An I register with this bit set is set to one if the immediately preceding
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
188 B<OPTIONAL> register received a value; otherwise, it is set to zero. If the
189 preceding register was not marked B<OPTIONAL>, the behavior is undefined; but
190 we promise you won't like it.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
191
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
192 =item 8 C<READONLY> (P only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
193
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
194 I<XXX - PROPOSED ONLY - XXX>
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
195
196 If this bit is set on a P register that receives a value, Parrot will ensure
197 that the final value in the P register is read-only (i.e. will not permit
198 modification). If the received value was a mutable PMC, then Parrot will
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
199 create and set the register to a {not yet invented} read-only PMC wrapper
200 around the original PMC.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
201
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
202 Future Notes: Parrot's algorithm for deciding what is writable may be
203 simplistic. In initial implementations, it may assume that any PMC not of a
204 known read-only-wrapper type is mutable. Later it may allow the HLL to
205 provide the test. But we must beware overdesigning this; any HLL with a truly
206 complex notion of read-only probably needs to do this kind of wrapping itself.
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
207
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
208 =item 8 (unused for S and N)
209
210 =item 9 C<NAMED> (C<SLURPY> or string constant only)
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
211
212 When the SLURPY bit is also set, behavior is as described above in the
213 "SLURPY" section. Otherwise, this bit may only be set on a unique string
589e643 @allisonrandal [cage] Some usage cleanup on "arguments" versus "parameters".
allisonrandal authored Oct 21, 2009
214 constant specifying the name of the next parameter (or returned value).
82bee68 @ambs Changed pre-formatted text to standard POD. Now we can LaTeX it
ambs authored Nov 2, 2006
215
216 =back
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
217
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
218 =head4 Overflow and underflow
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
219
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
220 If too many or too few values are provided for the given target registers,
221 Parrot by default will throw an exception for C<get_params>, but not for
222 C<get_results>. This error behavior can be controlled via the C<errorson> and
223 C<errorsoff> opcodes using C<PARROT_ERRORS_PARAM_COUNT_FLAG> for C<get_params>
224 and C<PARROT_ERRORS_RESULT_COUNT_FLAG> for C<get_results>. (It is not
225 possible to control underflow behavior separately from overflow.)
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
226
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
227 Note that if the final target is a P register with FLAT set, then overflow can
228 never occur. Similarly, if all target registers are marked B<OPTIONAL>, then
229 underflow is impossible.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
230
ca0d5e6 + Expand description of current overflow/underflow behavior, explain
Bob Rogers authored Jan 6, 2008
231 Note also that when these errors are off, any excess destination registers in
232 the case of underflow are left untouched, rather than being reset to zero or
233 null. Excess registers explicitly marked B<OPTIONAL> are always reset,
234 regardless of the error flag settings.
a40f31b Added docs on Parrot's calling conventions.
Dan Sugalski authored Apr 27, 2002
235
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
236 =head4 Ordering of named values (outgoing)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
237
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
238 Named values (arguments, or values to return) must be listed textually after
239 all the positional values. C<FLAT> and non-C<FLAT> values may be mixed in any
240 order.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
241
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
242 =head4 Ordering of named targets (incoming)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
243
244 Named targets (parameters, or returned values) must appear I<after> all the
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
245 positional targets. A C<SLURPY> positional target, if present, must be the
246 last positional target; a C<SLURPY> named target, if present, must be the last
247 named target.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
248
249 So the acceptable ordering of targets is:
250
251 =over 4
252
253 =item *
254
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
255 positional non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
256
257 =item *
258
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
259 positional SLURPY array (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
260
261 =item *
262
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
263 NAMED non-SLURPY (any number)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
264
265 =item *
266
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
267 NAMED SLURPY hash (optional)
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
268
269 =back
270
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
271 =head4 Mixing named and positional values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
272
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
273 Positional targets can only be filled with positional values.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
274
85e077d @paultcochrane [pdds] Minor formatting and textual corrections.
paultcochrane authored Sep 11, 2007
275 Named targets can be filled with either positional or named values.
276 However, if a named target was already filled by a positional value, and
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
277 then a named value is also given, this is an overflow error.
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
278
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
279 =head4 Type Conversions
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
280
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
281 Unlike the C<set_*> opcodes, the C<get_*> opcodes must perform conversion from
282 one register type to another. Here are the conversion rules:
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
283
284 =over 4
285
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
286 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
287
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
288 When the target is an I, N, or S register, storage will behave like an
289 C<assign> (standard conversion).
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
290
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
291 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
292
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
293 When the target and source are both P registers, storage will behave like a
294 C<set> (pass by reference).
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
295
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
296 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
297
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
298 When the target is a P register and the source is an integer, the P will be
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored Aug 30, 2007
299 set to a new Integer[1] which has been C<assign>ed the given integer.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
300
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
301 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
302
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
303 When the target is a P register and the source is a number, the P will be set
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored Aug 30, 2007
304 to a new Float[1] which has been C<assign>ed the given number.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
305
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
306 =item *
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
307
8e58c2e @jhoblitt reformat all Pods under docs/pdds
jhoblitt authored Oct 5, 2005
308 When the target is a P register and the source is a string, the P will be set
757c937 @chromatic [OO] Changed more PMC creation from constant syntax to string style.
chromatic authored Aug 30, 2007
309 to a new String[1] which has been C<assign>ed the given string.
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
310
311 =back
312
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
313 [1] or some other type specified by the current HLL type map, which may
314 substitute an alternative type for each default low-level Parrot type (array,
315 hash, string, number, etc.).
5b3d0e6 update pdd03 to better reflect current state
Leopold Toetsch authored Dec 27, 2005
316
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
317 =head2 Implementation
7d2f0b5 @jkeenan Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
jkeenan authored Apr 3, 2008
318
319 Not applicable.
320
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
321 =head2 Bugs
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
322
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
323 Required features are missing:
898b4d2 Final release version of pdd03
Dan Sugalski authored Nov 16, 2004
324
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
325 =over 4
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
326
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
327 =item *
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
328
6d3f9cf @chipdude It's all new. All of it.
chipdude authored Jun 13, 2005
329 Specific exceptions to throw for specific errors.
330
331 =back
332
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
333 =head2 PIR Syntax Examples
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
334
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
335 =head3 Function Calls
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
336
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
337 =begin PIR_FRAGMENT_INVALID
338
339 .local pmc foo, i, ar, y, p, value, kw, a, b, c, z
340 # ...
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
341 foo(1, i) # 2 positional arguments
342 foo(x, ar :flat, y) # flattening array
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored Oct 13, 2006
343 foo(p, 'key' => value) # named argument
344 foo(p, value :named('key')) # the same
33fc8c5 pdd03 typo
Leopold Toetsch authored May 11, 2006
345 foo(kw :named :flat) # a flattening hash
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
346
1aa4e60 @chipdude Remove the :maybe_flat "feature", which was intended to help Perl 6, but
chipdude authored Nov 10, 2006
347 # all together now: three positional (one flat) with two named (one flat)
348 foo(a, b, c :flat, 'x' => 3, 'y' => 4, z :flat :named('z'))
349
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
350 =end PIR_FRAGMENT_INVALID
351
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
352 =head3 Parameters
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
353
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
354 =begin PIR
355
356 .sub foo
357 .param int i # positional parameter
358 .param pmc argv :slurpy # slurpy array
359 .param pmc value :named('key') # named parameter
360 .param int x :optional # optional parameter
361 .param int has_x :opt_flag # flag 0/1 x was passed
362 .param pmc kw :slurpy :named # slurpy hash
363 # ...
364 .end
365
366 =end PIR
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
367
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
368 =head3 Return Values
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
369
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
370 =begin PIR_INVALID
371
372 .sub foo
373 .local pmc i, ar, value
374 .return (i, ar: flat, value :named('key') )
375 .end
376
377 =end PIR_INVALID
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
378
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
379 =head3 Call Results
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
380
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
381 =begin PIR_FRAGMENT
382
383 .local pmc x, foo, i, j, ar, value
c410b60 @chipdude * Add two more TYPE, allowing for the unknown future.
chipdude authored Feb 27, 2006
384 x = foo() # single result
d5305a0 @particle [PDD03[: clarify examples for :named syntax
particle authored Oct 13, 2006
385 (i, j :optional, ar :slurpy, value :named('key') ) = foo()
6ef5471 Added null ops to core.ops
Dan Sugalski authored Jun 21, 2003
386
6e05a06 @coke [docs] Mark & test more pasm/pir.
coke authored May 16, 2009
387 =end PIR_FRAGMENT
388
49bf7e6 @allisonrandal [doc] Abandoning daft Perl 5-style documentation headings.
allisonrandal authored Feb 8, 2009
389 =head2 References
ef9e57c tidy up pdds
Michael Scott authored Feb 28, 2004
390
fba2bc1 @coke PDD cleanup (TT #1536); Remove maintainer, changes sections.
coke authored Apr 14, 2010
391 F<pdd23_exceptions.pod>
ef9e57c tidy up pdds
Michael Scott authored Feb 28, 2004
392
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
393 =cut
f140bda @chipdude Formatting: standardize word wrap at column 78.
chipdude authored Nov 30, 2005
394
0abc6ea @chipdude Bring pdd03 out of clip purgatory.
chipdude authored Nov 30, 2005
395 __END__
396 Local Variables:
397 fill-column:78
398 End:
Something went wrong with that request. Please try again.