Final Documentation makeover, fix plenty bugs
authorChristian Thaeter <ct@pipapo.org>
Thu, 19 Aug 2010 17:29:07 +0000 (19:29 +0200)
committerChristian Thaeter <ct@pipapo.org>
Thu, 19 Aug 2010 17:29:07 +0000 (19:29 +0200)
23 files changed:
doc/buildinstall.txt
doc/coverageintro.txt
doc/dumping.txt
doc/logconfiguration.txt
doc/logflags.txt
doc/logflagsenv.txt
doc/logformat.txt
doc/logging.txt
doc/macros.txt
doc/multithreading.txt
doc/nobug_manual.conf
doc/overview.txt
doc/parametertable.txt
doc/resourcedeadlock.txt
doc/resourcetracking.txt
doc/scopechecks.txt
doc/using.txt
doc/whichlibrary.txt
src/nobug.c
src/nobug.h
src/nobug_rbdump.c
src/nobug_resources.c
tests/test.sh

index a5aa305..b2c57e5 100644 (file)
@@ -90,8 +90,15 @@ After that you can build as above
 
  $ cd build && ../configure && make && make install
 
-This default pull will update from the 'master' branch which is meant to be an on-going
-stable version (latest release and bugfixes).
+This default pull will update from the 'master' branch which is meant to be an
+on-going stable version (latest release and bugfixes).
+
+Major new releases are assembled in the 'devel' branch, generally this is not
+considered production ready.
+
+All other branches are volatile and may be deleted or rebased anytime without
+further notice.
+
 
 HEAD-- What Is Installed;;
 
index 3ff98bb..914475d 100644 (file)
@@ -4,8 +4,8 @@ CAUTION: Fault coverage checking is an experimental feature!
 
 NoBug can automatically inject faults at instrumented points and permute
 through all potential error paths of an application by restarting it with the
-state from a former run. It can be used to provide information on whether
-particular error is adequately treated in an application. Fault coverage
+state from a former run. It can be used to provide information on whether a
+particular error is adequately treated in an application. Fault coverage
 checking is only available in ALPHA builds; it is optimized out in all other
 builds.
 
@@ -13,19 +13,18 @@ NOTE: This kind of testing is very expensive on performance.
 
 HEAD~ How Does Automatic Fault Injection Work?;;
 
-First, NoBug checks if the `NOBUG_COVERAGE` environment variable is set. If
-it is set, it must contain a space, comma or a semicolon separated list of 
-filenames which are the logs from a previous run. These logs are then parsed as 
-the states of the previous run, storing these in a lookup tree.
+First, NoBug checks if the `NOBUG_COVERAGE` environment variable is set. If it
+is set, it must contain a space, comma or a semicolon separated list of
+filenames which are the logs from a previous run. These logs are then parsed
+storing the old state in a lookup tree.
 
-The application can be started and will proceed to run as usual.
-When an instrumented coverage point is hit, its status is 
-checked against all states that have been recorded.
-Any failure point that is encountered causes a fault to be injected; the last
-seen but previously failed point will now be passed, all other fault injection
-points behave as in their previous run. This ensures that each successive run of 
-the application changes only one injection point and, thus, permutes through all
-possible code paths.
+The application will then proceed to run as usual. When an instrumented
+coverage point is hit, its status is checked against all states that have been
+recorded previously. Any failure point that is encountered for a first time
+causes a fault to be injected; the last seen but previously failed point will
+now be passed, all other fault injection points behave as in their previous
+run. This ensures that each successive run of the application changes only one
+injection point and, thus, permutes through all possible code paths.
 
 Fault injection points are identified by a 64bit hash over the backtrace
 (return addresses on the stack) leading to it. This means each unique way to
@@ -37,8 +36,8 @@ HEAD~ How to Invoke Fault-Coverage Checking;;
 
 Each fault-injection point emits a logging message about its identity and
 state, this logging uses the normal NoBug logging facilities. Thus, one can
-control logging with the `NOBUG_LOG` environment variable. Furthermore,
-fault coverage checking is only active when the `NOBUG_COVERAGE` environment
+control logging with the `NOBUG_LOG` environment variable. Furthermore, fault
+coverage checking is only active when the `NOBUG_COVERAGE` environment
 variable has been set to point to log files which are the results from a
 previous run. NoBug comes with a `tests/coverage.sh` example script which
 permutes through all possible error paths.
index 10430a6..b6fd182 100644 (file)
@@ -1,4 +1,4 @@
-HEAD- Dumping Data Structures;dumping;
+HEAD- Dumping Data Structures; dumping; dump complete datastructures
 
 One can write functions to dump complex data structures using the NoBug
 facilities. This is done by writing a custom function for each
@@ -13,14 +13,15 @@ A dump function has the prototype:
 void
 nobug_NAME_dump (const struct NAME* POINTER,
                  const int DEPTH,
-                 const struct nobug_context CONTEXT,
+                 const struct nobug_context context,
                  void* EXTRA);
 -------------------------------------------------------
 
-where NAME is the identifier for what you want to dump, POINTER is a pointer
-to the data to be dumped, DEPTH is an integer which will be decremented when
+where 'NAME' is the identifier for what you want to dump, 'POINTER' is a pointer
+to the data to be dumped, 'DEPTH' is an integer which will be decremented when
 recursing into the data structure dumper (your dump function does that, see
-below) to limit the recursion depth, CONTEXT is a source context generated by
-nobug when you call DUMP() and EXTRA is a pointer transparently passed around
-that you can use to store some additional state.
+below) to limit the recursion depth, 'context' is a source context generated by
+nobug when you call DUMP() and 'EXTRA' is a pointer transparently passed around
+that you can use to store some additional state. The 'context' variable must
+be named `context` because the `DUMP_LOG()` macro relies on this.
 
index af4706f..6fc2dcc 100644 (file)
@@ -6,7 +6,7 @@ Each log macro has an explicit or implicit log-level which
 correspondends to syslog levels. Logging is only emitted when the
 message is more severe or the same as a defined limit.
 
-INDEX Default levels for logging; logging level defaults; table showing defaults log levels
+INDEX Default levels for logging;loggingleveldefaults; table showing defaults log levels
 [frame="topbot",options="header"]
 |===============================================================================
 |            |ALPHA    |BETA    |RELEASE
@@ -20,7 +20,7 @@ INDEX Default levels for logging; logging level defaults; table showing defaults
 Depending on the build level, there is a default logging target and a default
 limit which is selected when the user doesn't specify one.
 
-PARA The following default limits are;limitslogging;default logging limits
+PARA The following default limits are;limitslogging;default logging limits
 
   In *ALPHA* builds::
      `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
@@ -29,7 +29,7 @@ PARA The following default limits are;limits, logging;default logging limits
   In *RELEASE* builds::
      `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
 
-PARA The default targets are;targetslogging;default logging targets
+PARA The default targets are;targetslogging;default logging targets
 
   In *ALPHA* builds::
     `NOBUG_LOG_TARGET_ALPHA` defaulting to `NOBUG_TARGET_CONSOLE`
index 5cfdc3f..5b7127a 100644 (file)
@@ -53,6 +53,26 @@ These macros statically initialize the flags when they are defined, there is no
 need to call `NOBUG_INIT_FLAG()` (see below).
 
 
+HEAD^ Logging Flag Initialization; INIT_FLAG; initialize log flags from environment
+
+After a flag has been declared and defined, it has to be initialised:
+
+ NOBUG_INIT_FLAG(flagname)
+
+or
+
+ NOBUG_INIT_FLAG_LIMIT(flagname, default)
+
+Use either of these macros once at the begining your program for each flag.
+This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
+initializing the given flag dynamically.
+
+For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
+initialized as in the xref:loggingleveldefaults[table above], while
+`NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
+target (depending on build level) to `level`.
+
+
 HEAD^ Force declarations only; NOBUG_DECLARE_ONLY; force flag declarations
 
 When `NOBUG_DECLARE_ONLY` defined to be `1` then all flag definitions here become
@@ -95,23 +115,3 @@ NOBUG_DEFINE_FLAG(example);
 ...
 ----
 
-
-HEAD^ Logging Flag Initialization; INIT_FLAG; initialize log flags from environment
-
-After a flag has been declared and defined, it has to be initialised:
-
- NOBUG_INIT_FLAG(flagname)
-
-or
-
- NOBUG_INIT_FLAG_LIMIT(flagname, default)
-
-Use either of these macros once at the begining your program for each flag.
-This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
-initializing the given flag dynamically.
-
-For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
-initialized as in the xref:loggingleveldefaults[table above], while
-`NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
-target (depending on build level) to `level`.
-
index fdd86d4..9a44fcc 100644 (file)
@@ -1,7 +1,7 @@
 HEAD~ Controlling what gets logged; NOBUG_ENV; environment variable for loging control
 
 The `NOBUG_INIT_FLAG...` series of macros parse the environment variable
-'$NOBUG_LOG'. This enviromnet variable iis thus used to configure what is
+'$NOBUG_LOG'. This enviromnet variable is thus used to configure what is
 logged at runtime. Its syntax is as following:
 
 [source,prolog]
@@ -29,7 +29,7 @@ xref:loggingleveldefaults[table above]. The defaults presented here are
 currently an approximation of what might be viable. The default values used
 here may be redefined in a future release.
 
-HEAD^ Targets and Options; logging options; configure what gets logged
+HEAD^ Targets and Options; loggingoptions; configure what gets logged
 
 The Following options are available:
 
index 2c1c1fc..01fa81e 100644 (file)
@@ -48,7 +48,8 @@ The components are delimited by ": " or in one case by "! " are as following:
    or demangled C++ method. The reason for this is that neither is well
    specified an may yield to non unique results which may even interfere with
    the logging format syntax and thus make it very unreliable to write tools
-   to process logs.
+   to process logs. Some contexts dont provide a function name, a "-" is used
+   then.
 
  . *Message* +
    The rest of the log line is the user-defined and optional message part.
index 433c1b2..2f23f78 100644 (file)
@@ -1,8 +1,8 @@
-HEAD- Logging;;
+HEAD- Logging Concepts; loggingconcepts; destinations for logging output
 
-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.
+Nearly all NoBug Macros emit some xref:logformat[log message]. NoBug gives
+the user fine grained control over these log messages to display only
+interesting information without loosing details.
 
 Log messages can be routed to various destinations.  The following destintaions
 are available:
@@ -32,9 +32,10 @@ are available:
 Each log message 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, ...). This is referred to as 'channels'
-in other logging systems.
+All non-fatal messages are associated with a programmer defined flag
+describing the source of the message (subsystem, module, ...). This is
+referred to as 'channels' in other logging systems. xref:logflags[Flags] make
+it possible to configure logging in much detail at runtime.
 
 Putting this all together: A user can define which source/flag will be logged at
 what priority level and to which destination. To make this all easier, NoBug
index 95d7ac4..158aa93 100644 (file)
@@ -1,4 +1,4 @@
-HEAD- Macros;;
+HEAD- Macros Overview; macros; concepts and parameters for macros
 
 The NoBug interface is almost completely implemented using
 preprocessor macros. This is required because NoBug uses the
@@ -6,8 +6,8 @@ preprocessor macros. This is required because NoBug uses the
 log information on the current file, line number and function.
 Moreover, all the flat namespace uppercase identifiers make it easy
 to recognise the macros in source code.
-
 INDEX DISABLE_SHORTNAMES; DISABLE_SHORTNAMES; require NOBUG_ prefix everywhere
+
 All macros are available without condition with a `NOBUG_...` prefix. Many
 macros (the common cases) are also available without this prefix as a
 convenience, however macros without this prefix must not have been previously
index 5bd73d4..3849c76 100644 (file)
@@ -19,7 +19,7 @@ PARA NOBUG_THREAD_ID_SET; THREAD_ID_SET; set or reset thread id
 
 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
+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 may be reset with a new call to this macro.
 
index af92260..b5924bd 100644 (file)
@@ -41,7 +41,6 @@
 
 //=macros
 
-
 //=parametertable
 
 //=srccontext
@@ -110,3 +109,17 @@ Look at into the 'tests/' folder about how to apply this.
 //=credits
 
 
+Lost & Found:
+
+
+Release builds remove all assertions, but 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.
+
+
+
+
index a372b25..5671f4b 100644 (file)
@@ -14,6 +14,7 @@ The following features are provided by NoBug:
     detecting misuse
   * Detecting potential deadlocks
   * Simulate errors by injecting faults
+  * Coverage checking to find out if all (instrumentated) errors are properly handled
   * Additionally, the NoBug project is used to maintain a script and
     some tools to setup testsuites
 
@@ -24,6 +25,7 @@ will be an integral part of your application making it possible to gather
 debugging data for each stage of the application development, including
 collecting debugging info for finally deployed applications.
 
+
 PARA What NoBug can't do;;
 
 NoBug is a (macro-)library, it is not a C/C++ language extension. This
@@ -33,3 +35,11 @@ part of the program itself, it is affected by memory corruption.
 Certain kinds of misuse may introduce new bugs (assert expressions with
 side effects for example).
 
+
+HEAD~ Support; mailinglist; how to reach the NoBug developers
+
+When you need help with NoBug, have some ideas about potential features or
+think you found a bug, then you can contact the NoBug community and developers
+by sending mail to the NoBug mailinglist. Subscription is available at
+http://lists.pipapo.org/cgi-bin/mailman/listinfo/nobug[].
+
index de23b45..7f56b28 100644 (file)
@@ -3,11 +3,11 @@ HEAD~ Parameters types;;
 We use names for parameters which describe their type. These names are
 orthogonal through all macro definitions.
 
-[frame="topbot"]
+[cols="1,5",frame="topbot"]
 |==============================================================================
 |`when`    |Assertion is only performed if expression `when` is true at runtime
 |`expr`    |Test without side effects
-|`flag`    |Flag to enable custom logging groups
+|`flag`    |Destination flag for control logging at runtime
 |`type`    |Data type to be checked as a single identifier name
 |`pointer` |Pointer to type
 |`lvl`     |Log level
index 23940dc..6698850 100644 (file)
@@ -2,10 +2,12 @@ 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 and optimized out on any other build level.
+learning the relations between locks (precedence) and watching the order in
+which resources are acquired. It has some heuristics to detect certain
+patterns which are deadlock free. 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 and optimized out on any other build level.
 
 For details about the deadlock detection algorithm see
 xref:deadlockdetection[Appendix: Resource Tracking Alorithm].
index 8e26b44..d09edde 100644 (file)
@@ -11,23 +11,23 @@ ALPHA builds.
 HEAD++ Concepts;;
 
 Resources are an abstract entity for NoBug, which has little knowledge about the
-semantics of a resource; it only keeps records of resources and the code using 
-these resources and ensures basic constraints. More detailed checks on resource 
+kinds of resources; it only keeps records of resources and the code using
+these resources and ensures basic constraints. More detailed checks on resource
 usage have to be done with other NoBug facilities.
 
 Resources are identified by an arbitrary identifier which is just a
 pointer. Additionally a name, the type and the source locations which
 registered the resource are stored.
 
-Code which requiring to use a resource, calls an 'enter' macro, supplying 
-an identifier and state. The state can be altered. Thereafter a 'leave' macro is
+Code which requiring to use a resource, calls an 'ENTER' macro, supplying
+an identifier and state. The state can be altered. Thereafter a 'LEAVE' macro is
 used when the the code is finished with the resources.
 
 When a resource is used, one has to pass one of these states:
 
   `NOBUG_RESOURCE_WAITING`::
         For resources which might need to be blocked (locks),  enter with a
-        WAITING state first, as soon at the resource is acquired, change the 
+        WAITING state first, as soon at the resource is acquired, change the
         state to one of the following.
   `NOBUG_RESOURCE_EXCLUSIVE`::
         Acquired the resource exclusively. The resource must not be acquired
@@ -39,8 +39,7 @@ When a resource is used, one has to pass one of these states:
         The resource might be entered multiple times from any thread
         with this state.
 
-Possible state transitions:
-
+//.Possible state transitions
 ["graphviz", "resource-transitions.eps"]
 ---------------------------------------------------------------------
 strict digraph G
index af9b983..db15d06 100644 (file)
@@ -6,3 +6,21 @@ The programmer can tag any scope as `UNCHECKED` or `CHECKED`. In *ALPHA* and *BE
 builds, a global `UNCHECKED` is implied. In *RELEASE* builds, `UNCHECKED` scopes are
 not allowed.
 
+[source,C]
+-------
+int
+myfunc()
+{
+   /* the outer scope of this function is not validated yet*/
+   UNCHECKED;
+
+   if (...)
+   {
+      /* everything in this scope is considered ok */
+      CHECKED;
+      ...
+   }
+   return ...;
+}
+-------
+
index 7ed4e5c..66e2a88 100644 (file)
@@ -1,18 +1,13 @@
 HEAD- Using NoBug;;
 
 Your application will have to include the header file 'nobug.h' before NoBug
-can be used:
-
- #include <nobug.h>
-
-
-Once you've included the NoBug API in your application, you'll then have to select
-a 'build-level'.  Build-levels are discussed later, c.f.,
-xref:buildlevel[buildlevel].   Build-levels are used to define the amount of
-information NoBug provides to you.  Maximum information is generally required while
-developing an application and the ALPHA build-level is most apropriate during
-this phase; whereas the released phase of an application will usually only require
-sparse information, for which the RELEASE build-level has been conceived.
+can be used. Prior including this, a Build-level has to be choosen,
+Build-levels are discussed later, c.f., xref:buildlevel[buildlevel].
+Build-levels are used to define the amount of information NoBug provides to
+you. Maximum information is generally required while developing an application
+and the ALPHA build-level is most apropriate during this phase; whereas the
+released phase of an application will usually only require sparse information,
+for which the RELEASE build-level has been conceived.
 
 A build-level must always be specified, otherwise the compiler will complain
 while attempting to compile your application.  You can specifiy a build level in
@@ -34,7 +29,7 @@ single-threaded applications:
 
 [source,sh]
 ----------------
-gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
+gcc -o mybinary  $(WHATEVER_FLAGS) \
        mymodules.o ... -lnobug
 ----------------
 
@@ -49,11 +44,10 @@ gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
        mymodules.o -lnobugmt
 ----------------
 
-Both libraries must be initialised  before they can be used.  There are a number
-of different ways to initialise the NoBug libraries.  One of the easiest ways
-to initialise the NoBug libraries is to use the `NOBUG_INIT` macro, which must
-be used before any features can be used or any thread is created. This is
-discussed in more detail in the xref:multithreading[multithreading] chapter.
+The NoBug libraries must be initialised before they can be used. To initialise
+it call the `NOBUG_INIT` macro, which must be used before any NoBug features
+can be used or any thread is created. This is discussed in more detail in the
+xref:multithreading[multithreading] chapter.
 
 So putting all this together, our application using NoBug might look something
 like the following:
@@ -74,7 +68,6 @@ int main()
 
 
 
-
 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
 included.
 
@@ -155,7 +148,7 @@ PKG_CHECK_MODULES(VALGRIND, [valgrind],
         AC_DEFINE(HAVE_VALGRIND_H))
 
 # finally check for nobug itself, multithreaded here
-PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= ],
+PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= 201006.1],
         AC_DEFINE(HAVE_NOBUGMT_H),
         AC_MSG_ERROR([NoBug pkg-config metadata missing])
 )
index 3453ded..170797b 100644 (file)
@@ -11,13 +11,9 @@ uses multiple dynamic libraries which use NoBug or you build a dynamic
 library, then you have to link against the dynamic library.
 
 You can use the `pkg-config` tool to gather information about NoBug in
-your build system.
+your build system. For example you can query the NoBug version which is
+installed on your system:
 
-Release builds remove all assertions, but 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.
+ $ pkg-config --modversion nobug
+ 201006.1
 
index 1c4c19b..e09fbfd 100644 (file)
@@ -61,7 +61,7 @@ struct nobug_flag nobug_flag_NOBUG_ANN =
 {NULL, NULL, 0, {LOG_DEBUG, LOG_DEBUG, LOG_DEBUG, -1, LOG_WARNING}, NULL, NULL, NULL};
 
 /*
-//predefflags PARA nobug; nobugflag; log flag used to show nobug actions
+//predefflags PARA nobug; nobugflag; log flag used to show nobug actions
 //predefflags
 //predefflags Actions on NoBug itself will be logged under the `nobug` flag itself.
 //predefflags To see whats going on you can enable it with `NOBUG_LOG=nobug:TRACE`.
index 7d8ba6b..ac86975 100644 (file)
 
 
 /*
-//assertions HEAD- Assertions;;
+//assertions HEAD- Macros for Assertions; assertions; assert the state of the application
 //assertions
-//assertions The assertion set of macros provide a convenient status check
-//assertions on whether to continue running, or gracefully exit execution
-//assertions as some condition was not fulfilled.
+//assertions The assertion set of macros provide a convenient status check on whether
+//assertions to continue running, or abort execution as some condition was not fulfilled.
+//assertions Assertion failures are fatal and must abort the application immediately by
+//assertions calling the xref:ABORT[NOBUG_ABORT] macro which in turn may call a user defined
+//assertions xref:abortcallback[abort hook].
 //assertions
 //assertions PARA CHECK; CHECK; unnconditional assertion for test suites
 //assertions
 
 
 /*
-//logmacros HEAD- Macros That Log Information ;;
+//logmacros HEAD- Macros That Log Information; logging; generate logging messages
 //logmacros
 //logmacros Logging targets a flag (except for `ECHO`) and is done at a log-level related to syslog levels.
 //logmacros
 //logmacros  NOBUG_INFO_IF_CTX(when, flag, context, ...)
 //logmacros
 //logmacros It may be benificial to output information at various
-//logmacros locations throughout the code, e.g., messages on programme
+//logmacros locations throughout the code, e.g., messages on programm
 //logmacros progress.
 //logmacros
 */
 //logmacros
 //logmacros The same as the NOTICE() macros, except very fine-grained information.
 //logmacros a common use case is to put just `TRACE(debugflag)` just at the begin of every
-//logmacros non-trivial function. This allows to see fine grained application progress in the log.
+//logmacros non-trivial function. This allows to watch fine grained application progress in the log.
 //logmacros
 //logmacros NOTE: `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
 //logmacros
 //annotations
 //annotations Obsolete, buggy or precarious code can be marked in the code itself in
 //annotations comments at the location where the code occurs.  However these code
-//annotations locations can be easily overlooked, especially in large projects. The
-//annotations advantage of this tagging scheme is that it provides an additional
+//annotations locations can be easily overlooked, especially in large projects. NoBug
+//annotations provides macros to tag code with such annotations. This provides an additional
 //annotations instrument to alert or remind the programmer that there is still dubious
 //annotations code embedded in the application. This tagging scheme not only informs
 //annotations the programmer at compile time that there is code in the application
@@ -939,7 +941,7 @@ NOTREACHED      abort           abort           nothing
 
 
 /*
-//coverage HEAD- Coverage checking Macros;;
+//coverage HEAD~ Coverage checking Macros;;
 //coverage
 //coverage PARA COVERAGE_FAULT; COVERAGE_FAULT; coverage fault injection, statement
 //coverage
@@ -1279,10 +1281,10 @@ NOTREACHED      abort           abort           nothing
 /*
 //resourcemacros PARA RESOURCE_ANNOUNCE; RESOURCE_ANNOUNCE; publish new resources
 //resourcemacros
-//resourcemacros  RESOURCE_ANNOUNCE(flag, type, name, identifier, handle)
-//resourcemacros  NOBUG_RESOURCE_ANNOUNCE_RAW(flagptr, type, name, ptr, handle)
+//resourcemacros  RESOURCE_ANNOUNCE(flag, type, name, identifier, handle){}
+//resourcemacros  NOBUG_RESOURCE_ANNOUNCE_RAW(flagptr, type, name, ptr, handle){}
 //resourcemacros  NOBUG_RESOURCE_ANNOUNCE_RAW_CTX(flagptr, type, name,
-//resourcemacros                                  ptr, handle, context)
+//resourcemacros                                  ptr, handle, context){}
 //resourcemacros
 //resourcemacros Publishes resources.
 //resourcemacros
@@ -1292,12 +1294,11 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros      a string which should denote the domain of the resource,
 //resourcemacros      examples are "file", "mutex", "lock", "database" and so on
 //resourcemacros  `name`::
-//resourcemacros      the actual name of a named resource this as string which
-//resourcemacros      together with type forms a unique identifier of the resource. `type` and
+//resourcemacros      the actual name of a named resource this as string. `type` and
 //resourcemacros      `name` must be available through the entire lifetime of the resource, using
 //resourcemacros      literal strings is recommended
 //resourcemacros  `identifier`::
-//resourcemacros      a pointer which should be unique for this resource, any
+//resourcemacros      a pointer which must be unique for this resource, any
 //resourcemacros      kind of pointer will suffice, it is only used for identification. In
 //resourcemacros      multithreaded applications the thread identifier becomes an additional
 //resourcemacros      identifier
@@ -1308,8 +1309,8 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros Resources must be unique, it is a fatal error when a resource it tried to be
 //resourcemacros announced more than one time.
 //resourcemacros
-//resourcemacros 'RESOURCE_ANNOUNCE()' acts like the head of a C loop statement, it ties to the following
-//resourcemacros (block-) statement. Leaving and the user defined following statement are atomic.
+//resourcemacros `RESOURCE_ANNOUNCE()` acts like the head of a C loop statement, it ties to the following
+//resourcemacros (block-) statement which will be handled atomic.
 //resourcemacros This statement must not be left by break, return or any other kind of jump.
 //resourcemacros
 */
@@ -1349,9 +1350,9 @@ NOTREACHED      abort           abort           nothing
 /*
 //resourcemacros PARA RESOURCE_FORGET; RESOURCE_FORGET; remove resources
 //resourcemacros
-//resourcemacros  RESOURCE_FORGET(flag, handle)
-//resourcemacros  NOBUG_RESOURCE_FORGET_RAW(flagptr, handle)
-//resourcemacros  NOBUG_RESOURCE_FORGET_RAW_CTX(flagptr, handle, context)
+//resourcemacros  RESOURCE_FORGET(flag, handle){}
+//resourcemacros  NOBUG_RESOURCE_FORGET_RAW(flagptr, handle){}
+//resourcemacros  NOBUG_RESOURCE_FORGET_RAW_CTX(flagptr, handle, context){}
 //resourcemacros
 //resourcemacros Removes resources that have become unavailable from the registry.
 //resourcemacros
@@ -1363,8 +1364,8 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros The resource must still exist and no users must be attached to it, else a fatal
 //resourcemacros error is raised.
 //resourcemacros
-//resourcemacros 'RESOURCE_FORGET()' acts like the head of a C loop statement, it ties to the following
-//resourcemacros (block-) statement. Leaving and the user defined following statement are atomic.
+//resourcemacros `RESOURCE_FORGET()` acts like the head of a C loop statement, it ties to the following
+//resourcemacros (block-) statement which will be handled atomic.
 //resourcemacros This statement must not be left by break, return or any other kind of jump.
 //resourcemacros
 */
@@ -1435,8 +1436,8 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros PARA RESOURCE_RESET; RESOURCE_RESET; reset a single resource to a pristine state
 //resourcemacros
 //resourcemacros  RESOURCE_RESET(flag, handle)
-//resourcemacros  NOBUG_RESOURCE_RESETALL_RAW(flagptr, handle)
-//resourcemacros  NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, handle, context)
+//resourcemacros  NOBUG_RESOURCE_RESET_RAW(flagptr, handle)
+//resourcemacros  NOBUG_RESOURCE_RESET_RAW_CTX(flagptr, handle, context)
 //resourcemacros
 //resourcemacros Sometimes the resource tracker can give false positives when it finds a locking order violation
 //resourcemacros while the programmer knows that this will never happen in the real program, because for example
