.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 );
+.br
+.IB cls " *" \c
+.B SOD_MAKE(\c
+.IB cls ,
+.IB keywords );
+.br
+.B void *\c
+.B sod_make(\c
+.BI "const SodClass *" cls ,
+.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
.
.\"--------------------------------------------------------------------------
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 Layout utilities
The following macros are useful in
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
macro declares and initializes an instance
with automatic storage duration.
The instance has automatic storage duration:
pointers to it will become invalid when control
exits the scope of the declaration.
+.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_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_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 ;
+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