.\" 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.
+.\" it under the terms of the GNU Library 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.
+.\" GNU Library 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.
+.\" You should have received a copy of the GNU Library 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.
.
.\" Highlight using terminal escapes, rather than overstriking.
.\"\X'tty: sgr 1'
.IB chead ,
.BI "const void *" obj );
.br
-.B SOD_CAR(\c
-.IB arg ,
-.RB ... );
+.B void *\c
+.B SOD_INSTBASE(\c
+.BI "const " cls " *" obj );
.PP
.B const void *\c
.B SOD_CLASSOF(\c
.BI "const " cls " *" obj );
.br
-.B void *\c
-.B SOD_INSTBASE(\c
-.BI "const " cls " *" obj );
-.br
+.B int
+.B sod_subclassp(\c
+.BI "const SodClass *" sub ,
+.BI "const SodClass *" super );
+.PP
.IB cls " *" \c
.B SOD_CONVERT(\c
.IB cls ,
.BI "const void *" obj );
.br
+.B int
+.B sod_convert(\c
+.BI "const SodClass *" cls ,
+.BI "const void *" obj );
+.PP
+.IB cls " *" \c
+.B SOD_INIT(\c
+.IB cls ,
+.BI "void *" p ,
+.IB keywords );
+.br
+.B void *\c
+.B sod_init(\c
+.BI "const SodClass *" cls ,
+.BI "void *" p ,
+.B ...);
+.br
+.B void *\c
+.B sod_initv(\c
+.BI "const SodClass *" cls ,
+.BI "void *" p ,
+.BI "va_list " ap );
+.br
+.B void
+.B sod_teardown(\c
+.BI "void *" p );
+.br
.B SOD_DECL(\c
.IB cls ,
.IB var );
-.PP
-.B int
-.B sod_subclassp(\c
-.BI "const SodClass *" sub ,
-.BI "const SodClass *" super );
.br
-.B int
-.B sod_convert(\c
+.IB cls " *" \c
+.B SOD_MAKE(\c
+.IB cls ,
+.IB keywords );
+.br
+.B void *\c
+.B sod_make(\c
.BI "const SodClass *" cls ,
-.BI "const void *" obj );
+.B ...);
+.br
+.B void *\c
+.B sod_makev(\c
+.BI "const SodClass *" cls ,
+.BI "va_list " ap );
+.br
+.B int
+.B sod_destroy(\c
+.BI "void *" p );
+.PP
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
root object.
While the translator can (at some effort) support alternative roots,
they will require different run-time support machinery.
+.PP
+Some of Sod's macros include runtime checking by default.
+This checking can be disabled if you value performance
+more than early diagnosis of problems.
+Define
+.B SOD_RECKLESS
+to a nonzero value
+before including
+.B <sod/sod.h>
+to inhibit the runtime checking.
.
-.SS Infrastructure macros
-These macros are mostly intended for use in code
-generated by the Sod translator.
+.SS Layout utilities
+The following macros are useful in
+finding one's way around an instance layout structure,
+given various levels of information about
+what kind of object one is dealing with,
+or for computing the tables which are used for
+this kind of navigation.
+.PP
+These macros are mostly intended for use in
+code generated by the Sod translator.
Others may find them useful for special effects,
but they can be tricky to understand and use correctly
and can't really be recommended for general use.
.PP
The
-.B SOD_XCHAIN
-macro performs a `cross-chain upcast'.
-Given a pointer
-.I cls
-.BI * obj
-to an instance of a class of type
-.I cls
-and the nickname
-.I chead
-of the least specific class in one of
-.IR cls 's
-superclass chains which does not contain
-.I cls
-itself,
-.B SOD_XCHAIN(\c
-.IB chead ,
-.IB obj )
-returns the address of that chain's storage
-within the instance layout as a raw
-.B void *
-pointer.
-(Note that
-.I cls
-is not mentioned explicitly.)
-This macro is used by the generated
-.IB CLASS __CONV_ CLS
-conversion macros,
-which you are encouraged to use instead where possible.
-.PP
-The
.B SOD_OFFSETDIFF
macro returns the signed offset between
two members of a structure or union type.
macro (described below) is more suited to general use.
.PP
The
-.B SOD_CAR
-macro accepts one or more arguments
-and expands to just its first argument,
-discarding the others.
-It is only defined if the C implementation
-advertises support for C99.
-It is used in the definitions of message convenience macros
-for messages which accept a variable number of arguments
-but no required arguments,
-and is exported because the author has found such a thing useful in
-other contexts.
+.B SOD_INSTBASE
+macro finds the base address of an instance's layout.
+Given a pointer
+.BI "const " cls " *" obj
+to an instance,
+.BI SOD_INSTBASE( obj )
+returns the base address of the storage allocated to
+.IR obj .
+This is useful if you want to free a dynamically allocated instance,
+for example.
+This macro needs to look up an offset in
+.IR obj 's
+vtable to do its work.
+Compare
+.B SOD_ILAYOUT
+above,
+which is faster but requires
+precise knowledge of the instance's dynamic class.
.
-.SS Utility macros
-The following macros are expected to be useful
-in Sod method definitions and client code.
+.SS Classes
+The following macros and functions
+query the runtime relationhips between
+instances and classes.
.PP
The
.B SOD_CLASSOF
.IB cls __class \fR.)
.PP
The
-.B SOD_INSTBASE
-macro finds the base address of an instance's layout.
+.B sod_subclassp
+function answers whether one class
+.I sub
+is actually a subclass of another class
+.IR super .
+.B sod_subclassp(\c
+.IB sub ,
+.IB super )
+returns nonzero if and only if
+.I sub
+is a subclass of
+.IR super .
+This involves a run-time trawl through the class structures:
+while some effort has been made to make it perform well
+it's still not very fast.
+.
+.SS Conversions
+The following macros and functions are used
+to convert instance pointers of some (static) type
+into instance pointers of other static types
+to the same instance.
+.PP
+The
+.B SOD_XCHAIN
+macro performs a `cross-chain upcast'.
Given a pointer
-.BI "const " cls " *" obj
-to an instance,
-.BI SOD_INSTBASE( obj )
-returns the base address of the storage allocated to
-.IR obj .
-This is useful if you want to free a dynamically allocated instance,
-for example.
-This macro needs to look up an offset in
-.IR obj 's
-vtable to do its work.
-Compare
-.B SOD_ILAYOUT
-above,
-which is faster but requires
-precise knowledge of the instance's dynamic class.
+.I cls
+.BI * obj
+to an instance of a class of type
+.I cls
+and the nickname
+.I chead
+of the least specific class in one of
+.IR cls 's
+superclass chains which does not contain
+.I cls
+itself,
+.B SOD_XCHAIN(\c
+.IB chead ,
+.IB obj )
+returns the address of that chain's storage
+within the instance layout as a raw
+.B void *
+pointer.
+(Note that
+.I cls
+is not mentioned explicitly.)
+This macro is used by the generated
+.IB cls __CONV_ c
+conversion macros,
+which you are encouraged to use instead where possible.
.PP
The
.B SOD_CONVERT
-macro performs general conversions
+macro
+and
+.B sod_convert
+function
+perform general conversions
(up-, down-, and cross-casts) on instance pointers.
-Given a class name
+Given a class
.I cls
and a pointer
.BI "const void *" obj
to an instance,
-.B SOD_CONVERT(\c
-.IB cls ,
-.IB obj )
-returns an appropriately converted pointer to
+they return an appropriately converted pointer to
.I obj
if
.I obj
is indeed an instance of (some subclass of)
.IR cls ;
-otherwise it returns a null pointer.
-This macro is a simple wrapper around the
+otherwise they return a null pointer.
+.PP
+The
+.B SOD_CONVERT
+macro expects
+.I cls
+to be a class name;
+the
+.B sod_convert
+function
+expects a pointer to a class object instead.
+.PP
+This involves a run-time trawl through the class structures:
+while some effort has been made to make it perform well
+it's still not very fast.
+For upcasts (where
+.I cls
+is a superclass of the static type of
+.IR obj )
+the automatically defined conversion macros should be used instead,
+because they're much faster and can't fail.
+.PP
+When the target class is known statically,
+it's slightly more convenient to use the
+.B SOD_CONVERT
+macro rather than the
.B sod_convert
-function described below,
-which is useful in the common case that
-the target class is known statically.
+function,
+since the class object name is longer and uglier,
+and the macro returns a pointer of the correct type.
+.
+.SS Instance lifecycle
+The following macros and functions
+manage the standard steps along
+an instance's lifecycle.
+.PP
+The
+.B SOD_INIT
+macro,
+and the
+.B sod_init
+and
+.B sod_initv
+functions,
+imprint and initialize an instance of a class
+.I cls
+in the storage starting at address
+.IR p .
+.PP
+The direct class for the new instance is specified as
+a class name to
+.BR SOD_INIT ,
+or a pointer to a class object to the functions.
+.PP
+Keyword arguments for the initialization message may be provided.
+The
+.B SOD_INIT
+macro expects a single preprocessor-time argument
+which is a use of one of
+.B KWARGS
+or
+.B NO_KWARGS
+(see
+.BR keyword (3));
+the
+.B sod_init
+function expects the keywords as
+a variable-length argument tail;
+and
+.B sod_initv
+expects the keywords to be passed indirectly,
+through the captured argument-tail cursor
+.IR ap .
+.PP
+The return value is an instance pointer for the class
+.IR cls ;
+the
+.B SOD_INIT
+macro will have converted it to the correct type,
+so it should probably be used where possible.
+In fact, this is guaranteed to be equal to
+.I p
+by the layout rules described in
+.BR sod-structs (3).
+.PP
+The
+.B sod_teardown
+function tears down an instance of a class,
+releasing any resources it holds.
+.PP
+This function is a very thin wrapper around sending the
+.B obj.teardown
+message.
+It 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.
+(For example, the object may maintain a reference count,
+and knows that other references remain active.)
.PP
The
.B SOD_DECL
The instance has automatic storage duration:
pointers to it will become invalid when control
exits the scope of the declaration.
-.
-.SS Functions
-The following functions are provided.
+.PP
+Keyword arguments for the initialization message may be provided.
+The macro expects a single preprocessor-time argument
+which is a use of one of
+.B KWARGS
+or
+.B NO_KWARGS
+(see
+.BR keyword (3)).
+.PP
+The instance has automatic storage duration:
+pointers to it will become invalid
+when control exits the scope of the declaration.
+If necessary,
+the instance should be torn down before this happens,
+using the
+.B sod_teardown
+function.
+It may be appropriate to
+.BR assert (3)
+that the object is ready for deallocation at this time.
+.PP
+By default, this macro will abort the program
+if the size allocated for the instance doesn't match
+the size required by the class object;
+set
+.B SOD_RECKLESS
+to inhibit this check.
.PP
The
-.B sod_subclassp
-function answers whether one class
-.I sub
-is actually a subclass of another class
-.IR super .
-.B sod_subclassp(\c
-.IB sub ,
-.IB super )
-returns nonzero if and only if
-.I sub
-is a subclass of
-.IR super .
-This involves a run-time trawl through the class structures:
-while some effort has been made to make it perform well
-it's still not very fast.
+.B SOD_MAKE
+macro,
+and the
+.B sod_make
+and
+.B sod_makev
+functions,
+construct and return a pointer to a new instance of a class.
+.PP
+The direct class for the new instance is specified as a class name to
+.BR SOD_MAKE ,
+or as a class object to the functions.
.PP
+Keyword arguments for the initialization message may be provided.
The
-.B sod_convert
-function performs general conversions
-(up-, down-, and cross-casts) on instance pointers.
-Given a class pointer
-.I cls
-and an instance pointer
-.IR obj ,
-.B sod_convert(\c
-.IB cls ,
-.IB obj )
-returns an appropriately converted pointer to
-.I obj
-in the case that
-.I obj
-is an instance of (some subclass of)
+.B SOD_MAKE
+macro expects a single preprocessor-time argument
+which is a use of one of
+.B KWARGS
+or
+.B NO_KWARGS
+(see
+.BR keyword (3));
+the
+.B sod_init
+function expects the keywords as
+a variable-length argument tail;
+and
+.B sod_makev
+expects the keywords to be passed indirectly,
+through the captured argument-tail cursor
+.IR ap .
+.PP
+Storage for the new instance will have been allocated
+using the standard
+.BR malloc (3)
+function.
+The easiest way to destroy the instance,
+when it is no longer needed,
+is probably to call the
+.B sod_destroy
+function.
+.PP
+The return value is an instance pointer for the class
.IR cls ;
-otherwise it returns null.
-This involves a run-time trawl through the class structures:
-while some effort has been made to make it perform well
-it's still not very fast.
-For upcasts (where
-.I cls
-is a superclass of the static type of
-.IR obj )
-the automatically defined conversion macros should be used instead,
-because they're much faster and can't fail.
-When the target class is known statically,
-it's slightly more convenient to use the
-.B SOD_CONVERT
-macro instead.
+the
+.B SOD_MAKE
+macro will have converted it to the correct type,
+so it should probably be used where possible.
+.PP
+The
+.B sod_destroy
+function tears down and frees an instance allocated using
+.BR malloc (3).
+.PP
+The pointer
+.I p
+should be an instance pointer,
+i.e., a pointer to any of an instance's chains.
+The instance is torn down,
+by sending it the
+.B obj.teardown
+message.
+If the instance reports itself ready for deallocation,
+then its storage is released using
+.BR free (3).
+The return value is the value returned by the
+.B obj.teardown
+message.
.
.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.BR keyword (3),
.BR sod (1),
.BR sod-structs (3).
.
~mdw / sod / blobdiff