mdw@git.distorted.org.uk Git - sod/blob - doc/layout.tex

   1 %%% -*-latex-*-
   2 %%%
   3 %%% Class layout and method combination protocols
   4 %%%
   5 %%% (c) 2015 Straylight/Edgeware
   6 %%%
   7
   8 %%%----- Licensing notice ---------------------------------------------------
   9 %%%
  10 %%% This file is part of the Sensible 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 \chapter{Class layout and method combination}
  27
  28 %%%--------------------------------------------------------------------------
  29 \section{Class layout protocol} \label{sec:layout.instance}
  30
  31 \begin{describe}{fun}{islots-struct-tag @<class> @> @<string>}
  32 \end{describe}
  33
  34 \begin{describe}{fun}{ichain-struct-tag @<class> @<chain-head> @> @<string>}
  35 \end{describe}
  36
  37 \begin{describe}{fun}{ichain-union-tag @<class> @<chain-head> @> @<string>}
  38 \end{describe}
  39
  40 \begin{describe}{fun}{ilayout-struct-tag @<class> @> @<string>}
  41 \end{describe}
  42
  43 \begin{describe}{fun}{vtmsgs-struct-tag @<class> @<super> @> @<string>}
  44 \end{describe}
  45
  46 \begin{describe}{fun}{vtable-union-tag @<class> @<chain-head> @> @<string>}
  47 \end{describe}
  48
  49 \begin{describe}{fun}{vtable-struct-tag @<class> @<chain-head> @> @<string>}
  50 \end{describe}
  51
  52 \begin{describe}{fun}{vtable-name @<class> @<chain-head> @> @<string>}
  53 \end{describe}
  54
  55 \begin{describe}{fun}{message-macro-name @<class> @<entry> @> @<string>}
  56 \end{describe}
  57
  58 \begin{describe}{cls}{effective-slot () \&key :class :slot :initializer}
  59 \end{describe}
  60
  61 \begin{describe*}
  62     {\dhead{gf}{effective-slot-class @<slot> @> @<class>}
  63      \dhead{gf}{effective-slot-direct-slot @<slot> @> @<direct-slot>}
  64      \dhead{gf}{effective-slot-initializer @<slot> @> @<init-or-nil>}}
  65 \end{describe*}
  66
  67 \begin{describe}{gf}
  68     {find-slot-initializer @<class> @<slot> @> @<init-or-nil>}
  69 \end{describe}
  70
  71 \begin{describe}{gf}
  72     {find-class-initializer @<slot> @<class> @> @<init-or-nil>}
  73 \end{describe}
  74
  75 \begin{describe}{gf}{find-slot-initargs @<class> @<slot> @> @<list>}
  76 \end{describe}
  77
  78 \begin{describe}{gf}
  79     {compute-effective-slot @<class> @<slot> @> @<effective-slot>}
  80 \end{describe}
  81
  82 \begin{describe}{cls}
  83     {sod-class-effective-slot (effective-slot) \\ \ind
  84       \&key :class :slot :initializer-function :prepare-function}
  85 \end{describe}
  86
  87 \begin{describe*}
  88     {\dhead{gf}{effective-slot-initializer-function @<slot> @> @<function>}
  89      \dhead{gf}{effective-slot-prepare-function @<slot> @> @<function>}}
  90 \end{describe*}
  91
  92 \begin{describe}{cls}{islots () \&key :class :subclass :slots}
  93 \end{describe}
  94
  95 \begin{describe*}
  96     {\dhead{gf}{islots-class @<islots> @> @<class>}
  97      \dhead{gf}{islots-subclass @<islots> @> @<class>}
  98      \dhead{gf}{islots-slots @<islots> @> @<list>}}
  99 \end{describe*}
 100
 101 \begin{describe}{gf}{compute-islots @<class> @<subclass> @> @<islots>}
 102 \end{describe}
 103
 104 \begin{describe}{cls}{vtable-pointer () \&key :class :chain-head :chain-tail}
 105 \end{describe}
 106
 107 \begin{describe*}
 108     {\dhead{gf}{vtable-pointer-class @<vtable-pointer> @> @<class>}
 109      \dhead{gf}{vtable-pointer-chain-head @<vtable-pointer> @> @<class>}
 110      \dhead{gf}{vtable-pointer-chain-tail @<vtable-pointer> @> @<class>}}
 111 \end{describe*}
 112
 113 \begin{describe}{cls}{ichain () \&key :class :chain-head :chain-tail :body}
 114 \end{describe}
 115
 116 \begin{describe*}
 117     {\dhead{gf}{ichain-class @<ichain> @> @<class>}
 118      \dhead{gf}{ichain-head @<ichain> @> @<class>}
 119      \dhead{gf}{ichain-tail @<ichain> @> @<class>}
 120      \dhead{gf}{ichain-body @<ichain> @> @<list>}}
 121 \end{describe*}
 122
 123 \begin{describe}{gf}{compute-ichain @<class> @<chain> @> @<ichain>}
 124 \end{describe}
 125
 126 \begin{describe}{cls}{ilayout () \&key :class :ichains}
 127 \end{describe}
 128
 129 \begin{describe*}
 130     {\dhead{gf}{ilayout-class @<ilayout> @> @<class>}
 131      \dhead{gf}{ilayout-ichains @<ilayout> @> @<list>}}
 132 \end{describe*}
 133
 134 \begin{describe}{gf}{sod-class-ilayout @<class> @> @<ilayout>}
 135 \end{describe}
 136
 137 \begin{describe}{gf}{compute-ilayout @<class> @> @<ilayout>}
 138 \end{describe}
 139
 140 \begin{describe}{cls}
 141     {vtmsgs () \&key :class :subclass :chain-head :chain-tail :entries}
 142 \end{describe}
 143
 144 \begin{describe*}
 145     {\dhead{gf}{vtmsgs-class @<vtmsgs> @> @<class>}
 146      \dhead{gf}{vtmsgs-subclass @<vtmsgs> @> @<class>}
 147      \dhead{gf}{vtmsgs-chain-head @<vtmsgs> @> @<class>}
 148      \dhead{gf}{vtmsgs-chain-tail @<vtmsgs> @> @<class>}
 149      \dhead{gf}{vtmsgs-entries @<vtmsgs> @> @<list>}}
 150 \end{describe*}
 151
 152 \begin{describe}{gf}
 153     {compute-vtmsgs @<class> @<subclass> @<chain-head> @<chain-tail>
 154       @> @<vtmsgs>}
 155 \end{describe}
 156
 157 \begin{describe}{cls}
 158     {class-pointer () \&key :class :chain-head :metaclass :meta-chain-head}
 159 \end{describe}
 160
 161 \begin{describe*}
 162     {\dhead{gf}{class-pointer-class @<class-pointer> @> @<class>}
 163      \dhead{gf}{class-pointer-chain-head @<class-pointer> @> @<class>}
 164      \dhead{gf}{class-pointer-metaclass @<class-pointer> @> @<class>}
 165      \dhead{gf}{class-pointer-meta-chain-head @<class-pointer> @> @<class>}}
 166 \end{describe*}
 167
 168 \begin{describe}{fun}
 169     {make-class-pointer @<class> @<chain-head>
 170                         @<metaclass> @<meta-chain-head>
 171       @> @<class-pointer>}
 172 \end{describe}
 173
 174 \begin{describe}{cls}{base-offset () \&key :class :chain-head}
 175 \end{describe}
 176
 177 \begin{describe*}
 178     {\dhead{gf}{base-offset-class @<base-offset> @> @<class>}
 179      \dhead{gf}{base-offset-chain-head @<base-offset> @> @<class>}}
 180 \end{describe*}
 181
 182 \begin{describe}{fun}
 183     {make-base-offset @<class> @<chain-head> @> @<base-offset>}
 184 \end{describe}
 185
 186 \begin{describe}{cls}{chain-offset () \&key :class :chain-head :target-head}
 187 \end{describe}
 188
 189 \begin{describe*}
 190     {\dhead{gf}{chain-offset-class @<chain-offset> @> @<class>}
 191      \dhead{gf}{chain-offset-chain-head @<chain-offset> @> @<class>}
 192      \dhead{gf}{chain-offset-target-head @<chain-offset> @> @<class>}}
 193 \end{describe*}
 194
 195 \begin{describe}{fun}
 196     {make-chain-offset @<class> @<chain-head> @<target-head>
 197       @> @<chain-offset>}
 198 \end{describe}
 199
 200 \begin{describe}{cls}{vtable () \&key :class :chain-head :chain-tail :body}
 201 \end{describe}
 202
 203 \begin{describe*}
 204     {\dhead{gf}{vtable-class @<vtable> @> @<class>}
 205      \dhead{gf}{vtable-chain-head @<vtable> @> @<class>}
 206      \dhead{gf}{vtable-chain-tail @<vtable> @> @<class>}
 207      \dhead{gf}{vtable-body @<vtable> @> @<list>}}
 208 \end{describe*}
 209
 210 \begin{describe}{gf}
 211     {compute-vtable-items @<class> @<super>
 212                           @<chain-head> @<chain-tail>
 213                           @<emit-function>}
 214 \end{describe}
 215
 216 \begin{describe}{gf}{compute-vtable @<class> @<chain> @> @<vtable>}
 217 \end{describe}
 218
 219 \begin{describe}{gf}{sod-class-vtables @<class> @> @<list>}
 220 \end{describe}
 221
 222 \begin{describe}{gf}{compute-vtables @<class> @> @<list>}
 223 \end{describe}
 224
 225 %%%--------------------------------------------------------------------------
 226 \section{Method combination} \label{sec:layout.methods}
 227
 228 \begin{describe}{cls}{effective-method () \&key :message :class :keywords}
 229 \end{describe}
 230
 231 \begin{describe*}
 232     {\dhead{gf}{effective-method-message @<method> @> @<message>}
 233      \dhead{gf}{effective-method-class @<method> @> @<class>}
 234      \dhead{gf}{effective-method-keywords @<method> @> @<list>}}
 235 \end{describe*}
 236
 237 \begin{describe}{gf}
 238     {sod-message-receiver-type @<message> @<class> @> @<c-type>}
 239 \end{describe}
 240
 241 \begin{describe}{gf}
 242     {sod-message-applicable-methods @<message> @<class> @> list}
 243 \end{describe}
 244
 245 \begin{describe}{gf}
 246     {sod-message-keyword-argument-lists @<message> @<class>
 247                                         @<direct-methods> @<state>
 248       \nlret @<list>}
 249 \end{describe}
 250
 251 \begin{describe}{fun}
 252     {compute-effective-method-keyword-arguments @<message>
 253                                                 @<class>
 254                                                 @<direct-methods>
 255       \nlret @<list>}
 256 \end{describe}
 257
 258 \begin{describe}{gf}
 259     {sod-message-check-methods @<message> @<class> @<direct-methods>}
 260 \end{describe}
 261
 262 \begin{describe}{gf}
 263     {sod-message-effective-method-class @<message> @> @<class>}
 264 \end{describe}
 265
 266 \begin{describe}{gf}{primary-method-class @<message> @> @<class>}
 267 \end{describe}
 268
 269 \begin{describe}{gf}
 270     {compute-sod-effective-method @<message> @<class> @> @<method>}
 271 \end{describe}
 272
 273 \begin{describe}{gf}{sod-class-effective-methods @<class> @> @<list>}
 274 \end{describe}
 275
 276 \begin{describe}{gf}{compute-effective-methods @<class> @> @<list>}
 277 \end{describe}
 278
 279 \begin{describe}{cls}
 280     {method-entry () \&key :method :chain-head :chain-tail :role}
 281 \end{describe}
 282
 283 \begin{describe*}
 284     {\dhead{gf}{method-entry-effective-method @<method-entry> @> @<method>}
 285      \dhead{gf}{method-entry-chain-head @<method-entry> @> @<class>}
 286      \dhead{gf}{method-entry-chain-tail @<method-entry> @> @<class>}
 287      \dhead{gf}{method-entry-role @<method-entry> @> @<role>}}
 288 \end{describe*}
 289
 290 \begin{describe}{gf}
 291     {make-method-entries @<effective-method> @<chain-head> @<chain-tail>
 292       @> @<list>}
 293 \end{describe}
 294
 295
 296 \begin{describe}{gf}{sod-message-argument-tail @<message> @> @<list>}
 297 \end{describe}
 298
 299 \begin{describe}{gf}{sod-method-function-type @<method> @> @<c-type>}
 300 \end{describe}
 301
 302 \begin{describe}{gf}{sod-method-next-method-type @<method> @> @<c-type>}
 303 \end{describe}
 304
 305 \begin{describe}{gf}{sod-method-description @<method> @> @<string>}
 306 \end{describe}
 307
 308 \begin{describe}{gf}{sod-method-function-name @<method> @> @<string>}
 309 \end{describe}
 310
 311 \begin{describe}{fun}{varargs-message-p @<message> @> @<generalized-boolean>}
 312 \end{describe}
 313
 314 \begin{describe}{fun}{keyword-message-p @<message> @> @<generalized-boolean>}
 315 \end{describe}
 316
 317 \begin{describe}{gf}{method-entry-function-type @<entry> @> @<c-type>}
 318 \end{describe}
 319
 320 \begin{describe}{gf}{method-entry-slot-name @<entry> @> @<string>}
 321 \end{describe}
 322
 323 \begin{describe}{gf}
 324     {method-entry-slot-name-by-role @<entry> @<role> @<name> @> @<string>}
 325 \end{describe}
 326
 327 \begin{describe}{gf}
 328     {effective-method-basic-argument-names @<method> @> @<list>}
 329 \end{describe}
 330
 331 \begin{describe}{gf}
 332     {effective-method-live-p @<method> @> @<generalized-boolean>}
 333 \end{describe}
 334
 335
 336 \begin{describe}{cls}
 337     {method-codegen (codegen)                                   \\ \ind
 338       \&key :vars :insts :temp-index
 339             :message :class :method :target}
 340 \end{describe}
 341
 342 \begin{describe*}
 343     {\dhead{gf}{codegen-message @<codegen> @> @<message>}
 344      \dhead{gf}{codegen-class @<codegen> @> @<class>}
 345      \dhead{gf}{codegen-method @<codegen> @> @<method>}
 346      \dhead{gf}{codegen-target @<codegen> @> @<target>}}
 347 \end{describe*}
 348
 349 \begin{describe*}
 350     {\dhead{cls}{convert-to-ilayout-inst (inst)}
 351      \dhead{fun}
 352        {make-convert-to-ilayout-inst @<class> @<chain-head> @<expr>}}
 353   \def\makelabels#1#2{%
 354     #1{gf}{inst-class}[#2]#1{gf}{inst-chain-head}[#2]%
 355     \descindex{gf}{inst-expr}[#2]%
 356   }
 357   \makelabels{\desclabel}{|(}
 358
 359   \begin{prog}
 360     SOD_ILAYOUT(@<class>, @<chain-head-nick>, @<expr>)
 361   \end{prog}
 362
 363   \makelabels{\descindex}{|)}
 364 \end{describe*}
 365
 366
 367 \begin{describe}{gf}
 368     {compute-effective-method-body @<method> @<codegen> @<target>}
 369 \end{describe}
 370
 371 \begin{describe}{gf}{simple-method-body @<method> @<codegen> @<target>}
 372 \end{describe}
 373
 374 \begin{describe}{fun}
 375     {invoke-method @<codegen> @<target> @<arguments-tail> @<direct-method>}
 376 \end{describe}
 377
 378 \begin{describe}{fun}{ensure-ilayout-var @<codegen> @<super>}
 379 \end{describe}
 380
 381 \begin{describe}{fun}{make-trampoline @<codegen> @<super> @<body-func>}
 382 \end{describe}
 383
 384 \begin{describe}{gf}{effective-method-function-name @<method> @> @<string>}
 385 \end{describe}
 386
 387 \begin{describe}{gf}
 388     {method-entry-function-name @<method> @<chain-head> @<role> @> @<string>}
 389 \end{describe}
 390
 391 \begin{describe}{gf}{compute-method-entry-functions @<method> @> @<list>}
 392 \end{describe}
 393
 394 \begin{describe}{fun}
 395     {invoke-delegation-chain @<codegen> @<target> @<basic-tail>
 396                              @<chain> @<kernel-func>}
 397 \end{describe}
 398
 399 \begin{describe}{cls}
 400     {basic-message (sod-message) \&key :name :location :class :type}
 401 \end{describe}
 402
 403 \begin{describe}{cls}
 404     {simple-message (basic-message) \&key :name :location :class :type}
 405 \end{describe}
 406
 407 \begin{describe}{cls}
 408     {basic-direct-method (sod-method)
 409       \&key :message :location :class :type :body :role}
 410 \end{describe}
 411
 412 \begin{describe}{gf}{sod-method-role @<method> @> @<role>}
 413 \end{describe}
 414
 415 \begin{describe}{cls}
 416     {daemon-direct-method (basic-direct-method)                 \\ \ind
 417       \&key :message :location :class :type :body :role}
 418 \end{describe}
 419
 420 \begin{describe}{cls}
 421     {delegating-direct-method (basic-direct-method)             \\ \ind
 422       \&key :message :location :class :type :body :role}
 423 \end{describe}
 424
 425 \begin{describe}{cls}
 426     {basic-effective-method (effective-method)                  \\ \ind
 427       \&key :message :class :around-methods :before-methods :after-methods}
 428 \end{describe}
 429
 430 \begin{describe*}
 431     {\dhead{gf}
 432        {effective-method-around-methods @<effective-method> @> @<list>}
 433      \dhead{gf}
 434        {effective-method-before-methods @<effective-method> @> @<list>}
 435      \dhead{gf}
 436        {effective-method-after-methods @<effective-method> @> @<list>}
 437      \dhead{gf}{effective-method-functions @<effective-method> @> @<list>}}
 438 \end{describe*}
 439
 440 \begin{describe}{cls}
 441     {simple-effective-method (basic-effective-method)           \\ \ind
 442       \&key :message :class
 443             :around-methods :before-methods :after-methods :primary-methods}
 444 \end{describe}
 445
 446 \begin{describe}{fun}
 447     {basic-effective-method-body @<codegen> @<target> @<method> @<body>}
 448 \end{describe}
 449
 450 \begin{describe}{cls}
 451     {standard-message (simple-message) \&key :name :location :class :type}
 452 \end{describe}
 453
 454 \begin{describe}{cls}
 455     {standard-effective-method (simple-effective-method)        \\ \ind
 456       \&key :message :class
 457             :around-methods :before-methods :after-methods :primary-methods}
 458 \end{describe}
 459
 460 \begin{describe}{cls}
 461     {aggregating-message (simple-message)
 462       \&key :name :location :class :type :combination}
 463 \end{describe}
 464
 465 \begin{describe*}
 466     {\dhead{gf}{sod-message-combination @<message> @> @<keyword>}
 467      \dhead{gf}{sod-message-kernel-function @<message> @> @<function>}}
 468 \end{describe*}
 469
 470 \begin{describe}{gf}
 471     {aggregating-message-properties @<message> @<combination> @> @<plist>}
 472 \end{describe}
 473
 474 \begin{describe}{gf}
 475     {compute-aggregating-message-kernel
 476       \=@<message> @<combination> @<target>                   \+\\
 477         @<methods> @<arg-names> \&key}
 478 \end{describe}
 479
 480 \begin{describe}{gf}
 481     {check-aggregating-message-type @<message> @<combination> @<c-type>}
 482 \end{describe}
 483
 484 \begin{describe}{cls}
 485      {aggregating-effective-method (simple-effective-method)    \\ \ind
 486       \&key :message :class
 487             :around-methods :before-methods :after-methods :primary-methods}
 488 \end{describe}
 489
 490 \begin{describe}{mac}
 491     {define-aggregating-method-combination @<combination>       \\ \ind\ind
 492         ((@<var-name>^*)
 493          @[[ :codegen @<codegen-var> @!
 494              :methods @<methods-var> @]])                     \-\\
 495       @[[ \=:properties (@{ (@{ @<name> @! (@[@<keyword>@] @<name>) @}
 496                              @<c-type>
 497                              @[@<default>
 498                                @[@<suppliedp-var>@]@]) @}^*) @! \+\\
 499             :return-type @<c-type> @!                           \\
 500             :around @<around-func> @!
 501             :first-method @<first-method-func> @!
 502             :method @<method-func> @]]}
 503 \end{describe}
 504
 505 %%% the method combination story
 506 %% compute-effective-methods --> compute-sod-effective-method
 507
 508 %% hook-output (basic-effective-method :c)
 509 %%   basic-effective-method.functions
 510 %%     compute-method-entry-functions
 511 %%       compute-effective-method-body
 512 %%
 513 %% compute-effective-method-body (simple-effective-method)
 514 %%   basic-effective-method-body
 515 %%   simple-method-body (standard-effective-method)
 516 %%   simple-method-body (aggregating-effective-method)
 517 %%     message-kernel-function
 518
 519 %%%----- That's all, folks --------------------------------------------------
 520
 521 %%% Local variables:
 522 %%% mode: LaTeX
 523 %%% TeX-master: "sod.tex"
 524 %%% TeX-PDF-mode: t
 525 %%% End: