@@@ doc wip

[mLib] / utils / macros.3.in

diff --git a/utils/macros.3.in b/utils/macros.3.in
index caeb414..c7893fb 100644 (file)
--- a/utils/macros.3.in
+++ b/utils/macros.3.in
@@ -32,6 +32,7 @@
 .\" @N
 .\" @STR
 .\" @GLUE
+.\" @GLUE3
 .\" @STATIC_ASSERT
 .\" @CHECK_TYPE
 .\" @CONVERT_CAREFULLY
@@ -64,6 +65,8 @@
 .\" @DISCARD
 .\" @IGNORE
 .\" @LAUNDER
+.\" @ADMIRE
+.\" @ADMIRE_BUF
 .\" @RELAX
 .
 .\" @DEPRECATED
@@ -93,6 +96,7 @@ macros \- useful macros
 .BI "size_t N(" type " " array "[]);"
 .BI "STR(" tokens\fR... ")"
 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
+.BI "GLUE3(" tokens\fR... ", " tokens\fR... ", " tokens\fR... ")"
 .BI "STATIC_ASSERT(" cond ", " msg ");"
 .BI "int CHECK_TYPE(" expty ", " expty " " x );
 .IB newty " CONVERT_CAREFULLY(" newty ", " expty ", " expty " " x );
@@ -124,6 +128,10 @@ macros \- useful macros
 .PP
 .BI "void DISCARD(" scalar ");"
 .BI "void IGNORE(" variable ");"
+.IB type " LAUNDER(" type " " x ");"
+.BI "void ADMIRE(" type " " x ");"
+.BI "void ADMIRE_BUF(void *" p ", size_t " sz ");"
+.B "void RELAX;"
 .PP
 .BI "DEPRECATED(" msg ")"
 .BI "EXECL_LIKE(" ntrail ")"
@@ -162,7 +170,11 @@ macro expands to a single token, which is the result of gluing together
 the tokens resulting from expanding its argument token lists.  Each of
 the argument token lists must expand to a single preprocessing token,
 and the result of gluing these tokens together must be valid
-preprocessing token.
+preprocessing token.  The
+.B GLUE3
+macro does the same, except that it glues together
+.I three
+argument token lists rather than two.
 .PP
 The
 .B STATIC_ASSERT
@@ -278,14 +290,29 @@ This can be useful in muffling warnings about unused variables.
 The
 .B LAUNDER
 macro tries to confuse a compiler so that it `forgets' what it knows
-about a particular value.  This is most useful in benchmarking or
-similar applications.
+about a particular value.
+.PP
+The
+.B ADMIRE
+macro tries to confuse a compiler so that it will faithfully computes
+the argument
+.I x
+even though it's not used for anything.  The
+.B ADMIRE_BUF
+macro works similarly, but on regions of memory.
 .PP
 The
 .B RELAX
 macro tries do nothing, but in a way that a compiler won't optimize
 away.
-.
+.PP
+The
+.BR LAUNDER ,
+.BR ADMIRE ,
+.BR ADMIRE_BUF ,
+and
+.B RELAX
+macros are most useful in benchmarking and similar applications.
 .SS Annotations
 The following annotations can be attached to function declarations and
 definitions, as part of the declaration specifiers.  (Other positions