X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/27ec3825bd945bcdae0dca8ab2b4475c4722b313..fa388683c9116be05ee1778150fd550fd2366a6e:/doc/structures.tex diff --git a/doc/structures.tex b/doc/structures.tex index c31503e..c8a0d9c 100644 --- a/doc/structures.tex +++ b/doc/structures.tex @@ -46,8 +46,8 @@ Instance chains contain slots and vtable pointers, as described below. All instances have the basic structure of a @|struct sod_instance|. \begin{describe}[struct sod_instance]{type} - {struct sod_instance \{ \\ \ind - const struct sod_vtable *_vt; \- \\ + {struct sod_instance \{ \\ \ind + const struct sod_vtable *_vt; \-\\ \};} The basic structure of all instances. Members are as follows. @@ -58,9 +58,9 @@ instances have the basic structure of a @|struct sod_instance|. \end{describe} \begin{describe}[struct sod_vtable]{type} - {struct sod_vtable \{ \\ \ind - const SodClass *_class; \\ - size_t _base; \- \\ + {struct sod_vtable \{ \\ \ind + const SodClass *_class; \\ + size_t _base; \-\\ \};} A vtable contains static metadata needed for efficient conversions and @@ -93,33 +93,35 @@ recommended. \begin{figure}[tbp] \begin{tabular}{p{10pt}p{10pt}} \begin{nprog} - struct SodObject__ilayout \{ \\ \ind - union \{ \\ \ind - struct SodObject__ichain_obj \{ \\ \ind - const struct SodObject__vt_obj *_vt; \- \\ - \} obj; \- \\ - \} obj; \- \\ + struct SodObject__ilayout \{ \\ \ind + union \{ \\ \ind + struct SodObject__ichain_obj \{ \\ \ind + const struct SodObject__vt_obj *_vt; \-\\ + \} obj; \-\\ + \} obj; \-\\ \}; \end{nprog} & \begin{nprog} - struct SodObject__vt_obj \{ \\ \ind - const SodClass *_class; \\ - size_t _base; \\ - struct SodObject__vtmsgs_obj \{ \\ \ind - void (*init)(SodObject *me, ...); \\ - void (*init__v)(SodObject *me, va_list); \- \\ - \} obj; \- \\ + struct SodObject__vt_obj \{ \\ \ind + const SodClass *_class; \\ + size_t _base; \\ + struct SodObject__vtmsgs_obj \{ \\ \ind + void (*init)(SodObject *me, ...); \\ + void (*init__v)(SodObject *me, va_list); \\ + int (*teardown)(SodObject *me); \-\\ + \} obj; \-\\ \}; - \end{nprog} \\ + \end{nprog} \\ \end{tabular} \caption{Instance and vtable layout of @|SodObject|} \label{fig:structures.root.sodobject} \end{figure} \begin{describe}[SodObject]{cls} - {[nick = obj, metaclass = SodClass, lisp_metaclass = sod_class] \\ - class SodObject \{ \\ \ind + {[nick = obj, metaclass = SodClass, + lisp_metaclass = sod_class] \\ + class SodObject \{ \\ \ind void init(?); \}} @@ -135,7 +137,7 @@ recommended. The instance and vtable layout of @|SodObject| is shown in \xref{fig:structures.root.sodobject}. - The following message is defined. + The following messages are defined. \begin{describe}[obj.init]{msg}{void init(?);} Initialize a newly allocated instance. @@ -147,15 +149,16 @@ recommended. method calls on its @|next_method| function more than once. This default behaviour is to initialize the instance's slots using the - defined slot initializers: each slot is initialized using the most - specific applicable initializer, if any. Slots without an initializer - are left uninitialized. + defined slot initializers, and execute the initialization fragments. + Each slot is initialized using the most specific applicable initializer, + if any. Slots without an initializer are left uninitialized. - Slots are initialized in reverse-precedence order of their defining - classes; i.e., slots defined by a less specific superclass are - initialized earlier than slots defined by a more specific superclass. - Slots defined by the same class are initialized in the order in which - they appear in the class definition. + Slots are initialized and initialization fragments executed together, a + superclass at a time: first, the superclass's slots are initialized (if + any); then the superclass's initialization fragments (if any) are + executed, starting with the least specific superclass first. Slots and + initialization fragments defined by the same class are processed in the + order in which they appear in the class definition. There are no standard keyword arguments; methods on subclasses are free to introduce their own in the usual way. @@ -167,29 +170,54 @@ recommended. For more details on instance construction, see \xref{sec:concepts.lifecycle.birth}. \end{describe} + + \begin{describe}[obj.teardown]{msg}{int teardown();} + Teardown an instance which is no longer required. + + The message returns an integer flag. A zero value means that the + instance is safe to deallocate. A nonzero value means that the instance + should not be deallocated, and that it is safe for the caller to simply + forget about it. This simple protocol may be used, for example, to + implement a reference-counting system. + + This message uses a custom method combination which works like the + standard method combination except that default behaviour is invoked if + no primary or around method overrides. + + This default behaviour is to execute each superclass's teardown + fragments, most specific first, and then return zero to indicate that the + object is ready for deallocation. Teardown fragments defined by the same + class are processed in the order in which they appear in the class + definition. + + It is usual to provide complex teardown behaviour as @|before| methods. + Logic to decide whether to allow deallocation is usually implemented as + @|around| methods. + \end{describe} \end{describe} \subsection{The SodClass class} \label{sec:structures.root.sodclass} \begin{describe}[SodClass]{cls} - {[nick = cls, link = SodObject] \\ - class SodClass : SodObject \{ \\ \ind - const char *name; \\ - const char *nick; \\ - size_t initsz; \\ - void *(*imprint)(void *@
); \\ - size_t n_supers; \\ - const SodClass *const *supers; \\ - size_t n_cpl; \\ - const SodClass *const *cpl; \\ - const SodClass *link; \\ - const SodClass *head; \\ - size_t level; \\ - size_t n_chains; \\ - const struct sod_chain *chains; \\ - size_t off_islots; \\ - size_t islotsz; \- \\ + {[nick = cls, link = SodObject] \\ + class SodClass : SodObject \{ \\ \ind + const char *name; \\ + const char *nick; \\ + size_t initsz; \\ + size_t align; \\ + void *(*imprint)(void *@
); \\ + size_t n_supers; \\ + const SodClass *const *supers; \\ + size_t n_cpl; \\ + const SodClass *const *cpl; \\ + const SodClass *link; \\ + const SodClass *head; \\ + size_t level; \\ + size_t n_chains; \\ + const struct sod_chain *chains; \\ + size_t off_islots; \\ + size_t islotsz; \-\\ \}} The @|SodClass| class defines no additional messages , but there are a @@ -205,6 +233,8 @@ recommended. \item[initsz] The size in bytes required to store an instance of the class. + \item[align] A sufficient alignment for the class's instance storage. + \item[imprint] A pointer to a function: given a pointer @
to at least
@