Permalink
Newer
Older
100644 403 lines (255 sloc) 11.7 KB
1
# Copyright (C) 2001-2010, Parrot Foundation.
3
=head1 PDD 3: Calling Conventions
7
Parrot's inter-routine calling conventions.
12
19
This document describes how to pass arguments from registers to subroutines,
20
and how subroutines can extract their parameters into registers for use.
22
Since Parrot's calling conventions are continuation-based, there is arguably
23
very little difference between a call and a return. Because of this, the
24
conversion rules are the same regardless of whether code is invoking a
25
subroutine or a return continuation.
26
27
=head3 Common Features of Argument/Return Opcodes
28
29
There are four opcodes involved in parameter and return value propagation:
30
31
=over 4
32
33
=item *
35
C<set_args>, for passing arguments;
37
=item *
39
C<set_returns>, for returning values;
41
=item *
43
C<get_params>, for accepting parameters; and
45
=item *
47
C<get_results>, for accepting return values.
49
=back
51
FAQ: Given Parrot's internal use of continuation-passing style ["CPS"], it
52
would be possible to use one pair of opcodes for both call and return, since
53
under CPS returns I<are> calls. And perhaps someday we will have only two
54
opcodes. But for now, certain efficiency hacks are easier with four opcodes.
56
The common syntax of these opcodes is:
58
<set_opcode> "flags0, flags1, ..., flagsN", VAL0, VAL1, ... VALN
59
<get_opcode> "flags0, flags1, ..., flagsN", REG0, REG1, ... REGN
60
<get_opcode> "..., 0x200, flags0, ...", ..., "name", REG0, ...
62
The flags string is a literal quoted string denoting a list of zero or more
63
comma-separated integers. Integers may be specified either in decimal, or if
64
prefixed with "0b"/"0x", in binary/hexadecimal. There must be exactly one
65
integer for each value or register given.
66
67
For documentation purposes we'll number the bits 0 (low) through 30 (high).
68
Bit 31 (and higher, where available) will not be used.
69
70
Some values and registers do not correspond directly to values passed or
71
received. (See the descriptions of the OPT_FLAG and NAMED bits, below.)
72
73
=head4 Flag Words; Common Flag Word Bits
75
Each integer in the flag string controls the processing of the corresponding
76
value or register.
78
These bits of each flag word have common meanings for all argument/
79
return-value opcodes:
81
0-3 TYPE
82
0b0000 = I
83
0b0001 = S
84
0b0010 = P
85
0b0011 = N
87
Don't set these bits yourself; the assembler will do it.
89
=head3 Passing Arguments, Returning Values
91
Just before calling a subroutine with C<invokecc> or calling a method with
92
C<call_methodcc>, use the C<set_args> opcode to tell Parrot where the
93
subroutine's or method's arguments will come from and how they should be
94
expanded by the target.
96
Similarly, just before returning from such a subroutine or method, use
97
the C<set_returns> opcode to tell Parrot where the return values will
98
come from and how to expand them for the caller's use.
100
=head4 Flag Word Bits For 'Setting'
101
102
These bits of each flag word have these meanings specific to C<set_args> and
103
C<set_returns>:
104
108
109
The value is a literal constant, not a register. (Don't set this bit
110
yourself; the assembler will do it.)
111
112
=item 5 C<FLAT> (P only)
113
114
If this bit is set on a PMC value, then the PMC must be an aggregate. The
115
contents of the aggregate, rather than the aggregate itself, will be passed.
117
If the C<NAMED> bit is also set, the aggregate will be used as a hash; its
118
contents, as key/value pairs, will be passed as named arguments. The PMC
119
must implement the full hash interface. {{ TT #1288: Limit the required
122
If the C<NAMED> bit is not set, the aggregate will be used as an array; its
123
contents will be passed as positional arguments.
124
125
The meaning of this bit is undefined when applied to integer, number, and
126
string values.
127
134
=item 9 C<NAMED> (C<FLAT> or string constant only)
135
136
When the FLAT bit is also set, behavior is as described above in the "FLAT"
137
section. Otherwise, this bit may only be set on a unique string constant
138
specifying the name of the next argument (or returned value).
139
140
=back
142
=head3 Accepting Parameters, Accepting Return Values
144
As the I<first opcode> in a subroutine that will be called with
145
C<invokecc> or a method that will be called with C<call_methodcc>, use
146
the C<get_params> opcode to tell Parrot where the subroutine's or
147
method's arguments should be stored and how they should be expanded.
149
Similarly, just I<before> (yes, I<before>) calling such a subroutine or
150
method, use the C<get_results> opcode to tell Parrot where the return
151
values should be stored and how to expand them for your use.
153
NOTE: It should be obvious, but in case it's not: You must name only registers
154
as targets of these opcodes, not constants. (You can't store anything into a
155
constant. That would make it a variable.)
157
=head4 Flag Word Bits For 'Getting'
159
These bits of each flag word have these meanings specific to C<get_params> and
160
C<get_results>:
167
168
If this bit is set on a P register, then it will be populated with an
169
aggregate that will contain all of the remaining values that have not already
170
been stored in other registers.
171
172
All such values will be converted to PMCs according to the detailed rules
173
below, and those PMCs will be stored into the new aggregate.
174
175
If the C<NAMED> bit is also set, the aggregate will be the HLL-specific hash
176
type and the contents will be all unassigned _named_ arguments.
178
If the C<NAMED> bit is not set, the aggregate will be the HLL-specific array
179
type and the contents will be all unassigned positional arguments.
184
185
If this bit is set on a register for which no value has been passed, no
186
exception will be raised; rather, the register will be set to a default value:
187
a Null PMC for P, an empty string for S, or zero for N or I.
188
190
191
An I register with this bit set is set to one if the immediately preceding
192
B<OPTIONAL> register received a value; otherwise, it is set to zero. If the
193
preceding register was not marked B<OPTIONAL>, the behavior is undefined; but
194
we promise you won't like it.
199
200
If this bit is set on a P register that receives a value, Parrot will ensure
201
that the final value in the P register is read-only (i.e. will not permit
202
modification). If the received value was a mutable PMC, then Parrot will
203
create and set the register to a {not yet invented} read-only PMC wrapper
204
around the original PMC.
206
Future Notes: Parrot's algorithm for deciding what is writable may be
207
simplistic. In initial implementations, it may assume that any PMC not of a
208
known read-only-wrapper type is mutable. Later it may allow the HLL to
209
provide the test. But we must beware overdesigning this; any HLL with a truly
210
complex notion of read-only probably needs to do this kind of wrapping itself.
212
=item 8 (unused for S and N)
213
214
=item 9 C<NAMED> (C<SLURPY> or string constant only)
215
216
When the SLURPY bit is also set, behavior is as described above in the
217
"SLURPY" section. Otherwise, this bit may only be set on a unique string
218
constant specifying the name of the next parameter (or returned value).
222
=head4 Overflow and underflow
224
If too many or too few values are provided for the given target registers,
225
Parrot by default will throw an exception for C<get_params>, but not for
226
C<get_results>. This error behavior can be controlled via the C<errorson> and
227
C<errorsoff> opcodes using C<PARROT_ERRORS_PARAM_COUNT_FLAG> for C<get_params>
228
and C<PARROT_ERRORS_RESULT_COUNT_FLAG> for C<get_results>. (It is not
229
possible to control underflow behavior separately from overflow.)
231
Note that if the final target is a P register with FLAT set, then overflow can
232
never occur. Similarly, if all target registers are marked B<OPTIONAL>, then
233
underflow is impossible.
235
Note also that when these errors are off, any excess destination registers in
236
the case of underflow are left untouched, rather than being reset to zero or
237
null. Excess registers explicitly marked B<OPTIONAL> are always reset,
238
regardless of the error flag settings.
240
=head4 Ordering of named values (outgoing)
242
Named values (arguments, or values to return) must be listed textually after
243
all the positional values. C<FLAT> and non-C<FLAT> values may be mixed in any
244
order.
246
=head4 Ordering of named targets (incoming)
247
248
Named targets (parameters, or returned values) must appear I<after> all the
249
positional targets. A C<SLURPY> positional target, if present, must be the
250
last positional target; a C<SLURPY> named target, if present, must be the last
251
named target.
252
253
So the acceptable ordering of targets is:
254
255
=over 4
256
257
=item *
258
259
positional non-SLURPY (any number)
263
positional SLURPY array (optional)
275
=head4 Mixing named and positional values
277
Positional targets can only be filled with positional values.
279
Named targets can be filled with either positional or named values.
280
However, if a named target was already filled by a positional value, and
281
then a named value is also given, this is an overflow error.
283
=head4 Type Conversions
284
285
Unlike the C<set_*> opcodes, the C<get_*> opcodes must perform conversion from
286
one register type to another. Here are the conversion rules:
287
288
=over 4
289
290
=item *
292
When the target is an I, N, or S register, storage will behave like an
293
C<assign> (standard conversion).
295
=item *
297
When the target and source are both P registers, storage will behave like a
298
C<set> (pass by reference).
300
=item *
302
When the target is a P register and the source is an integer, the P will be
303
set to a new Integer[1] which has been C<assign>ed the given integer.
305
=item *
307
When the target is a P register and the source is a number, the P will be set
308
to a new Float[1] which has been C<assign>ed the given number.
310
=item *
312
When the target is a P register and the source is a string, the P will be set
313
to a new String[1] which has been C<assign>ed the given string.
314
315
=back
316
317
[1] or some other type specified by the current HLL type map, which may
318
substitute an alternative type for each default low-level Parrot type (array,
319
hash, string, number, etc.).
327
Required features are missing:
329
=over 4
331
=item *
333
Specific exceptions to throw for specific errors.
334
335
=back
336
337
=head2 PIR Syntax Examples
341
=begin PIR_FRAGMENT_INVALID
342
343
.local pmc foo, i, ar, y, p, value, kw, a, b, c, z
344
# ...
345
foo(1, i) # 2 positional arguments
346
foo(x, ar :flat, y) # flattening array
347
foo(p, 'key' => value) # named argument
348
foo(p, value :named('key')) # the same
Leopold Toetsch
May 11, 2006
349
foo(kw :named :flat) # a flattening hash
351
# all together now: three positional (one flat) with two named (one flat)
352
foo(a, b, c :flat, 'x' => 3, 'y' => 4, z :flat :named('z'))
353
354
=end PIR_FRAGMENT_INVALID
355
358
=begin PIR
359
360
.sub foo
361
.param int i # positional parameter
362
.param pmc argv :slurpy # slurpy array
363
.param pmc value :named('key') # named parameter
364
.param int x :optional # optional parameter
365
.param int has_x :opt_flag # flag 0/1 x was passed
366
.param pmc kw :slurpy :named # slurpy hash
367
# ...
368
.end
369
370
=end PIR
374
=begin PIR_INVALID
375
376
.sub foo
377
.local pmc i, ar, value
378
.return (i, ar: flat, value :named('key') )
379
.end
380
381
=end PIR_INVALID
385
=begin PIR_FRAGMENT
386
387
.local pmc x, foo, i, j, ar, value
388
x = foo() # single result
389
(i, j :optional, ar :slurpy, value :named('key') ) = foo()
391
=end PIR_FRAGMENT
392
Michael Scott
Feb 28, 2004
394
Michael Scott
Feb 28, 2004
396
399
__END__
400
Local Variables:
401
fill-column:78
402
End: