[sod] / doc / intro.tex

%%% -*-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 \man{lex}{1} or
  \man{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}

\subsection{Comparison with other object systems}

Sod's object system is significantly different in flavour\footnote{%
  The pun was unintentional, but I'm happy with it.} %
from most popular object-ish languages.  Indeed, it bears far more similarity
to Flavors, CLOS, and Dylan than to \Cplusplus, \Csharp, or Java (and still
less to Go or Rust).

Of the popular languages, \Cplusplus's object system is probably closest to
Sod.  Both are statically compiled, statically typed, implement single
dispatch, and have relatively simple runtime metaprogramming facilities.
\Cplusplus\ has a rich compile-time template metalanguage; Sod instead allows
compile-time metaprogramming in Common Lisp, which is probably less
convenient for simple cases but rather more pleasant for doing difficult
things.  Significantly, Sod has the @|SodObject| class, of which all other
classes\footnote{%
  Unless you construct a new root class of your own, which you can totally
  do, but it's hard work.} %
are subclasses; \Cplusplus\ has no such root class.

Both systems provide multiple inheritance, but go about it very differently.
The most important difference is that \Cplusplus\ provides only \emph{static
  delegation}: if you have a class @|B| which defines some (virtual) member
function @|f|, and a derived class of @|D| which wants to \emph{extend} the
behaviour of @|f| on instances of @|D|, then you must explicitly call @|B::f|
at the appropriate point:
\begin{prog}
  \#include <iostream>                                          \\+
                                                                %
  class B \{                                                    \\
  public:                                                       \\ \ind
    virtual void f() \{ std::cout <{}< "B@\\n"; \}              \\
    virtual @~B() \{ \}                                       \-\\
  \};                                                           \\+
                                                                %
  class D: public B \{                                          \\
  public:                                                       \\ \ind
    void f() \{ B::f(); std::cout <{}< "D too@\\n"; \}        \-\\
  \};
\end{prog}

This works adequately when only single inheritance is involved.  But if we
now introduce multiple inheritance, we see the problem.
\begin{prog}
  \#include <iostream>                                          \\+
                                                                %
  class B \{                                                    \\
  public:                                                       \\ \ind
    virtual void f() \{ std::cout <{}< "B@\\n"; \}              \\
    virtual @~B() \{ \}                                       \-\\
  \};                                                           \\+
                                                                %
  class X: virtual public B \{                                  \\
  public:                                                       \\ \ind
    void f() \{ B::f(); std::cout <{}< "X after@\\n"; \}      \-\\
  \};                                                           \\+
                                                                %
  class Y: virtual public B \{                                  \\
  public:                                                       \\ \ind
    void f() \{ std::cout <{}< "Y before@\\n"; B::f(); \}     \-\\
  \};                                                           \\+
                                                                %
  class D: public X, public Y \{                                \\
  public:                                                       \\ \ind
    void f() \{ X::f(); Y::f(); \} // \comment{oh, dear}      \-\\
  \};
\end{prog}
The above prints
\begin{prog}
  B                                                             \\
  X after                                                       \\
  Y before                                                      \\
  B
\end{prog}
which is unlikely to be what was wanted: `B' prints twice, and the `before'
and `after' actions are both in the middle.\footnote{%
  Of course, one could have arranged to call @|Y::f| before @|X::f| -- but
  the important point is that one would have needed to \emph{know} that this
  was necessary.} %
The problem is that correctly composing behaviour from a collection of
superclasses requires knowledge of all of the superclasses involved and how
they're supposed to work together.

The obvious workaround is to separate the functionality -- here, printing the
messages -- from the plumbing, which arranges to do everything in the right
order.  You'd end up with a @|_f| member function in each class which wanted
print something, and then every class would have a virtual @|f| which calls
the various @|_f| functions in the right order, like this:
\begin{prog}
  \#include <iostream>                                          \\+
                                                                %
  class B \{                                                    \\
  protected:                                                    \\ \ind
    void _f() \{ std::cout <{}< "B@\\n"; \}                   \-\\
  public:                                                       \\ \ind
    virtual void f() \{ _f(); \}                                \\
    virtual ~B() \{ \}                                        \-\\
  \};                                                           \\+
                                                                %
  class X: virtual public B \{                                  \\
  protected:                                                    \\ \ind
    void _f() \{ std::cout <{}< "X after@\\n"; \}             \-\\
  public:                                                       \\ \ind
    void f() \{ B::_f(); _f(); \}                             \-\\
  \};                                                           \\+
                                                                %
  class Y: virtual public B \{                                  \\
  protected:                                                    \\ \ind
    void _f() \{ std::cout <{}< "Y before@\\n"; \}            \-\\
  public:                                                       \\ \ind
    void f() \{ _f(); B::_f(); \}                             \-\\
  \};                                                           \\+
                                                                %
  class D: public X, public Y \{                                \\
  public:                                                       \\ \ind
    void f() \{ Y::_f(); B::_f(); X::_f(); \}                 \-\\
  \};
\end{prog}
This is clearly much more cumbersome.  Most disastrously, it spreads
knowledge about how the various classes' contributions to the behaviour of
@|f| fit together throughout the class graph.  Also, even this approach is
only suitable for especially simple cases.  Suppose @|Y| needed to add
behaviour before \emph{and} after @|B| -- maybe @|Y| is taking out a lock,
and then releasing it.  Then this approach won't work any more; indeed, it's
hard to see any way to make this work without spreading knowledge about
@|Y|'s lock everywhere.

Compare Sod's approach.
\begin{prog}
  code c: includes \{                                           \\
  \#include <stdio.h>                                           \\-
  \#include <sod.h>                                             \\
  \#include "foo.h"                                             \\
  \}                                                            \\+
                                                                %
  class B: SodObject \{                                         \\ \ind
    void f() \{ puts("B"); \}                                 \-\\
  \}                                                            \\+
                                                                %
  class X: B \{                                                 \\ \ind
    void b.f() \{ CALL_NEXT_METHOD; puts("X after"); \}       \-\\
  \}                                                            \\
                                                                %
  class Y: B \{                                                 \\ \ind
    void b.f() \{ puts("Y before"); CALL_NEXT_METHOD; \}      \-\\
  \}                                                            \\+
                                                                %
  class D: X, Y \{ \}
\end{prog}
This prints
\begin{prog}
  Y before                                                      \\
  B                                                             \\
  X after
\end{prog}
as (I think) you'd hope.  @|CALL_NEXT_METHOD| here does the job of figuring
out what to do next, according to some rather complicated rules
(described in full in \xref{sec:concepts.methods.combination}).

Indeed, there's an even better way to write this particular case with Sod,
because Sod has dedicated \emph{method rôles}.
\begin{prog}
  code c: includes \{                                           \\
  \#include <stdio.h>                                           \\-
  \#include <sod.h>                                             \\
  \#include "foo.h"                                             \\
  \}                                                            \\+
                                                                %
  class B: SodObject \{                                         \\ \ind
    void f() \{ puts("B"); \}                                 \-\\
  \}                                                            \\+
                                                                %
  class X: B \{                                                 \\ \ind
    [role = after] void b.f() \{ puts("X after"); \}          \-\\
  \}                                                            \\
                                                                %
  class Y: B \{                                                 \\ \ind
    [role = before] void b.f() \{ puts("Y before"); \}        \-\\
  \}                                                            \\+
                                                                %
  class D: X, Y \{ \}
\end{prog}

%%%--------------------------------------------------------------------------
\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:
Commit	Line	Data
caa6f4b9 MW	1	%%% --latex--
	2	%%%
	3	%%% Introduction to Sod and its object system
	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{Introduction} \label{ch:intro}
	27
	28	Sod is an object system for the C programming language.
	29
	30	The software distribution for Sod contains two main parts:
	31	\begin{itemize}
cafa747a MW	32	\item a translator, or preprocessor, similar in spirit to \man{lex}{1} or
	33	\man{yacc}{1}, which reads input files containing class definitions, and
	34	writes C source code and header files; and
caa6f4b9 MW	35	\item a very small runtime library, containing the built-in base classes and
	36	some simple utility macros and functions for working with instances and
	37	classes.
	38	\end{itemize}
	39
	40	%%%--------------------------------------------------------------------------
	41	\section{About Sod's object system} \label{ch:intro.about}
	42
	43	Sod implements a fairly sophisticated object system, with multiple
	44	inheritance, but only single dispatch.
	45
	46	\subsection{Ideology}
	47
	48	Object systems tend to come with ideology attached, so Sod is no exception;
	49	but Sod's ideology is different from that of most object systems.
	50	\begin{itemize}
	51	\item Sod provides an object system, not a module system. Sod provides no
	52	facilities for `information hiding'; there is no equivalent to the
	53	@\|private\| or @\|protected\| annotations in Java or \Cplusplus. The author
	54	takes the view (a) that such facilities are propertly part of a module
	55	system, and that trying to abuse classes so that they become modules is a
	56	mistake; and (b) that much useful functionality is unnecessarily hidden
	57	away behind abstract interfaces, and a gentle-ish nudge towards greater
	58	openness is called for.
	59	\item Sod's objective is to provide an effective tool for the expert
	60	programmer, in the classic `make easy things simple and, difficult things
	61	possible' mould. It isn't intended to be useful in an environment
	62	containing unassisted novice programmers. Sod tries to avoid placing
	63	technically unnecessary restrictions on programmers, and is likely to
	64	evolve in the direction of eliminating existing restrictions rather than
	65	growing new `safety' features.
	66	\end{itemize}
	67
ca8f5d55 MW	68	\subsection{Comparison with other object systems}
	69
	70	Sod's object system is significantly different in flavour\footnote{%
	71	The pun was unintentional, but I'm happy with it.} %
	72	from most popular object-ish languages. Indeed, it bears far more similarity
	73	to Flavors, CLOS, and Dylan than to \Cplusplus, \Csharp, or Java (and still
	74	less to Go or Rust).
	75
	76	Of the popular languages, \Cplusplus's object system is probably closest to
	77	Sod. Both are statically compiled, statically typed, implement single
	78	dispatch, and have relatively simple runtime metaprogramming facilities.
	79	\Cplusplus\ has a rich compile-time template metalanguage; Sod instead allows
	80	compile-time metaprogramming in Common Lisp, which is probably less
	81	convenient for simple cases but rather more pleasant for doing difficult
	82	things. Significantly, Sod has the @\|SodObject\| class, of which all other
	83	classes\footnote{%
	84	Unless you construct a new root class of your own, which you can totally
	85	do, but it's hard work.} %
	86	are subclasses; \Cplusplus\ has no such root class.
	87
	88	Both systems provide multiple inheritance, but go about it very differently.
	89	The most important difference is that \Cplusplus\ provides only \emph{static
	90	delegation}: if you have a class @\|B\| which defines some (virtual) member
	91	function @\|f\|, and a derived class of @\|D\| which wants to \emph{extend} the
	92	behaviour of @\|f\| on instances of @\|D\|, then you must explicitly call @\|B::f\|
	93	at the appropriate point:
	94	\begin{prog}
	95	\#include <iostream> \\+
	96	%
	97	class B \{ \\
	98	public: \\ \ind
	99	virtual void f() \{ std::cout <{}< "B@\\n"; \} \\
	100	virtual @~B() \{ \} \-\\
	101	\}; \\+
	102	%
	103	class D: public B \{ \\
	104	public: \\ \ind
	105	void f() \{ B::f(); std::cout <{}< "D too@\\n"; \} \-\\
	106	\};
	107	\end{prog}
	108
	109	This works adequately when only single inheritance is involved. But if we
	110	now introduce multiple inheritance, we see the problem.
	111	\begin{prog}
	112	\#include <iostream> \\+
	113	%
	114	class B \{ \\
	115	public: \\ \ind
	116	virtual void f() \{ std::cout <{}< "B@\\n"; \} \\
	117	virtual @~B() \{ \} \-\\
	118	\}; \\+
	119	%
	120	class X: virtual public B \{ \\
	121	public: \\ \ind
	122	void f() \{ B::f(); std::cout <{}< "X after@\\n"; \} \-\\
	123	\}; \\+
	124	%
	125	class Y: virtual public B \{ \\
	126	public: \\ \ind
	127	void f() \{ std::cout <{}< "Y before@\\n"; B::f(); \} \-\\
	128	\}; \\+
	129	%
	130	class D: public X, public Y \{ \\
	131	public: \\ \ind
132	void f() \{ X::f(); Y::f(); \} // \comment{oh, dear} \-\\
133	\};
134	\end{prog}
135	The above prints
136	\begin{prog}
137	B \\
138	X after \\
139	Y before \\
140	B
141	\end{prog}
142	which is unlikely to be what was wanted: `B' prints twice, and the `before'
143	and `after' actions are both in the middle.\footnote{%
144	Of course, one could have arranged to call @\|Y::f\| before @\|X::f\| -- but
145	the important point is that one would have needed to \emph{know} that this
146	was necessary.} %
147	The problem is that correctly composing behaviour from a collection of
148	superclasses requires knowledge of all of the superclasses involved and how
149	they're supposed to work together.
150
151	The obvious workaround is to separate the functionality -- here, printing the
152	messages -- from the plumbing, which arranges to do everything in the right
153	order. You'd end up with a @\|_f\| member function in each class which wanted
154	print something, and then every class would have a virtual @\|f\| which calls
155	the various @\|_f\| functions in the right order, like this:
156	\begin{prog}
157	\#include <iostream> \\+
158	%
159	class B \{ \\
160	protected: \\ \ind
161	void _f() \{ std::cout <{}< "B@\\n"; \} \-\\
162	public: \\ \ind
163	virtual void f() \{ _f(); \} \\
164	virtual ~B() \{ \} \-\\
165	\}; \\+
166	%
167	class X: virtual public B \{ \\
168	protected: \\ \ind
169	void _f() \{ std::cout <{}< "X after@\\n"; \} \-\\
170	public: \\ \ind
171	void f() \{ B::_f(); _f(); \} \-\\
172	\}; \\+
173	%
174	class Y: virtual public B \{ \\
175	protected: \\ \ind
176	void _f() \{ std::cout <{}< "Y before@\\n"; \} \-\\
177	public: \\ \ind
178	void f() \{ _f(); B::_f(); \} \-\\
179	\}; \\+
180	%
181	class D: public X, public Y \{ \\
182	public: \\ \ind
183	void f() \{ Y::_f(); B::_f(); X::_f(); \} \-\\
184	\};
185	\end{prog}
186	This is clearly much more cumbersome. Most disastrously, it spreads
187	knowledge about how the various classes' contributions to the behaviour of
188	@\|f\| fit together throughout the class graph. Also, even this approach is
189	only suitable for especially simple cases. Suppose @\|Y\| needed to add
190	behaviour before \emph{and} after @\|B\| -- maybe @\|Y\| is taking out a lock,
191	and then releasing it. Then this approach won't work any more; indeed, it's
192	hard to see any way to make this work without spreading knowledge about
193	@\|Y\|'s lock everywhere.
194
195	Compare Sod's approach.
196	\begin{prog}
197	code c: includes \{ \\
198	\#include <stdio.h> \\-
199	\#include <sod.h> \\
200	\#include "foo.h" \\
201	\} \\+
202	%
203	class B: SodObject \{ \\ \ind
204	void f() \{ puts("B"); \} \-\\
205	\} \\+
206	%
207	class X: B \{ \\ \ind
208	void b.f() \{ CALL_NEXT_METHOD; puts("X after"); \} \-\\
209	\} \\
210	%
211	class Y: B \{ \\ \ind
212	void b.f() \{ puts("Y before"); CALL_NEXT_METHOD; \} \-\\
213	\} \\+
214	%
215	class D: X, Y \{ \}
216	\end{prog}
217	This prints
218	\begin{prog}
219	Y before \\
220	B \\
221	X after
222	\end{prog}
223	as (I think) you'd hope. @\|CALL_NEXT_METHOD\| here does the job of figuring
224	out what to do next, according to some rather complicated rules
225	(described in full in \xref{sec:concepts.methods.combination}).
226
227	Indeed, there's an even better way to write this particular case with Sod,
228	because Sod has dedicated \emph{method rôles}.
229	\begin{prog}
230	code c: includes \{ \\
231	\#include <stdio.h> \\-
232	\#include <sod.h> \\
233	\#include "foo.h" \\
234	\} \\+
235	%
236	class B: SodObject \{ \\ \ind
237	void f() \{ puts("B"); \} \-\\
238	\} \\+
239	%
240	class X: B \{ \\ \ind
241	[role = after] void b.f() \{ puts("X after"); \} \-\\
242	\} \\
243	%
244	class Y: B \{ \\ \ind
245	[role = before] void b.f() \{ puts("Y before"); \} \-\\
246	\} \\+
247	%
248	class D: X, Y \{ \}
249	\end{prog}
250
caa6f4b9 MW	251	%%%--------------------------------------------------------------------------
	252	\section{About this manual}
	253
	254	This manual intends to provide complete documentation about Sod.
	255
	256	%%%----- That's all, folks --------------------------------------------------
	257
	258	%%% Local variables:
	259	%%% mode: LaTeX
	260	%%% TeX-master: "sod.tex"
	261	%%% TeX-PDF-mode: t
	262	%%% End: