lib/: Pure C machinery for handling `keyword arguments' to functions.

[sod] / doc / layout.tex

%%% -*-latex-*-
%%%
%%% Class layout and method combination protocols
%%%
%%% (c) 2015 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% This file is part of the Sensible Object Design, an object system for C.
%%%
%%% SOD is free software; you can redistribute it and/or modify
%%% it under the terms of the GNU General Public License as published by
%%% the Free Software Foundation; either version 2 of the License, or
%%% (at your option) any later version.
%%%
%%% SOD is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU General Public License for more details.
%%%
%%% You should have received a copy of the GNU General Public License
%%% along with SOD; if not, write to the Free Software Foundation,
%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

\chapter{Class layout and method combination}

%%%--------------------------------------------------------------------------
\section{Class layout protocol} \label{sec:layout.instance}

\begin{describe}{fun}{islots-struct-tag @<class> @> @<string>}
\end{describe}

\begin{describe}{fun}{ichain-struct-tag @<class> @<chain-head> @> @<string>}
\end{describe}

\begin{describe}{fun}{ichain-union-tag @<class> @<chain-head> @> @<string>}
\end{describe}

\begin{describe}{fun}{ilayout-struct-tag @<class> @> @<string>}
\end{describe}

\begin{describe}{fun}{vtmsgs-struct-tag @<class> @<super> @> @<string>}
\end{describe}

\begin{describe}{fun}{vtable-union-tag @<class> @<chain-head> @> @<string>}
\end{describe}

\begin{describe}{fun}{vtable-struct-tag @<class> @<chain-head> @> @<string>}
\end{describe}

\begin{describe}{fun}{vtable-name @<class> @<chain-head> @> @<string>}
\end{describe}

\begin{describe}{fun}{message-macro-name @<class> @<entry> @> @<string>}
\end{describe}

\begin{describe}{cls}{effective-slot () \&key :class :slot :initializer}
\end{describe}

\begin{describe*}
    {\dhead{gf}{effective-slot-class @<slot> @> @<class>}
     \dhead{gf}{effective-slot-direct-slot @<slot> @> @<direct-slot>}
     \dhead{gf}{effective-slot-initializer @<slot> @> @<init-or-nil>}}
\end{describe*}

\begin{describe}{gf}
    {find-slot-initializer @<class> @<slot> @> @<init-or-nil>}
\end{describe}

\begin{describe}{gf}
    {compute-effective-slot @<class> @<slot> @> @<effective-slot>}
\end{describe}

\begin{describe}{cls}
    {sod-class-effective-slot (effective-slot) \\ \ind
      \&key :class :slot :initializer-function :prepare-function}
\end{describe}

\begin{describe*}
    {\dhead{gf}{effective-slot-initializer-function @<slot> @> @<function>}
     \dhead{gf}{effective-slot-prepare-function @<slot> @> @<function>}}
\end{describe*}

\begin{describe}{cls}{islots () \&key :class :subclass :slots}
\end{describe}

\begin{describe*}
    {\dhead{gf}{islots-class @<islots> @> @<class>}
     \dhead{gf}{islots-subclass @<islots> @> @<class>}
     \dhead{gf}{islots-slots @<islots> @> @<list>}}
\end{describe*}

\begin{describe}{gf}{compute-islots @<class> @<subclass> @> @<islots>}
\end{describe}

\begin{describe}{gf}{vtable-pointer () \&key :class :chain-head :chain-tail}
\end{describe}

\begin{describe*}
    {\dhead{gf}{vtable-pointer-class @<vtable-pointer> @> @<class>}
     \dhead{gf}{vtable-pointer-chain-head @<vtable-pointer> @> @<class>}
     \dhead{gf}{vtable-pointer-chain-tail @<vtable-pointer> @> @<class>}}
\end{describe*}

\begin{describe}{gf}{ichain () \&key :class :chain-head :chain-tail :body}
\end{describe}

\begin{describe*}
    {\dhead{gf}{ichain-class @<ichain> @> @<class>}
     \dhead{gf}{ichain-chain-head @<ichain> @> @<class>}
     \dhead{gf}{ichain-chain-tail @<ichain> @> @<class>}
     \dhead{gf}{ichain-body @<ichain> @> @<list>}}
\end{describe*}

\begin{describe}{gf}{compute-ichain @<class> @<chain> @> @<ichain>}
\end{describe}

\begin{describe}{gf}{ilayout () \&key :class :ichains}
\end{describe}

\begin{describe*}
    {\dhead{gf}{ilayout-class @<ilayout> @> @<class>}
     \dhead{gf}{ilayout-ichains @<ilayout> @> @<list>}}
\end{describe*}

\begin{describe}{gf}{sod-class-ilayout <class> @> @<ilayout>}
\end{describe}

\begin{describe}{gf}{compute-ilayout @<class> @> @<ilayout>}
\end{describe}

\begin{describe}{cls}
    {vtmsgs () \&key :class :subclass :chain-head :chain-tail :entries}
\end{describe}

\begin{describe*}
    {\dhead{gf}{vtmsgs-class @<vtmsgs> @> @<class>}
     \dhead{gf}{vtmsgs-subclass @<vtmsgs> @> @<class>}
     \dhead{gf}{vtmsgs-chain-head @<vtmsgs> @> @<class>}
     \dhead{gf}{vtmsgs-chain-tail @<vtmsgs> @> @<class>}
     \dhead{gf}{vtmsgs-entries @<vtmsgs> @> @<list>}}
\end{describe*}

\begin{describe}{cls}
    {class-pointer () \&key :class :chain-head :metaclass :meta-chain-head}
\end{describe}

\begin{describe*}
    {\dhead{gf}{class-pointer-class @<class-pointer> @> @<class>}
     \dhead{gf}{class-pointer-chain-head @<class-pointer> @> @<class>}
     \dhead{gf}{class-pointer-metaclass @<class-pointer> @> @<class>}
     \dhead{gf}{class-pointer-meta-chain-head @<class-pointer> @> @<class>}}
\end{describe*}

\begin{describe}{fun}
    {make-class-pointer @<class> @<chain-head>
                        @<metaclass> @<meta-chain-head>
      @> @<class-pointer>}
\end{describe}

\begin{describe}{cls}{base-offset () \&key :class :chain-head}
\end{describe}

\begin{describe*}
    {\dhead{gf}{base-offset-class @<base-offset> @> @<class>}
     \dhead{gf}{base-offset-chain-head @<base-offset> @> @<class>}}
\end{describe*}

\begin{describe}{fun}
    {make-base-offset @<class> @<chain-head> @> @<base-offset>}
\end{describe}

\begin{describe}{cls}{chain-offset () \&key :class :chain-head :target-head}
\end{describe}

\begin{describe*}
    {\dhead{gf}{chain-offset-class @<chain-offset> @> @<class>}
     \dhead{gf}{chain-offset-chain-head @<chain-offset> @> @<class>}
     \dhead{gf}{chain-offset-target-head @<chain-offset> @> @<class>}}
\end{describe*}

\begin{describe}{fun}
    {make-chain-offset @<class> @<chain-head> @<target-head>
      @> @<chain-offset>}
\end{describe}

\begin{describe}{gf}{vtable () \&key :class :chain-head :chain-tail :body}
\end{describe}

\begin{describe*}
    {\dhead{gf}{vtable-class @<vtable> @> @<class>}
     \dhead{gf}{vtable-chain-head @<vtable> @> @<class>}
     \dhead{gf}{vtable-chain-tail @<vtable> @> @<class>}
     \dhead{gf}{vtable-body @<vtable> @> @<list>}}
\end{describe*}

\begin{describe}{gf}
    {compute-vtable-items @<class> @<super>
                          @<chain-head> @<chain-tail>
                          @<emit-function>}
\end{describe}

\begin{describe}{gf}{compute-vtable @<class> @<chain> @> @<vtable>}
\end{describe}

\begin{describe}{gf}{sod-class-vtables @<class> @> @<list>}
\end{describe}

\begin{describe}{gf}{compute-vtables @<class> @> @<list>}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Method combination} \label{sec:layout.methods}

\begin{describe}{cls}{effective-method () \&key :message :class}
\end{describe}

\begin{describe*}
    {\dhead{gf}{effective-method-message @<method> @> @<message>}
     \dhead{gf}{effective-method-class @<method> @> @<class>}}
\end{describe*}

\begin{describe}{gf}
    {sod-message-effective-method-class @<message> @> @<class>}
\end{describe}

\begin{describe}{gf}{primary-method-class @<message> @> @<class>}
\end{describe}

\begin{describe}{gf}
    {compute-sod-effective-method @<message> @<class> @> @<method>}
\end{describe}

\begin{describe}{gf}{sod-class-effective-methods @<class> @> @<list>}
\end{describe}

\begin{describe}{gf}{compute-effective-methods @<class> @> @<list>}
\end{describe}

\begin{describe}{cls}
    {method-entry () \&key :method :chain-head :chain-tail :role}
\end{describe}

\begin{describe*}
    {\dhead{gf}{method-entry-effective-method @<method-entry> @> @<method>}
     \dhead{gf}{method-entry-chain-head @<method-entry> @> @<class>}
     \dhead{gf}{method-entry-chain-tail @<method-entry> @> @<class>}
     \dhead{gf}{method-entry-role @<method-entry> @> @<role>}}
\end{describe*}

\begin{describe}{gf}
    {make-method-entries @<effective-method> @<chain-head> @<chain-tail>
      @> @<list>}
\end{describe}


\begin{describe}{gf}{sod-message-argument-tail @<message> @> @<list>}
\end{describe}

\begin{describe}{gf}{sod-message-no-varargs-tail @<message> @> @<list>}
\end{describe}

\begin{describe}{gf}{sod-method-function-type @<method> @> @<c-type>}
\end{describe}

\begin{describe}{gf}{sod-method-next-method-type @<method> @> @<c-type>}
\end{describe}

\begin{describe}{gf}{sod-method-function-name @<method> @> @<string>}
\end{describe}

\begin{describe}{fun}{varargs-message-p @<message> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{gf}{method-entry-function-type @<entry> @> @<c-type>}
\end{describe}

\begin{describe}{gf}{method-entry-slot-name @<entry> @> @<string>}
\end{describe}

\begin{describe}{gf}
    {method-entry-slot-name-by-role @<entry> @<role> @<name> @> @<string>}
\end{describe}

\begin{describe}{gf}
    {effective-method-basic-argument-names @<method> @> @<list>}
\end{describe}



\begin{describe}{cls}
    {method-codegen (codegen) \\ \ind
      \&key :vars :insts :temp-index
            :message :class :method :target}
\end{describe}

\begin{describe*}
    {\dhead{gf}{codegen-message @<codegen> @> @<message>}
     \dhead{gf}{codegen-class @<codegen> @> @<class>}
     \dhead{gf}{codegen-method @<codegen> @> @<method>}
     \dhead{gf}{codegen-target @<codegen> @> @<target>}}
\end{describe*}

\begin{describe*}
    {\dhead{cls}{convert-to-ilayout-inst (inst)}
     \dhead{fun}
       {make-convert-to-ilayout-inst @<class> @<chain-head> @<expr>}}
  \begin{prog}
    SOD_ILAYOUT(@<class>, @<chain-head-nick>, @<expr>)
  \end{prog}
\end{describe*}


\begin{describe}{gf}
    {compute-effective-method-body @<method> @<codegen> @<target>}
\end{describe}

\begin{describe}{gf}{simple-method-body @<method> @<codegen> @<target>}
\end{describe}

\begin{describe}{fun}
    {invoke-method @<codegen> @<target> @<arguments-tail> @<direct-method>}
\end{describe}

\begin{describe}{fun}{ensure-ilayout-var @<codegen> @<super>}
\end{describe}

\begin{describe}{fun}{make-trampoline @<codegen> @<super> @<body-func>}
\end{describe}

\begin{describe}{gf}{effective-method-function-name @<method> @> @<string>}
\end{describe}

\begin{describe}{gf}
    {method-entry-function-name @<method> @<chain-head> @<role> @> @<string>}
\end{describe}

\begin{describe}{gf}{compute-method-entry-functions @<method> @> @<list>}
\end{describe}

\begin{describe}{fun}
    {invoke-delegation-chain @<codegen> @<target> @<basic-tail>
                             @<chain> @<kernel-func>}
\end{describe}

\begin{describe}{cls}
    {basic-message (sod-message) \&key :name :location :class :type}
\end{describe}

\begin{describe}{cls}
    {simple-message (basic-message) \&key :name :location :class :type}
\end{describe}

\begin{describe}{cls}
    {basic-direct-method (sod-method)
      \&key :message :location :class :type :body :role}
\end{describe}

\begin{describe}{gf}{sod-method-role @<method> @> @<role>}
\end{describe}

\begin{describe}{cls}
    {daemon-direct-method (basic-direct-method) \\ \ind
      \&key :message :location :class :type :body :role}
\end{describe}

\begin{describe}{cls}
    {delegating-direct-method (basic-direct-method) \\ \ind
      \&key :message :location :class :type :body :role}
\end{describe}

\begin{describe}{cls}
    {basic-effective-method (effective-method) \\ \ind
      \&key :message :class :around-methods :before-methods :after-methods}
\end{describe}

\begin{describe*}
    {\dhead{gf}
       {effective-method-around-methods @<effective-method> @> @<list>}
     \dhead{gf}
       {effective-method-before-methods @<effective-method> @> @<list>}
     \dhead{gf}
       {effective-method-after-methods @<effective-method> @> @<list>}
     \dhead{gf}{effective-method-functions @<effective-method> @> @<list>}}
\end{describe*}

\begin{describe}{cls}
    {simple-effective-method (basic-effective-method) \\ \ind
      \&key :message :class
            :around-methods :before-methods :after-methods :primary-methods}
\end{describe}

\begin{describe}{fun}
    {basic-effective-method-body @<codegen> @<target> @<method> @<body>}
\end{describe}

\begin{describe}{cls}
    {standard-message (simple-message) \&key :name :location :class :type}
\end{describe}

\begin{describe}{cls}
    {standard-effective-method (simple-effective-method) \\ \ind
      \&key :message :class
            :around-methods :before-methods :after-methods :primary-methods}
\end{describe}

\begin{describe}{cls}
    {aggregating-message (simple-message)
      \&key :name :location :class :type :combination}
\end{describe}

\begin{describe}{gf}
    {aggregating-message-properties @<message> @<combination> @> @<plist>}
\end{describe}

\begin{describe}{gf}
    {compute-aggregating-message-kernel
      \=@<message> @<combination> @<target> \+ \\
        @<methods> @<arg-names> \&key}
\end{describe}

\begin{describe}{gf}
    {check-aggregating-message-type @<message> @<combination> @<c-type>}
\end{describe}

\begin{describe}{cls}
     {aggregating-effective-method (simple-effective-method) \\ \ind
      \&key :message :class
            :around-methods :before-methods :after-methods :primary-methods}
\end{describe}

\begin{describe}{mac}
    {define-aggregating-method-combination @<combination> \\ \ind\ind
        ((@<var-name>^*)
         @[[ :codegen @<codegen-var> @!
             :methods @<methods-var> @]]) \- \\
      @[[ \=:properties (@{ (@{ @<name> @! (@[@<keyword>@] @<name>) @}
                             @<c-type>
                             @[@<default>
                               @[@<suppliedp-var>@]@]) @}^*) @! \+ \\
            :return-type @<c-type> @! \\
            :around @<around-func> @!
            :first-method @<first-method-func> @!
            :method @<method-func> @]]}
\end{describe}

%%% the method combination story
%% compute-effective-methods --> compute-sod-effective-method

%% hook-output (basic-effective-method :c)
%%   basic-effective-method.functions
%%     compute-method-entry-functions
%%       compute-effective-method-body
%%
%% compute-effective-method-body (simple-effective-method)
%%   basic-effective-method-body
%%   simple-method-body (standard-effective-method)
%%   simple-method-body (aggregating-effective-method)
%%     message-kernel-function

%%%----- That's all, folks --------------------------------------------------

%%% Local variables:
%%% mode: LaTeX
%%% TeX-master: "sod.tex"
%%% TeX-PDF-mode: t
%%% End: