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).
Go to the first, previous, next, last section, table of contents.