X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/a142609c5dc2a7c3df02497235881beaf47088bf..d5fdd49e70b734b791eb907706f92da5775e2a8b:/lib/sod.3

diff --git a/lib/sod.3 b/lib/sod.3
index b713d57..c49378a 100644
--- a/lib/sod.3
+++ b/lib/sod.3
@@ -110,9 +110,32 @@ sod \- Sensible Object Design runtime library
 .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
 .
 .\"--------------------------------------------------------------------------
@@ -124,6 +147,16 @@ instances and classes inherit from the standard
 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
@@ -403,6 +436,21 @@ 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.
@@ -424,6 +472,105 @@ are set to the appropriate initial values.
 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