FIX: documentation for RESOURCE_ENTER was not updated

[nobug.git] / README.txt

NoBug Documentation
===================

[paradef-literal]
 Everyone makes errors, but with NoBug you won't make them twice!

Nobug is a simple debugging library for instrumenting C and C++ programs
inspired by ideas originating from Design-by-Contract.

Overview
--------

The following features are provided by NoBug:

  * Three different check levels: from detailed to final no-overhead
  * Scope tags: tell whenever a function or loop is considered to be bug free
  * Precondition, Postcondition and Invariant checks and generic assertions
  * Debugger support (actions are only executed while running under a
    debugger), currently only valgrind is supported
  * Datastructures can be dumped
  * Application activities can be logged
  * Runtime customizable logging via an environment variable
  * Different logging targets to stderr, syslog, debugger, ...
  * Annotation of your sourcecode about known bugs, things to do, etc.
  * Tracking resources (files, locks, etc.) used by your program; help in
    detecting misuse
  * Detecting deadlocks

In contrast to traditional debuggers, NoBug is a non-interactive debugger which
is linked to your application doing hard-coded tests in an efficient,
low-overhead way.

Building and Installing
-----------------------

Release Tarballs
~~~~~~~~~~~~~~~~

Release tarballs are attached to this wiki at:

  * http://pipawiki/NoBug?action=AttachFile

Gpg signed tarballs are being used for distribution. The first step involves
checking the signature:

$ gpg nobug-X.Y.tar.gz.gpg

This will produce a nobug-X.Y.tar.gz and report if the signature could be
validated.

Since they are built with gnu autotools, the usual build and install procedure
will work:

$ tar xzvf nobug-X.Y.tar.gz
$ cd nobug-X.Y
$ ./configure
$ make
$ make install

Development Version via git
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The development version is available via git from 'git://git.pipapo.org/nobug'
or mirrored at repo.or.cz 'git://repo.or.cz/nobug.git'.

After you have cloned the repository, you'll then have to bootstrap the
autotools first:

$ autoreconf -i

Then the usual ./configure && make && make install will work.

There is a special makefile target make meta to bring several files (README,
AUTHORS, NEWS) in sync with the NoBug documentation wiki and update the
changelog.

What Is Installed
~~~~~~~~~~~~~~~~~

Currently, NoBug installs the following:

  * A single nobug.h headerfile which your code will use
  * Two libs that are used by statically linking:
      + 'libnobug.a' for singlethreaded programs.
      + 'libnobugmt.a' for multithreaded programs.

Using NoBug
-----------

You can make NoBug features available either by installing it as described
above or by shipping the nobug sources along with your project.

To use NoBug, some controlling preprocessor macros have to be defined. The
nobug.h header should then be included.

A project using NoBug should use autoconf to check for execinfo.h and valgrind/
valgrind.h

AC_CHECK_HEADERS([execinfo.h valgrind/valgrind.h])

For Multithreaded programs, you should also check for pthread.h.

When the resulting HAVE_PTHREAD_H, HAVE_EXECINFO_H and HAVE_VALGRIND_VALGRIND_H
are defined by the configure script, the corresponding features become
available.

NoBug then defines 'NOBUG_USE_PTHREAD', 'NOBUG_USE_VALGRIND' and
'NOBUG_USE_EXECINFO' to 1. If you do not want to use any of these features in
NoBug, you can define these macros to 0 before including nobug.h.

If NVALGRIND is defined, valgrind support will not be available.

There are many other macros which can be set and overridden by the user to
control behavior. Please edit the wiki documentation if you find them useful.

To use NoBug with single threaded programmes, link libnobug.a to your project;
multi-threaded programmes should link with libnobugmt.a. The Library must be
initialized with NOBUG_INIT before any features can be used or a thread is
created. This is discussed in more detail at NoBug/Documentation/Macros/
MultiThreading.

Activating Logging
~~~~~~~~~~~~~~~~~~

Checking for Additional Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NoBug uses a number of additional optional tools depending on the application
and the debugging information required.  Such tools as valgrind, gdb and support
for multi-threaded applications can be tested whether they are available on a
particular system.  This can be done, for example, by using autoconf.  

Depending on the value of the following defines, the relevant tool or feature
is activated:

    NOBUG_USE_VALGRIND::      
        1;; Use valgrind
        0;; Do not use valgrind

    NOBUG_USE_PTHREAD::
        1;; Support for multi-thread applications
        0;; Single-threaded applications

    NOBUG_USE_EXECINFO::
        1;; Backtrace information
        0;; No backtrace informatin

Header and Initialisation
^^^^^^^^^^^^^^^^^^^^^^^^^
The project source file will have to include nobug.h, and Nobug will have to be
initialised using NOBUG_INIT before any NoBug features can be used.

-------------------------------------------------------
...
#include "nobug.h"
...

int main()
{
    NOBUG_INIT();
    ...
}
-------------------------------------------------------


Debugging Information Granuality: The Build Levels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Debugging information can be produced at three different levels: alpha, beta and
release:

  ALPHA::
        This debugging level is envisaged for the development phase of a project
        where exhaustive testing and logging are requred.
  BETA::
        This debugging level is more appropriate for projects beyond the
        development phase and ready for trials in the field and users willing to 
        test the software.
  RELEASE::
        This level is for final, end-users. 


Select a Build Level
++++++++++++++++++++
One of the above debugging levels is selected by defining one of the following:

    *ALPHA*::   -DEBUG_ALPHA

    *BETA*::    -DEBUG_BETA

    *RELEASE*:: -DNDEBUG

Then the project is compiled.  If one of the above switches has not been set,
NoBug will complain.

Link Appropriate Library
^^^^^^^^^^^^^^^^^^^^^^^^
Finally, the appropriate library (for either single or multi-threaded
applications) is linked to the project.

   *libnobug.a*:: Link-in this library for single threaded applications.
   *libnobugmt.a*:: Link with this library for multi-threaded applications.


Release builds remove all assertions, but some logging is still kept. We make
the assumption that bugs which were not covered in alpha and beta builds will
not easily show up in releases because the assertions there were not
sufficient. Furthermore, end users are not test bunnies and will not provide
good bug reports anyway. If there is a problem in a release build, try to track
down the cause using a beta build from the same source.


Scope Checks
^^^^^^^^^^^^
The programmer can tag any scope as UNCHECKED or CHECKED. In ALPHA and BETA
builds, a global UNCHECKED is implied. In RELEASE builds, UNCHECKED scopes are
not allowed.

Test Matrix
^^^^^^^^^^^
Here is a table of the basic assertions that are checked depending on the level
/scope combination:

          ALPHA                          BETA                   RELEASE
UNCHECKED Preconditions, Postconditions, Preconditions,         compiling will
          Invariants                     Postconditions         abort
CHECKED   Preconditions, Postconditions  Preconditions

Macros
------
The NoBug interface is almost completely implemented using preprocessor macros.
This is required because NoBug uses the __FILE__ and __LINE__ macros to log
information on the current file and the current line number within that file.
Moreover, all the flat namespace uppercase identifiers make it ease to
recognise the macros in source code.

All macros are available without condition with the 'NOBUG' prefix. Macros are
also available without the NOBUG prefix as a convenience, however macros
without this prefix must not have been previously defined. All assertion and
logging macros have a corresponding form postfixed by '_DBG'. Such macros will
only be active within a debugger and are only available in ALPHA builds.

When NOBUG_DISABLE_SHORTNAMES is defined by the user, then only the NOBUG_
prefixed macros are available and the short forms will never be defined.

A set of macros are provided by NoBug that are postfixed by '_IF'. These macros
are wrappers around assert from the C lib. These macros have the following
form:

  * WHATEVER_IF(when, ...)

We assert that when is true, if it is not, the assertion will fail. For
example:

  * REQUIRE_IF(foo!=NULL, foo->something == constrained)

The assertion will only be performed if foo points to some memory, or is non
NULL.

Debugger versions are available using _IF_DBG postfixed to the name of the
macro.

Parameters types:

when    Assertion is only performed if expression 'when' is true at runtime
expr    Test without side effects
fmt     printf-like format string
...     If not preceded by 'fmt', then printf-like format string; otherwise,
        only its arguments
flag    Flag to enable custom logging groups
type    Data type to be checked as a single identifier name
pointer Pointer to type
lvl     Log level
depth   Depth for invariants and dumps

Initialization

Global init

You have to call

  * NOBUG_INIT

before using any other NoBug feature. Probably in main or any other library
initialization routine. Calling NOBUG_INIT more than once is supported and each
subsequent call will be a no-op, thus initialization in main and in libraries
won't interfere.

Control Flags

If you want to use environment variable controlled debuging, then you have to
initialize each flag with

  * NOBUG_INIT_FLAG(flagname)

or

  * NOBUG_INIT_FLAG_LIMIT(flagname, default)

This is documented later in NoBug/Documentation/Macros/LoggingConfiguration.

  * <!> These two macros call NOBUG_INIT for backward compatibility.

Threads

In Multithreaded programs you should assign an identifier to each thread after
it is created with

  * NOBUG_THREAD_ID_SET(name)

If you don't call it, then NoBug will assign a automatic identifier. This is
documented in NoBug/Documentation/Macros/MultiThreading.

Assertions

  * REQUIRE(expr, ...)
      + Precondition (input) check. Use these macros to validate input a
        function receives. The checks are enabled in ALPHA and BETA builds and
        optimized out in RELEASE builds.

    ENSURE(expr, ...)
      + Postcondition (progress/output) check. Use these macros to validate the
        data a function produces (example: return value). The checks enabled
        unconditionally in ALPHA builds and optimized out in BETA builds for
        scopes which are tagged as CHECKED. In RELEASE builds this checks are
        always optimized out, but scopes tagged as UNCHECKED are not permitted.

    ASSERT(expr, ...)
      + Generic check. Use these macros when you want to validate something
        which doesn't fall into one of the above categories. A example is when
        a library function can return a unexpected result (scanf with syntax
        error in the formatstring, when a constant/literal formatstring is
        expected). The checks are enabled in ALPHA and BETA builds and
        optimized out in RELEASE builds.

    assert(expr)
      + NoBug overrides the standard assert macro in ALPHA and BETA builds.
        This is just a compatibility feature, its use is not suggested.

    INVARIANT(type, pointer, depth)
      + Checking invariants. You can provide more complex checking functions
        which test the validity of datastructures. Invariants are only enabled
        in ALPHA builds for scopes which are not tagged as CHECKED and
        otherwise optimized out. (TODO: document how to write invariants)

Logging

Nearly all NoBug Macros emit some log message. NoBug gives the user fine
grained control over these log messages to display only interesting information
without loosing details.

Log messages are routed to different destinations which are:

  * RINGBUFFER
      + The underlying storage backend. Messages are appended to the end of the
        buffer, overwriting older messages at the front of the buffer. NoBug
        comes with a highly efficient ringbuffer implementation. This
        ringbuffer is temporary by default but can be made persistent. NoBug
        comes with a 'nobug_rbdump' tool to get a log out of such a ringbuffer.
  * CONSOLE
      + This is either just stderr or if running under valgrind then valgrind
        facilities to include messages into its log will be used.
  * FILE
      + The user can open Files for log messages.
  * SYSLOG
      + Messages are send to the standard system logging daemon.
  * APPLICATION
      + There is a hook which allows the programmer to catch logmessages and
        display them in a application defined way.

Each logmessage has a priority describing its severity in the same way as
syslog messages do.

All non-fatal messages are associated with a programmer defined flag describing
the source of the message (subsystem, module, ...).

Putting it all together: A user can define which source/flag shall be logged at
what priority level and to which destination. To make this all easier NoBug
tries to give reasonable defaults.

Configuration

Log Levels

Each Log macro has a explicit or implicit Log-Level which correspondends to
syslog levels. Logging is only emitted when the messages is more severe than a
defined limit.

The defaults look like:

            ALPHA BETA    RELEASE
ringbuffer  TRACE INFO    NOTICE  ringbuffer must always be most verbose
console     INFO  NOTICE  -1      no log to console in release
file        TRACE NOTICE  WARNING
syslog      -1    NOTICE  WARNING no syslog for test runs
application INFO  WARNING ERROR

Depending on the build level there is a default logging target and a default
limit which is choosen when the user doesn't specify one.

The default limits are:

  * In ALPHA builds, NOBUG_LOG_LIMIT_ALPHA is used which defaults to LOG_INFO
  * In BETA builds, NOBUG_LOG_LIMIT_BETA is used and defaults to LOG_WARNING
  * In RELEASE builds, NOBUG_LOG_LIMIT_RELEASE is used and defaults to LOG_CRIT

The default targets are:

  * In ALPHA builds, NOBUG_LOG_TARGET_ALPHA is used which defaults to
    NOBUG_TARGET_CONSOLE
  * In BETA builds, NOBUG_LOG_TARGET_BETA is used and defaults to
    NOBUG_TARGET_FILE
  * In RELEASE builds, NOBUG_LOG_TARGET_RELEASE is used and defaults to
    NOBUG_TARGET_SYSLOG

You can override all of those values with your own preference. Alternatively
NOBUG_LOG_LIMIT and NOBUG_LOG_TARGET can be defined by the user to override all
defaults.

Log Flags

Flags are used to tell NoBug about subsystems/modules or even finer grained
parts of the code.

A Flag should be declared with

  * NOBUG_DECLARE_FLAG(flagname)

preferably in one of your headers

Further it must be defined with

  * NOBUG_DEFINE_FLAG(flagname)

or

  * NOBUG_DEFINE_FLAG_LIMIT(flagname, limit)

in one of your source files

There are also macros which take a 'parent' flag as parameter which is then
used to initialize the defaults from another flag

  * NOBUG_DEFINE_FLAG_PARENT(flagname, parent)

or

  * NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)

This can be used to create hierachies of flags

Next you should call

  * NOBUG_INIT_FLAG(flagname)

or

  * NOBUG_INIT_FLAG_LIMIT(flagname, default)

once at the start of your program for every flag.

For flags defined with NOBUG_DEFINE_FLAG(flagname) the defaults are initialized
as in the table above, while NOBUG_DEFINE_FLAG_LIMIT(flagname, level) is used
to initialize the default target (depending on build level) to limit. Calling
NOBUG_INIT_FLAG(flagname) is optional for limit initialized flags.

NOBUG_INIT_FLAG(flagname) parses the environment variable '$NOBUG_LOG' for
flagname, the syntax is as following:

logdecl_list --> logdecl, any( ',' logdecl_list).

logdecl --> flag, opt(limitdecl, any(targetdecl))

flag --> "identifier of a flag"

limitdecl --> ':', "LIMITNAME"

targetdecl --> '@', "targetname", opt(targetopts)

targetopts --> '(', "options for target", ')', opt(targetopts)

Roughly speaking, NOBUG_LOG contains a comma separated list of declarations for
flags which are the name of the flag followed by a limit which is written in
all uppercase letters and preceeded by a colon, followed by target declarations
which are names of the targets, introduced by a at sign. Target declarations
can have options in future which is not yet implemented. Limit and target
declarations are optional and then choosen from the defaults table above. These
defaults are currently just an guess what should be useable and might be
redefined in future.

Options

The Following options are implemented:

  * @ringbuffer
      + (file=filename) set filename backing the ringbuffer
        (size=nnn)      set size of the ringbuffer
        (append)        don't erase existing ringbuffer
        (keep)          keep file after application end
        (temp)          unlink file instantly at creation

    @console
      + (fd=n) redirect console output to fd n

    @file
      + (name=filename) log to filename
        (append)                        append to (existing) log

    @syslog
      + (ident=name) global prefix for syslog
        (cons)       log to system console if syslog is down
        (pid)        include pid in log
        (perror)     log to stderr as well

Examples:

NOBUG_LOG='flag,other'                        # set the limit of the default target a default limit (see table above)
NOBUG_LOG='flag:DEBUG'                        # set the limit of the default target to DEBUG
NOBUG_LOG='flag:DEBUG@console@syslog'         # set console and syslog limits for flag to DEBUG
NOBUG_LOG='flag:DEBUG,other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)' # trace 'other' to a persistent ringbuffer

There is a predefined flag NOBUG_ON which is always enabled.

Example code:

   1 #include "nobug.h"
   2 NOBUG_DEFINE_FLAG (test);
   3
   4 int
   5 main()
   6 {
   7   NOBUG_INIT_FLAG (test);
   8
   9   INFO (test, "Logging enabled");
  10   INFO (NOBUG_ON, "Always on");
  11 }

test it:

$ tcc -DEBUG_ALPHA -run example.c
example.c:10: debug: INFO: main: Always on

$ NOBUG_LOG=test tcc -DEBUG_ALPHA -run example.c
example.c:9: debug: INFO: main: Logging enabled
example.c:10: debug: INFO: main: Always on

C++ support

When used in C++ programms the following additional marocs are available:

  * NOBUG_CPP_DEFINE_FLAG(name)
    NOBUG_CPP_DEFINE_FLAG_PARENT(name, parent)
    NOBUG_CPP_DEFINE_FLAG_LIMIT(name, default)
    NOBUG_CPP_DEFINE_FLAG_PARENT_LIMIT(name, parent, default)

This macros statically initialize the flags at definition time, there is no
need to call NOBUG_INIT_FLAG().

The Logging Macros

These macros log with implicit Log Level, note that there are no more severe
levels than LOG_ERROR since these should be handled by Assertions in a
debugging library.

  * ERROR(flag, fmt, ...)
    ERROR_IF(expr, rflag, fmt, ...)
      + Application takes a error handling brach

    WARN(flag, fmt, ...)
    WARN_IF(expr, flag, fmt, ...)
      + Rare, handled but unexpected branch

    INFO(flag, fmt, ...)
    INFO_IF(expr, flag, fmt, ...)
      + Message about program progress

    NOTICE(flag, fmt, ...)
    NOTICE_IF(expr, flag, fmt, ...)
      + More detailed

    TRACE(flag, fmt, ...)
    TRACE_IF(expr, flag, fmt, ...)
      + Very fine grained messages

Note that TRACE corresponds to LOG_DEBUG, using 'DEBUG' could be ambiguous.

There is one generic LOG macro which takes the level explicitly:

  * LOG(flag, lvl, fmt, ...)
    LOG_IF(expr, flag, lvl, fmt, ...)

Dumping Datastructures

  * DUMP(flag, type, pointer, depth)
      + Dump a datastructure
    DUMP_IF(expr, flag, type, pointer, depth)
      + Dump datastructure if expr is true

How to write DUMP handlers

if you have a

   1 struct STRUCTNAME
   2 {
   3   int INTEGER_MEMBER;
   4   char * STRING_MEMBER;
   5   struct STRUCTNAME* next;
   6 }

