X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/blobdiff_plain/7292d6e1bc85cca454f64353722ba78a9263f257..d1b394fa5cde326c2635997ddb7cda27a52d537d:/doc/concepts.tex diff --git a/doc/concepts.tex b/doc/concepts.tex index 84e4062..b48746e 100644 --- a/doc/concepts.tex +++ b/doc/concepts.tex @@ -214,13 +214,13 @@ qualified by the defining class's nickname. \subsubsection{Slot initializers} As well as defining slot names and types, a class can also associate an \emph{initial value} with each slot defined by itself or one of its -subclasses. A class $C$ provides an \emph{initialization function} (see +subclasses. A class $C$ provides an \emph{initialization message} (see \xref{sec:concepts.lifecycle.birth}, and \xref{sec:structures.root.sodclass}) -which sets the slots of a \emph{direct} instance of the class to the correct -initial values. If several of $C$'s superclasses define initializers for the -same slot then the initializer from the most specific such class is used. If -none of $C$'s superclasses define an initializer for some slot then that slot -will be left uninitialized. +whose methods set the slots of a \emph{direct} instance of the class to the +correct initial values. If several of $C$'s superclasses define initializers +for the same slot then the initializer from the most specific such class is +used. If none of $C$'s superclasses define an initializer for some slot then +that slot will be left uninitialized. The initializer for a slot with scalar type may be any C expression. The initializer for a slot with aggregate type must contain only constant @@ -270,7 +270,10 @@ slots. If you want to hide implementation details, the best approach is to stash them in a dynamically allocated private structure, and leave a pointer 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. +\xref{sec:fixme.compatibility} for more details.) + +\subsubsection{Vtables} + \subsubsection{Class objects} In Sod's object system, classes are objects too. Therefore classes are @@ -288,8 +291,8 @@ doesn't define any messages, so it doesn't have any methods. In Sod, a class slot containing a function pointer is not at all the same thing as a method.) \subsubsection{Conversions} -Suppose one has a value of type pointer to class type of some class~$C$, and -wants to convert it to a pointer to class type of some other class~$B$. +Suppose one has a value of type pointer-to-class-type for some class~$C$, and +wants to convert it to a pointer-to-class-type for some other class~$B$. There are three main cases to distinguish. \begin{itemize} \item If $B$ is a superclass of~$C$, in the same chain, then the conversion @@ -305,13 +308,13 @@ There are three main cases to distinguish. pointer. The conversion can be performed using the appropriate generated upcast macro (see below); the general case is handled by the macro \descref{SOD_XCHAIN}{mac}. -\item If $B$ is a subclass of~$C$ then the conversion is an \emph{upcast}; +\item If $B$ is a subclass of~$C$ then the conversion is a \emph{downcast}; otherwise the conversion is a~\emph{cross-cast}. In either case, the conversion can fail: the object in question might not be an instance of~$B$ - at all. The macro \descref{SOD_CONVERT}{mac} and the function + after all. The macro \descref{SOD_CONVERT}{mac} and the function \descref{sod_convert}{fun} perform general conversions. They return a null pointer if the conversion fails. (There are therefore your analogue to the - \Cplusplus @|dynamic_cast<>| operator.) + \Cplusplus\ @|dynamic_cast<>| operator.) \end{itemize} The Sod translator generates macros for performing both in-chain and cross-chain upcasts. For each class~$C$, and each proper superclass~$B$ @@ -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} @@ -708,7 +741,11 @@ environment in which it operates. Details of initialization are necessarily class-specific, but typically it involves setting the instance's slots to appropriate values, and possibly -linking it into some larger data structure to keep track of it. +linking it into some larger data structure to keep track of it. It is +possible for initialization methods to attempt to allocate resources, but +this must be done carefully: there is currently no way to report an error +from object initialization, so the object must be marked as incompletely +initialized, and left in a state where it will be safe to tear down later. Initialization is performed by sending the imprinted instance an @|init| message, defined by the @|SodObject| class. This message uses a nonstandard @@ -807,9 +844,9 @@ allocated from the standard @|malloc| heap is done using the \descref{sod_destroy}[function]{fun}. \subsubsection{Teardown} -Details of initialization are necessarily class-specific, but typically it -involves setting the instance's slots to appropriate values, and possibly -linking it into some larger data structure to keep track of it. +Details of teardown are necessarily class-specific, but typically it +involves releasing resources held by the instance, and disentangling it from +any data structures it might be linked into. Teardown is performed by sending the instance the @|teardown| message, defined by the @|SodObject| class. The message returns an integer, used as a @@ -823,7 +860,7 @@ This simple protocol can be used, for example, to implement a reference counting system, as follows. \begin{prog} [nick = ref] \\ - class ReferenceCountedObject \{ \\ \ind + class ReferenceCountedObject: SodObject \{ \\ \ind unsigned nref = 1; \\- void inc() \{ me@->ref.nref++; \} \\- [role = around] \\ @@ -867,6 +904,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: