X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/4e3a7cb2594e9dd94ac6ad32e66cdfc50ee764a4..a985964182dbe5ea2e2ecda240fc862f13008820:/lib/sod.3 diff --git a/lib/sod.3 b/lib/sod.3 index 5908eb7..c49378a 100644 --- a/lib/sod.3 +++ b/lib/sod.3 @@ -92,9 +92,50 @@ sod \- Sensible Object Design runtime library .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 . .\"-------------------------------------------------------------------------- @@ -106,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 +to inhibit the runtime checking. . .SS Layout utilities The following macros are useful in @@ -336,6 +387,70 @@ 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 macro declares and initializes an instance with automatic storage duration. @@ -357,9 +472,109 @@ 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 +.BR keyword (3), .BR sod (1), .BR sod-structs (3). .