| 1 | ;;; -*-lisp-*- |
| 2 | ;;; |
| 3 | ;;; Method combination protocol |
| 4 | ;;; |
| 5 | ;;; (c) 2009 Straylight/Edgeware |
| 6 | ;;; |
| 7 | |
| 8 | ;;;----- Licensing notice --------------------------------------------------- |
| 9 | ;;; |
| 10 | ;;; This file is part of the Sensble Object Design, an object system for C. |
| 11 | ;;; |
| 12 | ;;; SOD is free software; you can redistribute it and/or modify |
| 13 | ;;; it under the terms of the GNU General Public License as published by |
| 14 | ;;; the Free Software Foundation; either version 2 of the License, or |
| 15 | ;;; (at your option) any later version. |
| 16 | ;;; |
| 17 | ;;; SOD is distributed in the hope that it will be useful, |
| 18 | ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 19 | ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 20 | ;;; GNU General Public License for more details. |
| 21 | ;;; |
| 22 | ;;; You should have received a copy of the GNU General Public License |
| 23 | ;;; along with SOD; if not, write to the Free Software Foundation, |
| 24 | ;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 25 | |
| 26 | (cl:in-package #:sod) |
| 27 | |
| 28 | ;;;-------------------------------------------------------------------------- |
| 29 | ;;; Effective methods and entries. |
| 30 | |
| 31 | (export '(effective-method effective-method-message effective-method-class)) |
| 32 | (defclass effective-method () |
| 33 | ((message :initarg :message :type sod-message |
| 34 | :reader effective-method-message) |
| 35 | (class :initarg :class :type sod-class :reader effective-method-class)) |
| 36 | (:documentation |
| 37 | "The behaviour invoked by sending a message to an instance of a class. |
| 38 | |
| 39 | This class describes the behaviour when an instance of CLASS is sent |
| 40 | MESSAGE. |
| 41 | |
| 42 | This is not a useful class by itself. Message classes are expected to |
| 43 | define their own effective-method classes. |
| 44 | |
| 45 | An effective method class must accept a `:direct-methods' initarg, which |
| 46 | will be a list of applicable methods sorted in most-to-least specific |
| 47 | order. (Either that or you have to add an overriding method to |
| 48 | `compute-sod-effective-method'.")) |
| 49 | |
| 50 | (export 'message-effective-method-class) |
| 51 | (defgeneric message-effective-method-class (message) |
| 52 | (:documentation |
| 53 | "Return the effective method class for the given MESSAGE. |
| 54 | |
| 55 | This function is invoked by `compute-sod-effective-method'.")) |
| 56 | |
| 57 | (export 'primary-method-class) |
| 58 | (defgeneric primary-method-class (message) |
| 59 | (:documentation |
| 60 | "Return the name of the primary direct method class for MESSAGE. |
| 61 | |
| 62 | This protocol is used by `simple-message' subclasses.")) |
| 63 | |
| 64 | (export 'compute-sod-effective-method) |
| 65 | (defgeneric compute-sod-effective-method (message class) |
| 66 | (:documentation |
| 67 | "Return the effective method when a CLASS instance receives MESSAGE. |
| 68 | |
| 69 | The default method constructs an instance of the message's chosen |
| 70 | `message-effective-method-class', passing the MESSAGE, the CLASS and the |
| 71 | list of applicable methods as initargs to `make-instance'.")) |
| 72 | |
| 73 | (export 'compute-effective-methods) |
| 74 | (defgeneric compute-effective-methods (class) |
| 75 | (:documentation |
| 76 | "Return a list of all of the effective methods needed for CLASS. |
| 77 | |
| 78 | The list needn't be in any particular order.")) |
| 79 | |
| 80 | (export '(method-entry method-entry-effective-method |
| 81 | method-entry-chain-head method-entry-chain-tail)) |
| 82 | (defclass method-entry () |
| 83 | ((method :initarg :method :type effective-method |
| 84 | :reader method-entry-effective-method) |
| 85 | (chain-head :initarg :chain-head :type sod-class |
| 86 | :reader method-entry-chain-head) |
| 87 | (chain-tail :initarg :chain-tail :type sod-class |
| 88 | :reader method-entry-chain-tail) |
| 89 | (role :initarg :role :type (or :keyword null) :reader method-entry-role)) |
| 90 | (:documentation |
| 91 | "An entry point into an effective method. |
| 92 | |
| 93 | Specifically, this is the entry point to the effective METHOD invoked via |
| 94 | the vtable for the chain headed by CHAIN-HEAD, and serving the given ROLE. |
| 95 | The CHAIN-TAIL is the most specific class on this chain; this is useful |
| 96 | because we can reuse the types of method entries from superclasses on |
| 97 | non-primary chains. |
| 98 | |
| 99 | Each effective method may have several different method entries, because |
| 100 | an effective method can be called via vtables attached to different |
| 101 | chains, and such calls will pass instance pointers which point to |
| 102 | different `ichain' structures within the overall instance layout; it's the |
| 103 | job of the method entry to adjust the instance pointers correctly for the |
| 104 | rest of the effective method. |
| 105 | |
| 106 | A vtable can contain more than one entry for the same message. Such |
| 107 | entries are distinguished by their roles. A message always has an entry |
| 108 | with the `nil role; in addition, a varargs message also has a `:valist' |
| 109 | role, which accepts a `va_list' argument in place of the variable argument |
| 110 | listNo other roles are currently defined, though they may be introduced by |
| 111 | extensions. |
| 112 | |
| 113 | The boundaries between a method entry and the effective method |
| 114 | is (intentionally) somewhat fuzzy. In extreme cases, the effective method |
| 115 | may not exist at all as a distinct entity in the output because its |
| 116 | content is duplicated in all of the method entry functions. This is left |
| 117 | up to the effective method protocol.")) |
| 118 | |
| 119 | (export 'make-method-entries) |
| 120 | (defgeneric make-method-entries (effective-method chain-head chain-tail) |
| 121 | (:documentation |
| 122 | "Return a list of `method-entry' objects for an EFFECTIVE-METHOD called |
| 123 | via CHAIN-HEAD. |
| 124 | |
| 125 | There is no default method for this function. (Maybe when the |
| 126 | effective-method/method-entry output protocol has settled down I'll know |
| 127 | what a sensible default action would be.)")) |
| 128 | |
| 129 | ;;;-------------------------------------------------------------------------- |
| 130 | ;;; Protocol for messages and direct-methods. |
| 131 | |
| 132 | (export 'sod-message-argument-tail) |
| 133 | (defgeneric sod-message-argument-tail (message) |
| 134 | (:documentation |
| 135 | "Return the argument tail for the message, with invented argument names. |
| 136 | |
| 137 | No `me' argument is prepended; any `:ellipsis' is left as it is.")) |
| 138 | |
| 139 | (export 'sod-message-no-varargs-tail) |
| 140 | (defgeneric sod-message-no-varargs-tail (message) |
| 141 | (:documentation |
| 142 | "Return the argument tail for the message with `:ellipsis' substituted. |
| 143 | |
| 144 | As with `sod-message-argument-tail', no `me' argument is prepended. |
| 145 | However, an `:ellipsis' is replaced by an argument of type `va_list', |
| 146 | named `sod__ap'.")) |
| 147 | |
| 148 | (export 'sod-method-function-type) |
| 149 | (defgeneric sod-method-function-type (method) |
| 150 | (:documentation |
| 151 | "Return the C function type for the direct method. |
| 152 | |
| 153 | This is called during initialization of a direct method object, and the |
| 154 | result is cached. |
| 155 | |
| 156 | A default method is provided (by `basic-direct-method') which simply |
| 157 | prepends an appropriate `me' argument to the user-provided argument list. |
| 158 | Fancy method classes may need to override this behaviour.")) |
| 159 | |
| 160 | (export 'sod-method-next-method-type) |
| 161 | (defgeneric sod-method-next-method-type (method) |
| 162 | (:documentation |
| 163 | "Return the C function type for the next-method trampoline. |
| 164 | |
| 165 | This is called during initialization of a direct method object, and the |
| 166 | result is cached. It should return a function type, not a pointer type. |
| 167 | |
| 168 | A default method is provided (by `delegating-direct-method') which should |
| 169 | do the right job. Very fancy subclasses might need to do something |
| 170 | different.")) |
| 171 | |
| 172 | (export 'sod-method-function-name) |
| 173 | (defgeneric sod-method-function-name (method) |
| 174 | (:documentation |
| 175 | "Return the C function name for the direct method.")) |
| 176 | |
| 177 | (export 'varargs-message-p) |
| 178 | (defun varargs-message-p (message) |
| 179 | "Answer whether the MESSAGE accepts a variable-length argument list. |
| 180 | |
| 181 | We need to jump through some extra hoops in order to cope with varargs |
| 182 | messages, so this is useful to know." |
| 183 | (member :ellipsis (sod-message-argument-tail message))) |
| 184 | |
| 185 | ;;;-------------------------------------------------------------------------- |
| 186 | ;;; Protocol for effective methods and method entries. |
| 187 | |
| 188 | (export 'method-entry-function-type) |
| 189 | (defgeneric method-entry-function-type (entry) |
| 190 | (:documentation |
| 191 | "Return the C function type for a method entry.")) |
| 192 | |
| 193 | (export 'method-entry-slot-name) |
| 194 | (defgeneric method-entry-slot-name (entry) |
| 195 | (:documentation |
| 196 | "Return the `vtmsgs' slot name for a method entry. |
| 197 | |
| 198 | The default method indirects through `method-entry-slot-name-by-role'.")) |
| 199 | |
| 200 | (defgeneric method-entry-slot-name-by-role (entry role name) |
| 201 | (:documentation "Easier implementation for `method-entry-slot-name'.") |
| 202 | (:method ((entry method-entry) (role (eql nil)) name) name) |
| 203 | (:method ((entry method-entry) (role (eql :valist)) name) |
| 204 | (format nil "~A__v" name))) |
| 205 | |
| 206 | (export 'effective-method-basic-argument-names) |
| 207 | (defgeneric effective-method-basic-argument-names (method) |
| 208 | (:documentation |
| 209 | "Return a list of argument names to be passed to direct methods. |
| 210 | |
| 211 | The argument names are constructed from the message's arguments returned |
| 212 | by `sod-message-no-varargs-tail'. The basic arguments are the ones |
| 213 | immediately derived from the programmer's explicitly stated arguments; the |
| 214 | `me' argument is not included, and neither are more exotic arguments added |
| 215 | as part of the method delegation protocol.")) |
| 216 | |
| 217 | ;;;-------------------------------------------------------------------------- |
| 218 | ;;; Code generation. |
| 219 | |
| 220 | ;;; Enhanced code-generator class. |
| 221 | |
| 222 | (export '(method-codegen codegen-message codegen-class |
| 223 | codegen-method codegen-target)) |
| 224 | (defclass method-codegen (codegen) |
| 225 | ((message :initarg :message :type sod-message :reader codegen-message) |
| 226 | (class :initarg :class :type sod-class :reader codegen-class) |
| 227 | (method :initarg :method :type effective-method :reader codegen-method) |
| 228 | (target :initarg :target :reader codegen-target)) |
| 229 | (:documentation |
| 230 | "Augments CODEGEN with additional state regarding an effective method. |
| 231 | |
| 232 | We store the effective method, and also its target class and owning |
| 233 | message, so that these values are readily available to the code-generating |
| 234 | functions.")) |
| 235 | |
| 236 | ;;; Protocol. |
| 237 | |
| 238 | (export 'compute-effective-method-body) |
| 239 | (defgeneric compute-effective-method-body (method codegen target) |
| 240 | (:documentation |
| 241 | "Generates the body of an effective method. |
| 242 | |
| 243 | Writes the function body to the code generator. It can (obviously) |
| 244 | generate auxiliary functions if it needs to. |
| 245 | |
| 246 | The arguments are as specified by the `sod-message-no-varargs-tail', with |
| 247 | an additional argument `sod__obj' of type pointer-to-ilayout. The code |
| 248 | should deliver the result (if any) to the TARGET.")) |
| 249 | |
| 250 | (export 'simple-method-body) |
| 251 | (defgeneric simple-method-body (method codegen target) |
| 252 | (:documentation |
| 253 | "Generate the body of a simple effective method. |
| 254 | |
| 255 | The function is invoked on an effective METHOD, with a CODEGEN to which it |
| 256 | should emit code delivering the method's value to TARGET.")) |
| 257 | |
| 258 | ;;; Additional instructions. |
| 259 | |
| 260 | (definst convert-to-ilayout (stream :export t) (class chain-head expr) |
| 261 | (format stream "SOD_ILAYOUT(~@<~A, ~_~A, ~_~A~:>)" |
| 262 | class (sod-class-nickname chain-head) expr)) |
| 263 | |
| 264 | ;;; Utilities. |
| 265 | |
| 266 | (export 'invoke-method) |
| 267 | (defun invoke-method (codegen target arguments-tail direct-method) |
| 268 | "Emit code to invoke DIRECT-METHOD, passing it ARGUMENTS-TAIL. |
| 269 | |
| 270 | The code is generated in the context of CODEGEN, which can be any instance |
| 271 | of the `codegen' class -- it needn't be an instance of `method-codegen'. |
| 272 | The DIRECT-METHOD is called with the given ARGUMENTS-TAIL (a list of |
| 273 | argument expressions), preceded by a `me' argument of type pointer-to- |
| 274 | CLASS where CLASS is the class on which the method was defined. |
| 275 | |
| 276 | If the message accepts a variable-length argument list then a copy of the |
| 277 | prevailing argument pointer is provided in place of the `:ellipsis'." |
| 278 | |
| 279 | (let* ((message (sod-method-message direct-method)) |
| 280 | (class (sod-method-class direct-method)) |
| 281 | (function (sod-method-function-name direct-method)) |
| 282 | (arguments (cons (format nil "&sod__obj->~A.~A" |
| 283 | (sod-class-nickname |
| 284 | (sod-class-chain-head class)) |
| 285 | (sod-class-nickname class)) |
| 286 | arguments-tail))) |
| 287 | (if (varargs-message-p message) |
| 288 | (convert-stmts codegen target |
| 289 | (c-type-subtype (sod-method-type direct-method)) |
| 290 | (lambda (var) |
| 291 | (ensure-var codegen *sod-tmp-ap* (c-type va-list)) |
| 292 | (emit-inst codegen |
| 293 | (make-va-copy-inst *sod-tmp-ap* |
| 294 | *sod-ap*)) |
| 295 | (deliver-expr codegen var |
| 296 | (make-call-inst function arguments)) |
| 297 | (emit-inst codegen |
| 298 | (make-va-end-inst *sod-tmp-ap*)))) |
| 299 | (deliver-expr codegen target (make-call-inst function arguments))))) |
| 300 | |
| 301 | (export 'ensure-ilayout-var) |
| 302 | (defun ensure-ilayout-var (codegen super) |
| 303 | "Define a variable `sod__obj' pointing to the class's ilayout structure. |
| 304 | |
| 305 | CODEGEN is a `method-codegen'. The class in question is CODEGEN's class, |
| 306 | i.e., the target class for the effective method. SUPER is one of the |
| 307 | class's superclasses; it is assumed that `me' is a pointer to a SUPER |
| 308 | (i.e., to SUPER's ichain within the ilayout)." |
| 309 | |
| 310 | (let* ((class (codegen-class codegen)) |
| 311 | (super-head (sod-class-chain-head super))) |
| 312 | (ensure-var codegen "sod__obj" |
| 313 | (c-type (* (struct (ilayout-struct-tag class)))) |
| 314 | (make-convert-to-ilayout-inst class super-head "me")))) |
| 315 | |
| 316 | (export 'make-trampoline) |
| 317 | (defun make-trampoline (codegen super body) |
| 318 | "Construct a trampoline function and return its name. |
| 319 | |
| 320 | CODEGEN is a `method-codegen'. SUPER is a superclass of the CODEGEN |
| 321 | class. We construct a new trampoline function (with an unimaginative |
| 322 | name) suitable for being passed to a direct method defined on SUPER as its |
| 323 | `next_method'. In particular, it will have a `me' argument whose type is |
| 324 | pointer-to-SUPER. |
| 325 | |
| 326 | The code of the function is generated by BODY, which will be invoked with |
| 327 | a single argument which is the TARGET to which it should deliver its |
| 328 | result. |
| 329 | |
| 330 | The return value is the name of the generated function." |
| 331 | |
| 332 | (let* ((message (codegen-message codegen)) |
| 333 | (message-type (sod-message-type message)) |
| 334 | (return-type (c-type-subtype message-type)) |
| 335 | (raw-args (sod-message-argument-tail message)) |
| 336 | (arguments (if (varargs-message-p message) |
| 337 | (cons (make-argument *sod-ap* |
| 338 | (c-type va-list)) |
| 339 | (butlast raw-args)) |
| 340 | raw-args))) |
| 341 | (codegen-push codegen) |
| 342 | (ensure-ilayout-var codegen super) |
| 343 | (funcall body (codegen-target codegen)) |
| 344 | (codegen-pop-function codegen (temporary-function) |
| 345 | (c-type (fun (lisp return-type) |
| 346 | ("me" (* (class super))) |
| 347 | . arguments))))) |
| 348 | |
| 349 | ;;;-------------------------------------------------------------------------- |
| 350 | ;;; Method entry protocol. |
| 351 | |
| 352 | (export 'effective-method-function-name) |
| 353 | (defgeneric effective-method-function-name (method) |
| 354 | (:documentation |
| 355 | "Returns the function name of an effective method.")) |
| 356 | |
| 357 | (export 'method-entry-function-name) |
| 358 | (defgeneric method-entry-function-name (method chain-head role) |
| 359 | (:documentation |
| 360 | "Returns the function name of a method entry. |
| 361 | |
| 362 | The method entry is given as an effective method/chain-head/role triple, |
| 363 | rather than as a method entry object because we want the function name |
| 364 | before we've made the entry object.")) |
| 365 | |
| 366 | (export 'compute-method-entry-functions) |
| 367 | (defgeneric compute-method-entry-functions (method) |
| 368 | (:documentation |
| 369 | "Construct method entry functions. |
| 370 | |
| 371 | Builds the effective method function (if there is one) and the necessary |
| 372 | method entries. Returns a list of functions (i.e., `function-inst' |
| 373 | objects) which need to be defined in the generated source code.")) |
| 374 | |
| 375 | ;;;-------------------------------------------------------------------------- |
| 376 | ;;; Invoking direct methods. |
| 377 | |
| 378 | (export 'invoke-delegation-chain) |
| 379 | (defun invoke-delegation-chain (codegen target basic-tail chain kernel) |
| 380 | "Invoke a chain of delegating methods. |
| 381 | |
| 382 | CODEGEN is a `method-codegen'. BASIC-TAIL is a list of argument |
| 383 | expressions to provide to the methods. The result of the delegation chain |
| 384 | will be delivered to TARGET. |
| 385 | |
| 386 | The CHAIN is a list of method objects (it's intended to be used with |
| 387 | `delegating-direct-method' objects). The behaviour is as follows. The |
| 388 | first method in the chain is invoked with the necessary arguments (see |
| 389 | below) including a `next_method' pointer. If KERNEL is nil and there are |
| 390 | no more methods in the chain then the `next_method' pointer will be null; |
| 391 | otherwise it will point to a `trampoline' function, whose behaviour is to |
| 392 | call the remaining methods on the chain as a delegation chain. The method |
| 393 | may choose to call this function with its arguments. It will finally |
| 394 | return a value, which will be delivered to the TARGET. |
| 395 | |
| 396 | If the chain is empty, then the code generated by KERNEL (given a TARGET |
| 397 | argument) will be invoked. It is an error if both CHAIN and KERNEL are |
| 398 | nil." |
| 399 | |
| 400 | (let* ((message (codegen-message codegen)) |
| 401 | (argument-tail (if (varargs-message-p message) |
| 402 | (cons *sod-tmp-ap* basic-tail) |
| 403 | basic-tail))) |
| 404 | (labels ((next-trampoline (method chain) |
| 405 | (if (or kernel chain) |
| 406 | (make-trampoline codegen (sod-method-class method) |
| 407 | (lambda (target) |
| 408 | (invoke chain target))) |
| 409 | 0)) |
| 410 | (invoke (chain target) |
| 411 | (if (null chain) |
| 412 | (funcall kernel target) |
| 413 | (let ((trampoline (next-trampoline (car chain) |
| 414 | (cdr chain)))) |
| 415 | (invoke-method codegen target |
| 416 | (cons trampoline argument-tail) |
| 417 | (car chain)))))) |
| 418 | (invoke chain target)))) |
| 419 | |
| 420 | ;;;----- That's all, folks -------------------------------------------------- |