From caa6f4b99a79f95d15a6cc1e5b8dd27ea48b4d03 Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Mon, 14 Dec 2015 17:51:53 +0000 Subject: [PATCH] doc/: Work in progress. Organization: Straylight/Edgeware From: Mark Wooding --- doc/concepts.tex | 49 ++++++++++++++++++++++++++++++ doc/intro.tex | 79 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 doc/intro.tex diff --git a/doc/concepts.tex b/doc/concepts.tex index 84e4062..8067739 100644 --- a/doc/concepts.tex +++ b/doc/concepts.tex @@ -272,6 +272,9 @@ to it in a slot. (This will also help preserve binary compatibility, because 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 @@ -585,6 +588,36 @@ There is also a @|custom| aggregating method combination, which is described 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} @@ -867,6 +900,22 @@ determined using the \descref{SOD_INSTBASE}[macro]{mac}. %%%-------------------------------------------------------------------------- \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: diff --git a/doc/intro.tex b/doc/intro.tex new file mode 100644 index 0000000..d509925 --- /dev/null +++ b/doc/intro.tex @@ -0,0 +1,79 @@ +%%% -*-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]