@@ -1470,9 +1471,9 @@ NOTREACHED      abort           abort           nothing
 /*
 //resourcemacros PARA RESOURCE_ENTER; RESOURCE_ENTER; claim a resource
 //resourcemacros
-//resourcemacros  RESOURCE_ENTER(flag, announced, user, state, handle)
+//resourcemacros  RESOURCE_ENTER(flag, announced, user, state, handle){}
 //resourcemacros  NOBUG_RESOURCE_ENTER_CTX(flag, resource, user, state,
-//resourcemacros                           handle, context)
+//resourcemacros                           handle, context){}
 //resourcemacros
 //resourcemacros Acquire a resource.
 //resourcemacros
@@ -1481,7 +1482,7 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros `announced`::
 //resourcemacros     the handle set by `RESOURCE_ANNOUNCE`
 //resourcemacros `user`::
-//resourcemacros     a free-form identifier
+//resourcemacros     a literal string defining the purpose
 //resourcemacros `state`::
 //resourcemacros     the state to enter
 //resourcemacros `handle`::
@@ -1489,7 +1490,7 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros     entering node
 //resourcemacros
 //resourcemacros `RESOURCE_ENTER()` acts like the head of a C loop statement, it ties to the following
-//resourcemacros (block-) statement. Leaving and the user defined following statement are atomic.
+//resourcemacros (block-) statement which will be handled atomic.
 //resourcemacros This statement must not be left by break, return or any other kind of jump.
 //resourcemacros
 */
@@ -1531,8 +1532,8 @@ NOTREACHED      abort           abort           nothing
 
 //resourcemacros PARA RESOURCE_WAIT; RESOURCE_WAIT; wait for a resource to become available
 //resourcemacros
-//resourcemacros  RESOURCE_WAIT(flag, resource, user, handle)
-//resourcemacros  NOBUG_RESOURCE_WAIT_CTX(flag, resource, user, handle, context)
+//resourcemacros  RESOURCE_WAIT(flag, resource, user, handle){}
+//resourcemacros  NOBUG_RESOURCE_WAIT_CTX(flag, resource, user, handle, context){}
 //resourcemacros
 //resourcemacros This is just an alias for
 //resourcemacros
@@ -1558,8 +1559,8 @@ NOTREACHED      abort           abort           nothing
 
 //resourcemacros PARA RESOURCE_TRY; RESOURCE_TRY; wait for a resource to become available
 //resourcemacros
-//resourcemacros  RESOURCE_TRY(flag, resource, user, handle)
-//resourcemacros  NOBUG_RESOURCE_TRY_CTX(flag, resource, user, handle, context)
+//resourcemacros  RESOURCE_TRY(flag, resource, user, handle){}
+//resourcemacros  NOBUG_RESOURCE_TRY_CTX(flag, resource, user, handle, context){}
 //resourcemacros
 //resourcemacros This is just an alias for
 //resourcemacros
@@ -1579,10 +1580,10 @@ NOTREACHED      abort           abort           nothing
 /*
 //resourcemacros PARA RESOURCE_STATE; RESOURCE_STATE; change the state of a resource
 //resourcemacros
-//resourcemacros  RESOURCE_STATE(flag, entered, state)
-//resourcemacros  NOBUG_RESOURCE_STATE_CTX(flag, state, entered, context)
-//resourcemacros  NOBUG_RESOURCE_STATE_RAW(flagptr, state, entered)
-//resourcemacros  NOBUG_RESOURCE_STATE_RAW_CTX(flagptr, nstate, entered, context)
+//resourcemacros  RESOURCE_STATE(flag, entered, state){}
+//resourcemacros  NOBUG_RESOURCE_STATE_CTX(flag, state, entered, context){}
+//resourcemacros  NOBUG_RESOURCE_STATE_RAW(flagptr, state, entered){}
+//resourcemacros  NOBUG_RESOURCE_STATE_RAW_CTX(flagptr, state, entered, context){}
 //resourcemacros
 //resourcemacros Changes resource's state.
 //resourcemacros
@@ -1595,7 +1596,7 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros     the handle set by `RESOURCE_ENTER`
 //resourcemacros
 //resourcemacros `RESOURCE_STATE()` acts like the head of a C loop statement, it ties to the following
-//resourcemacros (block-) statement. Leaving and the user defined following statement are atomic.
+//resourcemacros (block-) statement which will be handled atomic.
 //resourcemacros This statement must not be left by break, return or any other kind of jump.
 //resourcemacros
 */
@@ -1657,7 +1658,7 @@ NOTREACHED      abort           abort           nothing
 //resourcemacros     the handle you got while entering the resource
 //resourcemacros
 //resourcemacros `RESOURCE_LEAVE()` acts like the head of a C loop statement, it ties to the following
