docs/multidispatch.pod

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