Copyright (C) 1996, 1997, P.J.Maker
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Nana is a library that provides support for assertion checking and logging in a space and time efficient manner. The aim is to put common good practise(1) into a library that can be reused rather than writing this stuff every time you begin a new project.
In addition assertion checking and logging code can be implemented using a debugger rather than as inline code with a large saving in code space.
Nana aims to solve the following problems:
bool isempty(){ /* true iff stack is empty */
DS($s = s); /* copy s into $s in the debugger */
...; /* code to do the operation */
DI($s == s); /* verify that s hasn't been changed */
}
These `$..' variables are called convenience variables
and are implemented by gdb. They have a global scope and are
dynamically typed and initialised automatically to 0.
In addition a C only version of before and after state is provided.
For example:
bool isempty() { /* true iff stack is empty */
ID(int olds); /* declare variable to hold old value */
IS(olds = s); /* copy s into $s in the debugger */
...; /* code to do the operation */
I(olds == s); /* verify that s hasn't been changed */
}
I(A(char *p = v, *p != '\0', p++, islower(*p)));These macros can be nested and used as normal boolean values in control constructs as well as assertions. Unfortunately they depend on the GNU CC statement value extensions and so are not portable. The following macros are defined in `Q.h':
A
E
E1
C
S
P
void process_events() {
for(;;){
DS($start = $cycles);
switch(get_event()){
case TOO_HOT:
...;
DI($start - $cycles <= 120);
break;
case TOO_COLD:
...;
DI($start - $cycles <= 240);
break;
}
}
}
The intended audience for Nana includes:
The Nana project was inspired by some other projects, in particular:
Anna is available from:Anna is a language for formally specifying the intended behaviour of Ada programs. It extends Ada with various different kinds of specification constructs from ones as simple as assertions, to as complex as algebraic specifications. A tool set has been implemented at Stanford for Anna, including:
- standard DIANA extension packages, parsers, pretty-printers;
- a semantic checker;
- a specification analyser;
- an annotation transformer; and
- a special debugger that allows program debugging based on formal specifications
All tools have been developed in Ada and are therefore extremely portable. Anna has thus been ported to many platforms. For more information send e-mail to "anna-request@anna.stanford.edu". Before down loading the huge Anna release, you may wish to copy and read some Anna LaTeX reports.
ftp://anna.stanford.edu/pub/anna
Eiffel is a pure object-oriented language featuring multiple inheritance, polymorphism, static typing and dynamic binding, genericity (constrained and unconstrained), a disciplined exception mechanism, systematic use of assertions to promote programming by contract, and deferred classes for high-level design and analysis.
Nana is essentially a poor mans implementation of some of these ideas which works for C and C++. Ideally in the best of all possible worlds you might want to look at Eiffel or in the military world Ada and Anna. If you use TCL/TK you might also be interested in Jon Cook's `AsserTCL' package.
Most C programmers become familiar with assertions from the the
assert.h header. As such its a very good thing and has a nice
simple implementation. However it is also inefficient and leads some
people to the conclusion that assertion checking is an expensive luxury.
The implementation of assert.h as distributed with gcc
looks like the following (after a bit of editing):
# ifndef NDEBUG
# define _assert(ex) {if (!(ex)) \
{(void)fprintf(stderr, \
"Assertion failed: file \"%s\", line %d\n", \
__FILE__, __LINE__);exit(1);}}
# define assert(ex) _assert(ex)
# else
# define _assert(ex)
# define assert(ex)
# endif
There are are two main problems with this:
assert.h had library code support we could make the implementation
much more space efficient, e.g. by calling a single function on error
detection.
Of course everyone merely rewrites their own `assert' macro so these are not significant objections. The only problem is if the author uses the libraries without modification.
This document aims to both describe the library and provide a tutorial in its use. Further work is required, particularly on the tutorial sections. If anyone has any suggestions please send them to me.
Nana uses the normal GNU install method in the same way as `gcc' and `gdb'. To install nana in the default location `/usr/local/{bin,lib,include}' you would use:
% gzcat nana-1.10.tar.gz | tar xvf - % cd nana-1.10 % ./configure % make % make install % make check % make check-mail % make subscribe
The check-mail and subscribe targets both send e-mail. If you need to change the mailer used try something like:
% make MAIL=elm subscribe
Note: we need to install nana before running the `make check' target. The `check-mail' target sends the test report via e-mail to the `nana-bug@cs.ntu.edu.au'.
Of course things are never that simple. If you want to install Nana in a different location or change the behaviour on error detection see section Configure.
Each of the sub-directories nana can be compiled and installed separately, e.g. if you don't need the documentation you can just compile and install from the `src' sub-directory after doing the configure statement.
The following software is possibly required to run nana.
gcc-2.7.2
gdb-4.16
gmake
For a listing of porting results including software versions see:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
In addition to the required software you might also be interested in:
Nana uses a standard GNU autoconf generated configure
script. The configure script checks the setup on your machine and
then generates the appropriate Makefiles. Some of the things checked by
configure include:
-lposix flag to the linker to build programs
on your machine.
unistd.h available on this machine.
In addition `configure' uses the host architecture and operating system to generate the `nana-config.h' file. This file contains some macro definitions which define how nana works on particular operating systems and hardware architectures.
For example on `i386' machines we would use the `asm("hlt")' instruction whenever an assertion fails, on a `sparc' we would use `asm("stp")'. Otherwise we would default to a plain C call to `abort()' If `configure' does not recognise your machine it uses plain C code.
You may wish to change these defaults on installation, one method is to edit
a local copy of the `nana-config.h' file. Alternately you can define
the code yourself in the call to `configure'. For example
to redefine the action we take when an error is detected by the I
macro we can use:
I_DEFAULT_HANDLER="restart_system()" ./configure
As well as simple calls to routines various other bits of information are passed off to the `I_DEFAULT_HANDLER' such as the expression that failure and a failure code. For example:
% I_DEFAULT_HANDLER="restart(line,file,param)" ./configure
The default for `I_DEFAULT_HANDLER' calls a function which prints a message and then dumps core. Different behaviour on failure can be organised by setting the `I_DEFAULT' to `fast', i.e. plain core dump or `verbose' which prints an error messsage and then does the core dump.
% I_DEFAULT=fast ./configure
For nana the following examples may be useful:
./configure
Accept the default values for everything. In particular the files will
be installed in:
`/usr/local/{bin,include,lib,man,info}'
./configure --prefix=~project/tools
Install the files into:
`~project/tools/{bin,include,lib,man,info}'
./configure --bindir=~project/bin --libdir=~/project/lib \
--includedir=~/project/headers --infodir=/usr/local/info \
--mandir=~/project/doc
The install directory for program (`bin'), etc can all be set with
command line arguments to`configure'.
CC=xacc LIBS=-lposix ./configure sun3
If the defaults chosen by `configure' are not correct you can
override them by setting variables such as CC before calling
`configure'. The `sun3' argument is used to identify the
machine we are running on and may be necessary on some machines.
./configure --help
And of course when in doubt ask for help.
For even more details see the file `INSTALL.con' which contains the generic instructions for use with `autoconf' generated `configure' scripts.
The configure program uses the following shell variables to change various defaults. Another method is simply to edit the `nana-config.h' file. Most of these values should be auto detected, so you can ignore this section until your need to save a few bytes of store by using `asm("hlt")' instead of a call to `abort()'.
DI_MAKE_VALID_BREAKPOINT
DL_MAKE_VALID_BREAKPOINT
I_DEFAULT_HANDLER
asm("hlt")
asm("stp")
abort()
restart()
ALWAYS_INCLUDE_MALLOC
Nana has been tested on the following platforms:
The `alpha-dec-osf3.2', `mips-sgi-irix5.3' and `powerpc-ibm-aix3.2.5' implementations have problems when you compile with `-O2' or `-O3' optimisation. This causes some errors in the the debugger based assertion and logging code since variables can be removed or changed by optimisation. At `-O' everything passes. Regardless of optimisation the C based checking code passes all tests on these platforms.
If you use nana on a new platform please send the `check.log' file to `nana-bug@cs.ntu.edu.au' via the `make check-mail' command. A machine generated list of this information is available at:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
Currently Nana works with the GNU GDB debugger which is available on a wide range of platforms including embedded systems and even provides support for remote debugging. Porting to any reasonable debugger with conditional breakpoints and commands is not very difficult.
As an example of an unreasonable debugger, Nana has been ported to
work with the MicroSoft Codeview debugger. The port is small (60 lines of
code) but suffers from a problem with variable scoping in Codeview. If
a breakpoint is set at a point in the code the expressions are not
evaluated from that particular scope. For example setting a breakpoint
in the function f cannot access a variable local to f
directly. Codeview has a unique (expletive deleted) scope operator
which you must use to set the scope `{...}'. This makes the
interface somewhat less than beautiful.
Another good thing about CodeView is to try a debug command which prints a message which contains a single open `{'. This of course causes it to hang and was the main problem during the porting to CodeView which took a whole day(2).
If anyone is interested I may release the CodeView implementation, please contact me if you are interested. Of course a better bet is probably to move to the `gdbserver' system. I think `gdb' has been released as a native even for some MicroSoft operating systems.
Other debuggers like DBX don't seem to be worth the trouble since gdb works on those machines. A redesign of the nana internals may also be useful if we decide portability between debuggers is actually useful.
Nana has the following known features (or perhaps problems):
DI or DL should be on lines by themselves. If you
mix code and nana macros on the same line you will get errors, e.g:
main(){
int x;
x = 5; x--; DI(x == 4);
}
This doesn't work since breakpoints are set at line boundaries rather
than statement ones. Of course anyone who writes code like this deserves
whatever happens to them.
DI(x +
10 > 30);
A few backslashes may solve this particular problem.
% ./configure pdp11-dec-ultrix
configure
script detecting vsnprintf. If configure doesn't find it
and it does exist then simply define it in `nana-config.h' as per
the previous question.
If vsnprintf really doesn't exist then get a new C library,
possibly the GNU libc.
vsprintf opens a security hole since no
bounds checking is done by it. Nana attempts to use vsnprintf
which is safe when it exists but it will resort to vsprintf
if it can't find vsnprintf. All careful people should make
sure that they have a library with vsnprintf.
STL header file errors due to nana.
The C++ STL header files for version 3.0 at least must
be included before the Q.h file. The problem is caused by the STL
files using S as a template argument. Of course Q.h uses
S for summing a series. Namespace pollution strikes again.
(Thanks to Han Holl for this particular problem).
If you think you have found a bug in the Nana library, please investigate it and report it.
If your bug report is good, we will do our best to help you to get a corrected version of the library; if the bug report is poor, we won't do anything about it (apart from asking you to send better bug reports).
Send your bug report to:
`nana-bug@cs.ntu.edu.au'
Copies of bug reports will be kept at:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
New versions of nana will be made available at:
`ftp://ftp.cs.ntu.edu.au/pub/nana/'
If you wish to be informed about new releases of nana then subscribe to the nana mailing list. Send a message containing `subscribe' <your e-mail address> to:
`mailto:nana-request@it.ntu.edu.au'.
A hypermail archive of this list is kept at:
`http://www.cs.ntu.edu.au/hypermail/nana-archive'
If you wish to send a message to the list send it to `mailto:nana@it.ntu.edu.au'.
The functions defined by Nana are implemented either as pure C code or as a set of commands which are generated for the debugger. To use the C based support for assertion checking you would use something like:
#include <nana.h> /* this file includes the other nana .h files */
int floor_sqrt(int i) { /* returns floor(sqrt(i) */
int answer;
I(i >= 0); /* assert(i >= 0) if i -ve then exit */
...; /* code to calculate sqrt(i) */
L("floor_sqrt(%d) == %d\n",
i, answer); /* logs a printf style message */
}
To compile and link the previous code you may need to use the `-Ipath' or `-lnana' flags with the compiler. For example:
% gcc toy.c -lnana
If the nana headers have been installed in a strange location you may need to do something like:
% gcc -I<strange location> toy.c -lnana
The next example uses the debugger versions of `L' and `I'. If the code is run under the debugger these checks will occur, otherwise they take up a negligible amount of space and time.
#include <nana.h> /* this includes the other nana .h files */
int floor_sqrt(int i){
int answer;
DI(i >= 0); /* assert(i >= 0) if i -ve then exit */
...; /* code to calculate sqrt(i) */
DL("floor_sqrt(%d) == %d\n", i, answer); /* logs a printf style message */
}
To generate the debugger commands from the C source we just run the `nana' filter over the program and then execute the commands under gdb using the `source' command.
% nana sqrt.c >sqrt.gdb % gdb a.out (gdb) source sqrt.gdb breakpoint insert: ... (gdb) run ... (gdb) quit
Note that any C preprocessor flags which you use must be passed off to the `nana' command. The best way to do this of course is in a Makefile. Something like the following works for GNU Make:
%.nana: %.c
nana $(CFLAGS) $< >$@
The `nana' filter can also be run over multiple source files in a single run if thats more convenient.
For convenience a number of other simple scripts are provided, in particular to:
nana-run
% nana-run a.out -x main.gdb output from program
nana-clg
% nana-clg -O3 main.c output from programYou can change the compiler invoked by `nana-clg' by redefining the `NANACC' environment variable. For example:
% NANACC=g++ nana-clg -O3 main.ccThe installation also `nana-c++lg' which compiles your code using a GNU C++ compiler.
nana-trace
% nana-trace a.out
54 printf("main()\n");
55 x = distance(5,-5);
distance (i=5, j=-5) at test.c:47
47 i = -i;
48 j = -j;
...
The arguments to `nana-trace' are passed directly to GDB. If you
wish display variables or call procedures on each line then could use
something like:
% nana-trace -x mycommands.gdb a.outWhere the `mycommands.gdb' contains the GDB commands such as `display x' which causes `x' to be printed every time the debugger gets control of the program.
This section describes the details of the interface to nana library.
All of the files can be included multiple times without ill--effect since they use the C preprocessor to make sure the header declarations are only seen the first by the compiler. Each of the files can also be included individually.
If any of the following routines have an internal problem (e.g. malloc fails due to lack of memory) they will call the `nana_error' function defined in `nana_error.c'. By default this function prints a message and dumps core using `abort'. If you wish to override this behaviour you should define your own handler before linking in the nana library.
The `nana.h' file includes most of the other files in the library. In particular it `#include's' the following files:
I.h
DI.h
L.h
DL.h
Q.h
GDB.h
If you wish to disable all nana code you can `#define' the `WITHOUT_NANA' macro. This selects versions of the macros defined in `I.h',`L.h', etc which map to `/* empty */'.
So if you are using nana for your development but don't wish to force your customers to use it you can add an option to your `configure' script to define/undefine `WITHOUT_NANA'. In addition you will need to distribute copies of the nana header files with your package to get the stubs.
Note that the `L.h' and `DL.h' macros use the macro variable number of arguments extension provided by GNU C. If you wish your code to be portable you should use the macros `VL((..))', etc rather than `L(..)' to avoid problems with non GNU C preprocessors which only take a fixed number of arguments.
This implements the C based invariant checking code and is a replacement for `assert.h'. The first two macros are the normal user interface; the remainder are used for configuring the behaviour on failure, etc.
Checking can be enabled and disabled by using the I_LEVEL and I_DEFAULT_GUARD macros. See the definitions below for these macros for further details.
Note that exprn should have no side-effects(5) since disabling checking shouldn't change your programs behaviour.
I(z != 0); x = y / z;
I(!(e)) and
exists as a piece of syntactic sugar which may be helpful for complicated
boolean expressions.
char* strdup(char *s) {
N(s == NULL);
...;
}
0
I, N, etc.
1
2
I_LEVEL defaults to 1.
I_DEFAULT_GUARD is used to selectively enable or disable
checking at compile or run time.
I_DEFAULT_GUARD defaults to TRUE, i.e. always enabled.
A user would typically define I_DEFAULT_GUARD to be global or local
variable which is used to turn checking on or off at run--time. For
example:
#define I_DEFAULT_GUARD i_guard > 0 extern int i_guard;
I_DEFAULT_HANDLER and defaults to
nothing, it is just some text and is intended to pass failure codes
(e.g. IEH303) or requests (e.g. HW_DEAD) information off
to the handler.
I_DEFAULT_PARAMS defaults to nothing.
When an error is detected the I_DEFAULT_HANDLER will be called to
handle the error. The arguments are:
exprn
"I(i>=0)".
file
__FILE__.
line
__LINE__.
param
I_DEFAULT_PARAMS. This can be used to pass failure codes or other
information from the checking code to the handler.
All of the remaining macros are used to individually override the default values defined above. Normally these macros would be used in a system wide header file to define macros appropriate for the application. For example you might use `IH' to define different checking macros for hardware and software faults.
We also provide support for referring to previous values of variables in
postconditions. The ID macro is used to create variables to
save the old state in. The IS and ISG macros are to
set these values.
For example:
void ex(int &r) {
ID(int oldr = r); /* save parameter */
g(r);
I(oldr == r); /* check r is unchanged */
while(more()) {
IS(oldr = r); /* assign r to oldr */
h(r);
I(oldr == r * r);
}
}
This implements the debugger based invariant checking code. The first two macros are the normal user interface; the remainder are used for configuring the behaviour on failure, etc. Note that these macros have no effect unless you run your program under the debugger and read in the commands generated by the `nana' command.
The checking using DI can be enabled and disabled by using the DI_LEVEL and DI_DEFAULT_GUARD macros. See the definitions below for these macros for further details.
Note that exprn should have no side-effects(6) since disabling the checking shouldn't change your programs behaviour.
I(!(e)) and
exists as piece of syntactic sugar which is helpful for complicated
boolean expressions.
0
DI, DN, etc.
1
2
DI_LEVEL defaults to 1.
DI_DEFAULT_GUARD is used to selectively enable or disable
checking at compile or run time.
DI_DEFAULT_GUARD defaults to TRUE, i.e. always enabled.
A user would typically define DI_DEFAULT_GUARD to be global or local
variable which is used to turn checking on or off at run--time. For
example:
#define DI_DEFAULT_GUARD (i_guard) extern int i_guard;
DI_DEFAULT_HANDLER and defaults to
nothing, it is just some text and is intended to pass failure codes
(e.g. IEH303) or requests (e.g. HW_DEAD) information off
to the handler.
DI_DEFAULT_PARAMS defaults to nothing.
When an error is detected the DI_DEFAULT_HANDLER will be called to
handle the error. The arguments are:
exprn
"I(i>=0)".
file
__FILE__.
line
__LINE__.
param
DI_DEFAULT_PARAMS. This can be used to pass failure codes or other
information from the checking code to the handler.
DI, etc. It defaults to
asm("nop") and can be redefined by the user.
All of these macros are used to individually override the default values defined above. Normally these macros would be used in a system wide header file to define macros appropriate for the application.
$ and can be used be
used for saving the state of program or for counting events. The
`DS' macro executes e under the same rules as DI.
The `DSG' macro executes e only if the the expression
g is true.
Note that `DS' and `DSG' can also be used for modifying C variables and calling functions.
These routines are used to provide logging functions. Messages can be divided into classes and separately enabled and disabled.
Defaults to a using fprintf on stderr.
The macros such as `L' depend on the GNU CC variable number of arguments to macros extension. If you wish to compile your code on other systems you might wish to use the following variations on `L', etc.
Thus you can have nana under GCC whilst the code is still portable to other compilers. However debugging information will not be available on other platforms.
Note: the argument list is surrounded by two sets of brackets. For example:
VL(("haze in darwin = %d\n", 3.4));
2
1
0
Defaults to 1.
Defaults to fprintf
Defaults to TRUE.
Defaults to stderr
A traditional embedded systems trick is to log messages to a circular buffer in core. This has the following benefits:
L_BUFFER *lbuffer; lbuffer = L_buffer_create(32*1024); /* create a 32K buffer */ ...; L_buffer_delete(lbuffer); /* and delete it after use */
L_BUFFER *lb = L_buffer_create(32*1024); L_buffer_wraparound(lb, 0); /* disable wraparound */
L_buffer_printf(lbuffer, "U: user input %c\n", c); L_buffer_puts(lbuffer, "warning: its too hot"); L_buffer_putchar(lbuffer, '*');
Note: a null pointer passed to the `L_buffer_puts' function prints as `(null)'. (7)
Note that this does not change the contents of the buffer. This is important since we may have a hardware or software problem part of the way through the dump operation and you don't want to loose anything.
To reset the buffer after a successful dump use `L_buffer_clear'.
The output of `L_buffer_dump' consists of a starting message followed by the contents of the log. If a character in the log is not printable we print it out in hex on a line by itself.
* L_buffer_dump = log message and another * non-printable character 0x1 more log messages * end of dump
You also need to be able to integrate these functions into your design. See `examples/ott.c' for a complicated example. Here we will provide a simplified version which implements a new logging macro called `LFAST' which does a `printf' to the `log_buffer'. If you want to have all messages going to a `L_BUFFER' then you can redefine `L_DEFAULT_HANDLER'.
/* project.h - the project wide include file */ #include <nana.h> #include <L_buffer.h> /* LFAST(char *, ...) - log a message to the log_buffer */ /* ##f translates as the rest of the arguments to LFAST */ #define LFAST(f...) LHP(L_buffer_printf,log_buffer,##f) extern L_BUFFER *log_buffer; /* the log buffer */
The main program merely creates the log_buffer and eventually calls `L_buffer_dump' to print out the buffer when the system dies.
/* main.c - initialise the system and start things */
#include <project.h>
L_BUFFER *log_buffer;
main() {
log_buffer = L_buffer_create(16000);
if(log_buffer == NULL) { /* not enough store */
...
}
LFAST("system starting at %f\n", now());
...;
}
void fatal_error() { /* called on fatal errors */
FILE *f = fopen("project.errors","w");
L_buffer_dump(b, stderr); /* print log to stderr */
L_buffer_dump(b, f); /* print log to file */
}
This component is used to record events and times with a lower time and space overhead than the `L_buffer.h' component. Instead of using a `printf' style string we simply record the time and a pointer to a string identifying the event in a circular buffer.
Note 0: the string arguments should not be modified after a call since we record pointers to the strings rather than the strings themselves.
Note 1: there is no printf style formatting, e.g. `%d' in this package.
These routines are used to provide logging functions. Messages can be divided into classes and separately enabled and disabled.
Defaults to a using fprintf on stderr.
The macros such as `DL' depend on the GNU CC variable number of arguments to macros extension. If you wish to compile your code on other systems you might wish to use the following variations on `DL', etc.
Thus you can have debugging under GCC whilst the code is still portable to other compilers. However debugging information will not be available on other platforms.
Note: the argument list is surrounded by two sets of brackets. For example:
VDL(("haze in darwin = %d\n", 3.4));
2
1
0
Defaults to 1.
Defaults to fprintf
Defaults to TRUE.
stderr
DL_SHOW_TIME. This causes the _L_gettime routine to be
called before each message which generates the timestamp. A default
version is provided by the nana library.
`GDB.h' provides macros for generating user specified commands in the output of the `nana' command. They are not included by default in the `nana.h' file.
This could be used to set debugger options or to define procedures inside `gdb', e.g.
GDB(define checkstack); GDB( if 0 <= n && n <= 10); GDB( print "stack ok"); GDB( else); GDB( print "stack corrupted"); GDB( end); GDB(end);
GDBCALL(set memory_check = 1)
These macros could used for instrumenting code or setting up test harnesses, e.g.
GDB(set $siocall = 0);
GDB(set $sioerr = 0);
void sio_driver() {
GDBCALL(set $siocall++)
if(SIO_REQ & 0x010) {
GDBCALL(set $sioerr++);
...
}
}
`Q.h' provides support for the quantifiers of predicate logic. For example to check that all elements in a data structure have some property we would use universal (forall, upside down A) quantification. To check that one or more values in a data structure have some property we would use existential (exists, back the front E) quantification. For example:
/* all values in a[] must be between 0 and 10 */ I(A(int i = 0, i < n_array, i++, 0 <= a[i] && a[i] <= 10)); /* there exists a value in linked list l which is smaller than 10 */ I(E(node *p = l, p != NULL, p = p->next, p->data <= 10));
The first three arguments to `A' and `E' are similar to a C `for' loop which iterates over the values we wish to check. The final argument is the expression that must be true.
The only minor difference from the C `for' loop is that variables may be declared at the start of the loop, even if you are using C rather than C++ which already supports this.(8)
The `Q.h' macros can also be nested and used anywhere a boolean value is required. For example:
if(A(int i = 0, i < MAXX, i++,
A(int j = 0, j < MAXY, j++,
m[i][j] == (i == j ? 1 : 0)))) {
/* identity matrix, i.e. all 0's except for 1's on */
/* the diagonal */
...
} else {
/* not an identity matrix */
...
}
The results from these macros can also be combined using boolean operations, e.g.
/* the values in a[i] are either ALL positive or ALL negative */
I(A(int i = 0, i < MAX, i++, a[i] >= 0)
||
A(int i = 0, i < MAX, i++, a[i] < 0));
Portability: note the macros in this file require the GNU CC/C++ statement expression extension of GCC to work. If your not using GNU CC then for now you are out of luck. At some time in the future we may implement a method which will work for standard C++, standard C is a bit of a challenge.
Portability: unfortunately these macros do not for the `DI' and `DL' macros since the statement expression extension has not been implemented in GDB.
I(A(int i = 0, i < MAX, i++, a[i] >= 0)); /* all a[i] are +ve */
/* one or more a[i] >= 0 */ I(E(int i = 0, i < MAX, i++, a[i] >= 0));
/* 3 elements of a[] are +ve */ I(C(int i = 0, i < MAX, i++, a[i] >= 0) == 3);
/* a single elements of a[] is +ve */ I(E1(int i = 0, i < MAX, i++, a[i] >= 0));
/* sum of a[] is 10 */ I(S(int i = 0, i < MAX, i++, a[i]) == 10); /* sum of all +ve numbers in a[] is 10 */ I(S(int i = 0, i < MAX, i++, a[i] >= 0 ? a[i] : 0) == 10);
/* product of all the values in a[] is 10 */ I(P(int i = 0, i < MAX, i++, a[i]) == 10); /* a = x^y i.e. x*x..*x y times */ I(P(int i = 0, i < y, i++, x) == a);
The Standard Template Library (STL) is a library for C++ that makes extensive use of templates to implement the standard container classes and much more. Each of the container classes provides an interface to iterate over all the objects in the container, e.g.
// MAP is an associate array from location(lat,long) onto the name.
typedef map<location,string,locationlt> MAP;
void print_map_names(MAP& m) { // print out all the names in the map
for(MAP::iterator i = m.begin(); i != m.end(); ++i) {
cout << (*i).second << "\n";
}
}
`Qstl.h' provides the same facilities as `Q.h' but uses the standard STL iterator protocol shown above. The names in `Qstl.h' are generated by appending a `O' (O not zero!) to the names in `Q.h'. In particular:
map<int,char *,ltint> m; // all keys (or indexes) into m are positive I(AO(i, m, (*i).first >= 0));
map<int,char,ltint> m; // one or more characters in m are '$' I(EO(i, m, (*i).second == '$'));
map<int,char,ltint> m; // one characters in m is a '$' I(E1O(i, m, (*i).second == '$'));
map<int,char,ltint> m; int nalpha; // count the number of alphabetic chars in the map nalpha = CO(i, m, isalpha((*i).second));
map<int,float,ltint> m; float sum; // sum all the values in m sum = SO(i, m, (*i).second);
map<int,float,ltint> m; float product; // multiply all the values in m product = PO(i, m, (*i).second);
The `now.h' file provides some simple time measurement routines. It is not included in `nana.h' so you must include this file separately.
It uses the `gettimeofday' system call and has an accuracy of between 1us and 10ms depending on the operating system and hardware configuration.
See the IPM package if you require better measurement tools.(10)
t = now();
for(;;) {
...; /* code that must finish in 50ms */
I(now_delta(&t) <= 0.050);
}
Eiffel is a very nice language which provides the assertion checking facilities of nana inside the language itself. The `eiffel.h' library is intended to provide a similar setup to Eiffel in the C++ language. It is a pretty poor emulation, but it is hopefully better than nothing.
Assertion checking is controlled by the EIFFEL_CHECK variable which can take on any of the following values:
CHECK_NO
CHECK_REQUIRE
CHECK_ENSURE
CHECK_INVARIANT
CHECK_LOOP
CHECK_ALL
A typical compile flag to the compile might be:
% g++ -c -DEIFFEL_CHECK=CHECK_ALL play.cc
And then we have the actual assertion macros.
And finally a small example:
#include <eiffel.h>
class example {
int nobjects;
map<location,string,locationlt> layer;
public:
bool invariant();
void changeit(location l);
};
bool example::invariant() {
return AO(i,layer,valid_location((*i).first)) &&
nobjects >= 0;
}
void example::changeit(string n, location l) {
REQUIRE(E1O(i,layer,(*i).second == n));
...;
while(..) {
INVARIANT(...);
...
INVARIANT(...);
}
...
CHECK(x == 5);
...
ENSURE(layer[l] == n);
}
Note that the invariant checking macro `example::invariant' is called automatically on function entry/exit using the `REQUIRE' and `ENSURE' macros.
A drop in replacement for `assert.h' is provided in the `src' directory. It is not installed by default. If you wish to use it then you need to copy it to your include directory by hand.
This might be of use if you are already using `assert.h' and wish to save some code space since the nana implementation is more space efficient.
Calls to `assert' are translated to calls to `I' and can be disabled by defining `NDEBUG'.
The `calls' module implements a simple list of functions which can be modified and executed at run-time. It is similar in spirit to the ANSI C `atexit' function. It is intended to be used for:
void print_object(void *f) {
...;
}
CALL *head = 0;
CALL *global_checks = 0; calls_add(&global_checks,complex_ok,(void *)x);
calls_exec(&l,0,0); /* execute all functions in l */ calls_exec(&l,complex_print,0); /* calls complex_print(*) in l */ calls_exec(&l,0,(void*) &b); /* calls *(&b) in l */ calls_exec(&l,f,(void*) &b); /* calls f(&b) in l */
calls_delete(&l,0,0); /* delete all functions in l */ calls_delete(&l,complex_print,0); /* delete complex_print(*) in l */ calls_delete(&l,0,(void*) &b); /* delete *(&b) in l */ calls_delete(&l,f,(void*) &b); /* delete f(&b) in l */
Note: that calls are added to the head of the list rather than the tail. This means that the most recently added call will be executed first (as in a stack).
This chapter is intended to provide some hopefully useful examples of Nana. If any of the users of this library would be so kind as to contribute a section on their usage I would be obliged.
This section is under development
As a nice simple, indeed trivial example consider the following:
`syslog' is a comprehensive logging system written by Eric Allman which is available on most UNIX systems. It provides facilities for sorting messages by source or severity and mechanisms for sending messages off to files, terminals or other machines. See chapter 12 of the "UNIX System Administration Handbook (2nd Edition)" by Nemeth, Snyder, Seebass and Hein for an excellent tutorial on `syslog'.
The rules used by `syslog' are normally defined in `/etc/syslog.conf'. Each line specifies the destination for messages with particular sources and priorities. For example:
# log mail messages at priority info to mailinfo mail.info /var/log/mailinfo # log all ftp information to syslog on a remote machine ftp.* @remote-machine.cs.ntu.edu.au # all critical errors to console *.crit /dev/console
To use `syslog' we merely redefine the default handlers and parameter values for `nana'. For example:
#include <syslog.h>
#define L_DEFAULT_HANDLER syslog /* replaces fprintf(3) by syslog(3) */
#define L_DEFAULT_PARAMS LOG_USER /* default priority for syslog info */
#include <nana.h>
int main() {
openlog("nana", /* identifier for these log messages */
LOG_PID, /* also log the process id */
LOG_DAEMON /* facility */
);
L("temperature is falling to %d", 35); /* logged at LOG_USER priority */
LP(LOG_CRIT, "the snow is falling in Darwin"); /* LOG_CRIT message */
closelog();
return 0;
}
This program results in the following addition to `/var/adm/messages':
Jun 12 16:04:46 chingiz nana[2671]: the temperature is falling to 35 Jun 12 16:04:46 chingiz nana[2671]: the snow is falling in Darwin
In addition the `LOG_CRIT' message about snow falling in Darwin is sent to the console for immediate action.
Note: `syslog' normally uses `UDP' for its network communications and that `UDP' does not guarantee delivery.
Imagine you(12) are building a GNU program. Ideally it should run on systems without any other software including GCC, GDB and even Nana.
To achieve this noble goal you can provide your configure script with a `--without-nana'(13) flag which then `#define's' `WITHOUT_NANA'. You should also use the `VL' macro rather than `L' macro since `L' takes a variable number of arguments and will break non GNU C preprocessors.
int half(int n) {
/* Don't use L(...) since it takes a variable number of args! */
VL(("hello world = %d\n", 10)); /* Note the doubled (( */
...;
}
One of the uses (in fact the original use) for nana is in the testing of non-deterministic systems. These systems behave in a different way each time they are run because of timing or measurement noise. Thus you can't just `diff' the results against a known good run since they run differently each time.
Instead you can use a series of programs which execute over a the results of the program and check that the behaviour meets the specification automatically.
Assertions for the timing behaviour of you system can be done in nana nicely. You might also consider using an instruction level simulator such as PSIM and use the `cycles' variable to test realtime constraints.
Ah databases, business boffins using assertions. It would nice to get a real example for this one!
One nice way to use `L', `DL', etc is to punt off the messages off to a program which displays the information. You would use the `L_DEFAULT_PARAM' argument to send commands off to a pipe with gnuplot or TCL/TK interpreter running at the end.
For a small example of this, see `tcl/status.c'.
This chapter is intended to answer some general questions about the usage of Nana. Most of the material (perhaps) has been presented elsewhere, my apologies for repeating myself.
As usual, there is more work to be done than time to do it in. Workers or test pilots are invited to apply for the following tasks which may get down in the fullness of time minister. I'm particularly interested in which projects people think are worthwhile (or rubbish).
Jump to: 0 - 1 - 2 - a - c - d - e - f - g - i - l - n - p - q - r - s - t - v
Which is unfortunately quite uncommon in the authors experience.
And about 60 reset cycles where the machine went off into hyperspace
This allows variable number of arguments to C preprocessor macros.
If you don't want a core dump then look at stopping the core
dumps with ulimit rather than changing the handler.
Side-effects include such operations as input/output or assignments, e.g. `x++'
Side-effects include operations like input/output or assignments.
This was suggested by Phil Blecker.
ANSI C does not allow variable declarations at the beginning of loops unlike C++. The `Q.h' macros get around this by starting each loop with a new scope.
This uses yet another GNU CC extension, however since we are already using statement expressions we might as well use `typeof' as well.
In the fullness of time, we may integrate these routines in here.
Of course you also need to use the gdb commands generated by the `nana' command, perhaps using `nana-clg'
Gordon Matzigkeit contributed some of the ideas presented here and raised this problem.
Or add a `--with-nana' flag to configure that does the opposite.
This document was generated on 6 November 1998 using the texi2html translator version 1.52.