the private structure can grow more members as needed. See
\xref{sec:fixme.compatibility} for more details.
+\subsubsection{Vtables}
+
+
\subsubsection{Class objects}
In Sod's object system, classes are objects too. Therefore classes are
themselves instances; the class of a class is called a \emph{metaclass}. The
in \xref{sec:fixme.custom-aggregating-method-combination}.
+\subsection{Sending messages in C} \label{sec:concepts.methods.c}
+
+Each instance is associated with its direct class [FIXME]
+
+The effective methods for each class are determined at translation time, by
+the Sod translator. For each effective method, one or more \emph{method
+entry functions} are constructed. A method entry function has three
+responsibilities.
+\begin{itemize}
+\item It converts the receiver pointer to the correct type. Method entry
+ functions can perform these conversions extremely efficiently: there are
+ separate method entries for each chain of each class which can receive a
+ message, so method entry functions are in the privileged situation of
+ knowing the \emph{exact} class of the receiving object.
+\item If the message accepts a variable-length argument tail, then two method
+ entry functions are created for each chain of each class: one receives a
+ variable-length argument tail, as intended, and captures it in a @|va_list|
+ object; the other accepts an argument of type @|va_list| in place of the
+ variable-length tail and arranges for it to be passed along to the direct
+ methods.
+\item It invokes the effective method with the appropriate arguments. There
+ might or might not be an actual function corresponding to the effective
+ method itself: the translator may instead open-code the effective method's
+ behaviour into each method entry function; and the machinery for handling
+ `delegation chains', such as is used for @|around| methods and primary
+ methods in the standard method combination, is necessarily scattered among
+ a number of small functions.
+\end{itemize}
+
+
\subsection{Messages with keyword arguments}
\label{sec:concepts.methods.keywords}
%%%--------------------------------------------------------------------------
\section{Metaclasses} \label{sec:concepts.metaclasses}
+%%%--------------------------------------------------------------------------
+\section{Compatibility considerations} \label{sec:concepts.compatibility}
+
+Sod doesn't make source-level compatibility especially difficult. As long as
+classes, slots, and messages don't change names or dissappear, and slots and
+messages retain their approximate types, everything will be fine.
+
+Binary compatibility is much more difficult. Unfortunately, Sod classes have
+rather fragile binary interfaces.\footnote{%
+ Research suggestion: investigate alternative instance and vtable layouts
+ which improve binary compatibility, probably at the expense of instance
+ compactness, and efficiency of slot access and message sending. There may
+ be interesting trade-offs to be made.} %
+
+If instances are allocated [FIXME]
+
%%%----- That's all, folks --------------------------------------------------
%%% Local variables:
--- /dev/null
+%%% -*-latex-*-
+%%%
+%%% Introduction to Sod and its object system
+%%%
+%%% (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{Introduction} \label{ch:intro}
+
+Sod is an object system for the C programming language.
+
+The software distribution for Sod contains two main parts:
+\begin{itemize}
+\item a translator, or preprocessor, similar in spirit to \manpage{lex}{1} or
+ \manpage{yacc}{1}, which reads input files containing class definitions,
+ and writes C source code and header files; and
+\item a very small runtime library, containing the built-in base classes and
+ some simple utility macros and functions for working with instances and
+ classes.
+\end{itemize}
+
+%%%--------------------------------------------------------------------------
+\section{About Sod's object system} \label{ch:intro.about}
+
+Sod implements a fairly sophisticated object system, with multiple
+inheritance, but only single dispatch.
+
+\subsection{Ideology}
+
+Object systems tend to come with ideology attached, so Sod is no exception;
+but Sod's ideology is different from that of most object systems.
+\begin{itemize}
+\item Sod provides an object system, not a module system. Sod provides no
+ facilities for `information hiding'; there is no equivalent to the
+ @|private| or @|protected| annotations in Java or \Cplusplus. The author
+ takes the view (a) that such facilities are propertly part of a module
+ system, and that trying to abuse classes so that they become modules is a
+ mistake; and (b) that much useful functionality is unnecessarily hidden
+ away behind abstract interfaces, and a gentle-ish nudge towards greater
+ openness is called for.
+\item Sod's objective is to provide an effective tool for the expert
+ programmer, in the classic `make easy things simple and, difficult things
+ possible' mould. It isn't intended to be useful in an environment
+ containing unassisted novice programmers. Sod tries to avoid placing
+ technically unnecessary restrictions on programmers, and is likely to
+ evolve in the direction of eliminating existing restrictions rather than
+ growing new `safety' features.
+\end{itemize}
+
+%%%--------------------------------------------------------------------------
+\section{About this manual}
+
+This manual intends to provide complete documentation about Sod.
+
+%%%----- That's all, folks --------------------------------------------------
+
+%%% Local variables:
+%%% mode: LaTeX
+%%% TeX-master: "sod.tex"
+%%% TeX-PDF-mode: t
+%%% End:
~mdw / sod / commitdiff