then you define a function like:

   1 void
   2 nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
   3                        const int depth,
   4                        const char* file,
   5                        const int line,
   6                        const char* func)
   7 {
   8   // check for self != NULL and that the depth
   9   // limit did not exceed in recursive datastructures
  10   if (self && depth)
  11   {
  12     // use DUMP_LOG not LOG to print the data
  13     DUMP_LOG("STRUCTNAME %p: int is %d, string is %s", self,
  14                              self->INTEGER_MEMBER,
  15                              self->STRING_MEMBER);
  16     // now recurse with decremented depth
  17     nobug_STRUCTNAME_dump (self->next, depth-1, file, line, func);
  18   }
  19 }

now you can use the DUMP() macros within the code

   1 example()
   2 {
   3   struct STRUCTNAME foo;
   4   init(&foo);
   5   DUMP (my_flag, STRUCTNAME, &foo, 2);
   6 }

Dumping is by default done on level LOG_DEBUG, this can be overridden by
defining NOBUG_DUMP_LEVEL to some other level, further DUMP_IF is the only
enabled dumping macro for the RELEASE build level.

Source Annotations

One can tagging features as:

  * DEPRECATED(...)
      + Something which shouldn't be used in future.
    UNIMPLEMENTED(...)
      + important, not yet finished feature
    PLANNED(...)
      + planned for future feature
    FIXME(...)
      + known bug to be fixed later
    TODO(...)
      + enhancement to be done soon
    NOTREACHED
      + used to tag code-path which shall be never executed (defaults in switch
        statements, else NOTREACHED after series of if's)

The advantage of this tagging over plain source comments is that we can take
some actions if we run in such a tag at compile or runtime:

the action to be taken when such a macro is hit depends on the build level:

              ALPHA BETA         RELEASE
DEPRECATED    log   nothing      wont compile
UNIMPLEMENTED abort abort        wont compile
FIXME         log   wont compile wont compile
TODO          log   log          wont compile
PLANNED       log   nothing      nothing
NOTREACHED    abort abort        removed

Legend:

  * abort means first log and then abort
  * log will only log once for each sourceline (not on each hit)
  * wont compile will abort compilation with a error message
  * nothing optimized out, sane way
  * removed optimized out for performance reasons

Resource Tracking

With little effort, NoBug can watch all kinds of resources a program uses. This
becomes useful for resources which are distributed over a multithreaded
program. Resource tracking is only active in ALPHA builds and optimized out in
BETA and RELEASE builds.

Concepts

Resources are abstracted, NoBug has little knowledge about the semantics of a
resource, it only keeps records of resources and the code using it and ensures
basic constraints. Detailed usage checks of resource have to be done with other
NoBug facilities.

Resources are identified by a arbitrary identifier which is just a pointer and
if using threads, NoBug's thread identifier. Additionally a name, the type and
the source locations which announced the resource are stored.

Code which wants to use a resource calls a enter macro with its own identifier
and state, then might alter the state and finally a leave macro when finished
with it.

When a resource is used one has to pass one of three states:

  * NOBUG_RESOURCE_WAITING
      + For resources where acquisition could block (locks) you enter it with a
        WAITING state and as soon you aacquired it you change the state to one
        of the following.
  * NOBUG_RESOURCE_EXCLUSIVE
      + Acquired the resource exclusively, this means for NoBug that trying to
        get the resource again with the same identifier would be fatal, other
        parts of the program could still enter it.
  * NOBUG_RESOURCE_RECURSIVE
      + The resource might be entered multiple times from the same identifier,
        NoBug keeps a reference count and only deletes the record when the
        resource is left as much times the state was changed to
        NOBUG_RESOURCE_RECURSIVE

Possible state transitions:

  * [ResourceTr]

The macros

Resources are accessed through handles, these handles are defined with

  * RESOURCE_HANDLE(name)

This macro takes care that the declaration is optimized out in the same manner
the rest of the resource tracker would be disabled. You can still instantiate
handles as struct nobug_resource_record* in structures which must have a
constant size unconditional of the build level.

Resources are published by

  * RESOURCE_ANNOUNCE(flag, type, name, identifier, handle)

Resources must be unique, it is a fatal error when a resource it tried to be
announced more than one time.

  * 'flag' is nobug flag which turns logging on for this macro.
  * 'type' is a cstring which should denote the domain of the resource,
    examples are "file" "mutex" "lock" "database" and so on.
  * 'name' is the actual name of a named resource this is a cstring which
    together with type forms a unique identifier of the resource. 'type' and
    'name' must be available through the entire lifetime of the resource, using
    literal strings is recommended.
  * 'identifier' is a pointer which should be unique for this resource, any
    kind of pointer will suffice, it is only used for identification. In
    multithreaded applications the thread identifier becomes an additional
    identifier.
  * 'handle' is a nobug_resource_record* which will be initialized to point to
    the newly created resource.

When a resource becomes unavailable it is removed from the registry by

  * RESOURCE_FORGET(flag, handle)

The resource must still exist and no users must be attached to it, else a fatal
error is raised.

Code which wants to use a resource attaches to it by

  * RESOURCE_ENTER(flag, announced, name, identifier, state, handle)
  * 'flag' is nobug flag which turns logging on for this macro.
  * 'announced' is the handle set by RESOURCE_ANNOUNCE
  * 'name' is a free-form identifier
  * 'identifier' is some pointer which must be unique for the user of the
    resource (see above)
  * 'state' is the initial state, one of NOBUG_RESOURCE_WAITING,
    NOBUG_RESOURCE_EXCLUSIVE or NOBUG_RESOURCE_RECURSIVE
  * 'handle' is a nobug_resource_record* which will be initialized to the
    entering node.

For some uses one can change the state with

  * NOBUG_RESOURCE_STATE(flag, entered, state)
  * 'flag' is nobug flag which turns logging on for this macro.
  * 'entered' is the handle set by RESOURCE_ENTER
  * 'state' is the new state Note that only certain state transitions are
    allowed, see discussion/diagram above

When finished with using the resource you disconnect from it either with the
handle you initialized when entering it

  * RESOURCE_LEAVE(flag, handle)
  * 'flag' is nobug flag which turns logging on for this macro.
  * 'handle' is the handle you got while entering the resource.

or by looking it up in the announced resource by its identifier

  * RESOURCE_LEAVE_LOOKUP(flag, resource, identifier)
  * 'flag' is nobug flag which turns logging on for this macro.
  * 'resource' is the handle you got from announcing the resource.
  * 'identifier' is the pointer you gave it when creating it

Resources keep track of the thread which used them, you cant ANNOUNCE/FORGET
ENTER/LEAVE the same handle from different threads.

Just a simple example:

   1 NOBUG_DEFINE_FLAG_LIMIT(test, LOG_DEBUG);
   2
   3 void example()
   4 {
   5
   6   // define a mutex and announce it
   7   pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
   8   RESOURCE_HANDLE(resource)
   9   // 'example' is just a pointer to this function which suffices as unique id
  10   RESOURCE_ANNOUNCE(test, "mutex", "my_mutex", example, resource);
  11
  12   // the following would be actually done in a different thread in a real program
  13   RESOURCE_HANDLE(test, enter);                            // define a handle
  14   RESOURCE_ENTER_NAME(test, resource, "example", &enter, NOBUG_RESOURCE_WAITING, enter);
  15                                                            // announce that we want to use the resource
  16                                                            // &enter also suffices as unique pointer
  17   pthread_mutex_lock (&my_mutex);                          // this might block
  18   RESOURCE_STATE(test, enter, NOBUG_RESOURCE_EXCLUSIVE);   // we got it, now announce that
  19
  20   // program does something useful here
  21
  22
  23   pthread_mutex_lock (&my_mutex);                          // and instantly unlock
  24   RESOURCE_LEAVE(test, enter);                             // we don't need it anymore
  25
  26   // back in the main thread
  27   RESOURCE_FORGET(test, resource);                         // remove the resource from the public registry
  28 }

Deadlock Detection

The Resource Tracker is able to detect potential deadlocks. This is done by
learning the relations between locks (precedence). A possible deadlock results
in a log message and a fatal abort. Note that only waiting on resources can
lead to a deadlock. Deadlock detection is implemented in the Resource Tracker
and active in ALPHA builds.

Logging Control

Unless the user defines NOBUG_RESOURCE_LOGGING to 0 each of the above macros
will emit a log message at NOBUG_RESOURCE_LOG_LEVEL which defaults to
LOG_DEBUG.

Notes

The Resource Tracker is neither bullet-proof nor exact. There are small race
conditions in the time we announce/forget/enter/remove resources and doing the
actual call to a resource. These race conditions affect the reporting exactness
and are a design decision, for there is no danger for practical use.

More important is that the Resource Tracker relies on that announce/forget and
enter/leave are properly paired. The programmer should ensure that this is done
right, else it will become unusable. This will be addressed in future NoBug
versions.

The underlying resource-tracking library may report errors, all these errors
are fatal for NoBug and trigger an abort(). When such an error occurs the
Resource Tracker is left in a locked state, which is harmless and intended for
generating reports prior the abort.

Multithreading

It is important that NoBug protects certain operations with locks in
multithreaded programs. You have to ensure that 'HAVE_PTHREAD_H' is defined by
the configuration system and use the 'libnobugmt.a' library for linking. It is
particular important that libraries using NoBug are compiled with
'HAVE_PTHREAD_H' enabled when they are intended to be used in multithreaded
programs.

When Multithreading is used, log messages contain a identifier of the
originating thread. This identifier should be set by

  * NOBUG_THREAD_ID_SET(name)

right after thread creation. name is a string describing the purpose of the
thread. Nobug will assemble a unique identifier by appending a underscore and a
number to name, for example NOBUG_THREAD_ID_SET("gui") will result in a
identifier like "gui_5". When you don't set a thread identifier, then NoBug
assigns one automatically with the name 'thread' preprended if needed. Thread
identifiers are immutable once set.

For querying the thread identifier you use

  * NOBUG_THREAD_ID_GET

which will return a const char* to the thread id in multithreaded programs and
a pointer to a literal "" in singlethreaded programs.

Tool Macros

  * BACKTRACE(...)
      + Log a stacktrace
    ABORT
      + just calls abort()

Best Practices

<!> this section is very work in progress

Workflow

 1. Development
      + Write a testsuite, build your program with -O0 -g -DEBUG_ALPHA and run
        the testsuite under valgrind control. Hack until the program fits the
        requirements defined by the testsuite.
 2. Beta Test
      + Build with desired optimization level and -g -DEBUG_BETA and give the
        program to your beta testers.
 3. Release
      + Just build it with optimization and without -g -DEBUG_*

What and when to check

  * Add REQUIRE checks on your interfaces (incoming parameters). Especially if
    a argument might not cover the whole range of the underlying type.
  * Don't waste your and your CPU's time with unnecessary checks. The testsuite
    should validate your program. NoBug aids in debugging. You can add
    Postconditions (ENSURE) and Invariants when you have a bug somewhere and
    want to nail it down.
  * Added checks don't need to be removed.
  * When you use the CHECKED/UNCHECKED features then don't forget C scoping
    rules, tag things as CHECKED from the leaves to the root.

Tips & Tricks

  * TRACE(flagname) or TRACE_DBG(flagname) at the begin of every nontrivial
    function will easily log the progress of your application.
  * Trying a RELEASE build will abort on certain conditions (known BUG, TODO's,
    UNCHECKED code), you can use this to find these spots.

This Documentation is maintained at:

  * http://www.pipapo.org/pipawiki/NoBug/Documentation

NoBug/Documentation (last edited 2008-04-02 10:19:58 by 193)