Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 237 lines (141 sloc) 6.442 kB
8ee1ad7 @allisonrandal [cage] Updating copyright in whole repository to Parrot Foundation.
allisonrandal authored
1 # Copyright (C) 2001-2004, Parrot Foundation.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
2
9d8cce4 a bit more tidying up
Michael Scott authored
3 =head1 NAME
4
5 docs/mmd.pod - Multimethod dispatch for binary opcode functions
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
6
a61c1bf @audreyt * mark mmd.pod as inaccurate and needs rewriting.
audreyt authored
7 =head1 CAVEATS
8
9 XXX - Part or all of this document is outdated. Especially the "the MMD system
b0e0c65 @jkeenan Applying documentation fixes found in patch submitted by ronaldws in …
jkeenan authored
10 doesn't handle inheritance" bit. Please refer to PDD27 at this moment while we
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
11 rewrite or merge this document. We apologize for the inconvenience.
a61c1bf @audreyt * mark mmd.pod as inaccurate and needs rewriting.
audreyt authored
12
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
13 =head1 SYNOPSIS
14
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
15 This system is set up to handle type-based dispatching for binary (i.e.
16 two-arg) functions. This includes, though isn't necessarily limited to, binary
17 operators such as addition or subtraction.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
18
19 =head1 DESCRIPTION
20
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
21 The MMD system is straightforward, and currently must be explicitly invoked,
22 for example by a vtable function. (We may reserve the right to use MMD in all
ea0630c @jhoblitt reformat all Pod files under docs with podtidy (modified to also remo…
jhoblitt authored
23 circumstances, but currently do not)
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
24
25 =head2 API
26
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
27 For the purposes of the API, each MMD-able function is assigned a unique number
28 which is used to find the correct function table. This is the C<func_num>
29 parameter in the following functions. While Parrot isn't restricted to a
30 predefined set of functions, it I<does> set things up so that all the binary
1772034 @jhoblitt reformat all Pod files under docs with podtidy except for docs/pdds
jhoblitt authored
31 vtable functions have a MMD table preinstalled for them, with default behavior.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
32
33 =over 4
34
35 =item mmd_add_by_class(interp, func_num, left_class, right_class, funcptr)
36
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
37 Adds a new MMD function C<funcptr> to the C<func_num> function table that will
38 be invoked when the left parameter is of class C<left_class> and the right
39 parameter is of class C<right_class>. Both classes are C<STRING *>s that hold
40 the PMC class names for the left and right sides. If either class isn't yet
41 loaded, Parrot will cache the information such that the function will be
42 installed if at some point in the future both classes are available.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
43
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
44 Currently this is done by just assigning class numbers to the classes, which
45 the classes will pick up and use if they're later loaded, but we may later put
46 the functions into a deferred table that we scan when PMC classes are loaded.
47 Either way, the function will be guaranteed to be installed when it's needed.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
48
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
49 The function table must exist, but if it is too small, it will automatically be
50 expanded.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
51
52 =item mmd_register(interp, func_num, left_type, right_type, funcptr)
53
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
54 Register a function C<funcptr> for MMD function table C<func_num> for classes
55 C<left_type> and C<right_type>. The left and right types are C<INTVAL>s that
56 represent the class ID numbers.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
57
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
58 The function table must exist, but if it is too small, it will automatically be
59 expanded.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
60
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
61 Currently the MMD system doesn't handle inheritance and best match searching,
62 as it assumes that all PMC types have no parent type. This can be considered a
63 bug, and will be resolved at some point in the future.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
64
65 =item mmd_dispatch_pmc(interp, left, right, dest, func_num)
66
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
67 Dispatch to a multimethod that "returns" a PMC. C<left>, C<right>, and C<dest>
68 are all PMC pointers, while C<func_num> is the MMD table that should be used to
69 do the dispatching.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
70
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
71 The MMD system will figure out which function should be called based on the
72 types of C<left> and C<right> and call it, passing in C<left>, C<right>, and
73 C<dest> like any other binary vtable function.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
74
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
75 This function has a void return type, like all the "take two PMCs, return a
76 PMC" vtable functions do.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
77
78 =item STRING *mmd_dispatch_string(interp, left, right, func_num)
79
1772034 @jhoblitt reformat all Pod files under docs with podtidy except for docs/pdds
jhoblitt authored
80 Dispatch to a multimethod that returns a string. C<left> and C<right> are PMC
81 pointers, while C<func_num> is the MMD table that should be used to do the
82 dispatching. The function is responsible for creating the returned string.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
83
84 =item INTVAL mmd_dispatch_intval(interp, left, right, func_num)
85
86 Like C<mmd_dispatch_string>, only it returns an INTVAL.
87
ff299f0 Change mmd_dispatch_numval to mmd_dispatch_floatval
Simon Glover authored
88 =item FLOATVAL mmd_dispatch_floatval(interp, left, right, func_num)
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
89
90 Like C<mmd_dispatch_string>, only it returns a FLOATVAL.
91
92 =item mmd_add_function(interp, func_num, default_func)
93
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
94 Add a new function table to the list of functions the MMD system knows of.
95 C<func_num> is the number of the new function, while C<default_func> is the
96 function to be called when the system doesn't know which function it should
97 call. (Because, for example, there hasn't been a function installed that
98 matches the left and right types for a call)
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
99
100 =back
101
102 =head2 Constants
103
104 The following constants are defined to identify function tables:
105
106 =over 4
107
108 =item MMD_ADD
109
110 Addition
111
112 =item MMD_SUBTRACT
113
114 Subtraction
115
116 =item MMD_MULTIPLY
117
118 Multiplication
119
120 =item MMD_DIVIDE
121
122 Division
123
124 =item MMD_MOD
125
126 Accurate modulus
127
128 =item MMD_CMOD
129
130 C-style modulus
131
132 =item MMD_BAND
133
134 Binary and
135
136 =item MMD_BOR
137
138 Binary or
139
140 =item MMD_BXOR
141
142 Binary xor
143
144 =item MMD_BSL
145
146 Bitshift left
147
148 =item MMD_BSR
149
150 Bitshift right
151
152 =item MMD_CONCAT
153
154 String concatenation
155
156 =item MMD_LAND
157
158 Short-circuiting logical and
159
160 =item MMD_LOR
161
162 Short-circuiting logical or
163
164 =item MMD_LXOR
165
166 Logical xor (not short-circuiting)
167
168 =item MMD_REPEAT
169
8e257b0 Fix a few typos
Simon Glover authored
170 String repetition
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
171
172 =item MMD_NUMEQ
173
174 Numeric equality
175
176 =item MMD_STREQ
177
178 String equality
179
180 =item MMD_NUMCMP
181
182 Numeric comparison
183
184 =item MMD_STRCMP
185
186 String comparison
187
188 =item MMD_SOR
189
190 Bitwise or of the string value
191
192 =item MMD_SAND
193
194 Bitwise and of the string value
195
196 =item MMD_SXOR
197
198 Bitwise xor of the string value
199
200 =back
201
202 =head2 Defaults
203
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
204 By default, functions are installed for all the functions that have constants
205 associated with them. They are all functions suitable for calling with
206 C<mmd_dispatch_pmc>.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
207
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
208 The math functions (add, subtract, multiply, and divide) all work on the float
209 values of the left and right sides.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
210
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
211 The cmod function does a plan C-style mod (the C C<%> operator) on the integer
212 value of the left and right sides.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
213
214 The mod function does an fmod on the float values of the two sides.
215
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
216 The bitwise functions (and, or, xor, left shift, right shift) work on the
217 integer values of the two sides.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
218
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
219 The concat function concatenates the string values of the left and right sides.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
220
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
221 The logical functions (and, or, xor) use the boolean values of the left and
222 right sides to see whether they should set_pmc the destination to the left or
223 right sides. The C<and> and C<or> functions short-circuit, C<xor> does not.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
224
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
225 The repeat function gets the string value of the left side and the integer
226 value of the right.
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
227
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
228 The numeric equal and numeric comparison functions work on the float values of
ebc99df Docs for the MMD subsystem
Dan Sugalski authored
229 both sides.
230
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
231 The string equal and comparison functions work on the string values of both
232 sides.
233
234 The string bitwise ops (and, or, xor) take the string values of both sides and
235 do bitwise operations on the resulting bitstring.
1772034 @jhoblitt reformat all Pod files under docs with podtidy except for docs/pdds
jhoblitt authored
236
Something went wrong with that request. Please try again.