-//resourcemacros (block-) statement. Leaving and the user defined following statement are atomic.
+//resourcemacros (block-) statement which will be handled atomic.
 //resourcemacros This statement must not be left by break, return or any other kind of jump.
 //resourcemacros
 //resourcemacros .How to use it
@@ -2250,13 +2251,29 @@ NOBUG_IFNOT(NOBUG_USE_VALGRIND, 0)
 //toolmacros
 //toolmacros Sometimes it is useful to have initializer code only in *ALPHA* builds, for example when you
 //toolmacros conditionally include resource handles only in *ALPHA* versions. An initializer can then
-//toolmacros use this macros to append a comman and something else only in *ALPHA* builds as in:
+//toolmacros use this macros to append a comma and something else only in *ALPHA* builds as in:
 //toolmacros
 //toolmacros [source,C]
 //toolmacros ----
 //toolmacros struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
 //toolmacros ----
 //toolmacros
+//toolmacros Becomes the following in *ALPHA* builds
+//toolmacros
+//toolmacros [source,C]
+//toolmacros ----
+//toolmacros struct foo = {"foo", "bar", NULL};
+//toolmacros ----
+//toolmacros
+//toolmacros and
+//toolmacros
+//toolmacros [source,C]
+//toolmacros ----
+//toolmacros struct foo = {"foo", "bar"};
+//toolmacros ----
+//toolmacros
+//toolmacros in *BETA* and *RELEASE* builds.
+//toolmacros
 */
 #define NOBUG_COMMA ,
 #define NOBUG_ALPHA_COMMA(something) NOBUG_IF_ALPHA(NOBUG_COMMA something)
@@ -2737,7 +2754,7 @@ extern unsigned long long nobug_counter;
 //callbacks
 //callbacks NoBug provides callbacks, applications can use these
 //callbacks to present logging information in some custom way or hook some special processing in.
-//callbacks The callbacks are initialized to NULL and never modified by NoBug, its the solve responsibility
+//callbacks The callbacks are initialized to NULL and never modified by NoBug, it is the sole responsibility
 //callbacks of the user to manage them.
 //callbacks
 //callbacks CAUTION: There are certain constraints what and what not can be done in callbacks
index 27ec47e..0813ff5 100644 (file)
 //rbdump ringbuffer. It is invoked with the filename of the ringbuffer, the content is then
 //rbdump printed to stdout.
 //rbdump
+//rbdump  $ NOBUG_LOG='test:TRACE@ringbuffer(file=test.rb)(keep)' ./a.out
+//rbdump  0000000004: TRACE: example.c:11: -: main: Always on
+//rbdump  $ nobug_rbdump test.rb
+//rbdump  0000000003: TRACE: example.c:10: -: main: Logging
+//rbdump  0000000003! TRACE: example.c:10: -: main:  enabled
+//rbdump
 */
 int
 main(int argc, char* argv[])
index f572402..3b87d4b 100644 (file)
@@ -384,7 +384,7 @@ nobug_resource_node_new (struct nobug_resource_record* resource,
 //dlalgo Every new locking path discovered is stored as 'resource_node' structures which refer to the associated
 //dlalgo 'resource_record'.
 //dlalgo
-//dlalgo Threads keep a trail of 'resource_user' strcutures for each resource entered. This 'resource_user' struct
+//dlalgo Threads keep a trail of 'resource_user' structures for each resource entered. This 'resource_user' struct
 //dlalgo refer to the 'resource_nodes' and thus indirectly to the associated 'resource_record'.
 //dlalgo
 //dlalgo The deadlock checker uses this information to test if the acqusition of a new resource would yield a
index 3d0dd36..beec03c 100755 (executable)
@@ -68,7 +68,7 @@ LOGSUPPRESS='^\(\*\*[0-9]*\*\* \)\?[0-9]\{10,\}[:!] \(TRACE\|INFO\|NOTICE\|WARNI
 
 #config HEAD^ Resource Limits; ulimit, tests; constrain test resource limits
 #config
-#config It is possible to set some limits for tests to protect the system against really broken cases.
+#config It is possible to set some limits for tests to protect the system against broken cases.
 #config Since running under valgrind takes consinderable more resources there are separate variants for
 #config limits when running under valgrind.
 #config INDEX LIMIT_CPU; LIMIT_CPU; limit the cpu time
@@ -123,7 +123,7 @@ arg0="$0"
 TESTDIR="$(dirname "$arg0")"
 
 
-#libtool HEAD Libtool; libtool; support for libtool
+#libtool HEAD~ Libtool; libtool; support for libtool
 #libtool
 #libtool When test.sh detects the presence of './libtool' it runs all tests with
 #libtool `./libtool --mode=execute`.