diff options
Diffstat (limited to 'doc/Diagnostic-Logging.md')
-rw-r--r-- | doc/Diagnostic-Logging.md | 88 |
1 files changed, 0 insertions, 88 deletions
diff --git a/doc/Diagnostic-Logging.md b/doc/Diagnostic-Logging.md deleted file mode 100644 index e71e737..0000000 --- a/doc/Diagnostic-Logging.md +++ /dev/null @@ -1,88 +0,0 @@ -# The Hierarchical Log Library (`hlog`) - -A program uses the hierarchical log library, `hlog`, to organize -its diagnostic messages into categories and subcategories and to -turn on and off message categories to produce the most useful -diagnostic trace. - -A typical program will define one or more log *outlets*. An outlet -is a named target for diagnostic messages. Each outlet has a *state* -(*on*, *off*, or *pass*) and at most one *parent outlet*. Usually, the -parent-child relationships between outlets form a tree rooted at the -outlet "all", which is supplied by the library. Outlets may form a -"forest" if a program supplies its own root outlets. - -A program sends messages to an outlet using `hlog` API calls. -Messages sent to an outlet that is *on* are copied to the error -stream. Messages sent to an outlet that is *off* are discarded. -When a message is sent to an outlet in *pass* state, the `hlog` -uses the outlet ancestors to decide what to do with the message. - -## Sending messages with `hlog_fast` - -A program calls `hlog_fast(outlet name, format string, ...)` to -write a formatted message to the named outlet. `hlog_fast` uses -the outlet state to do decide what to do with the message. If the -outlet is *on*, then the message is written to the standard error -stream. If the outlet is *off*, then the message is discarded. -If the outlet is in state *pass*, and the outlet has no parent, -then the message is discarded. If the outlet does have a parent, -then `hlog_fast` looks at the parent state and decides whether to -discard, write, or recurse. - -`hlog_fast` precedes each diagnostic message with a timestamp (decimal -seconds with 9 digits right of the decimal point), a colon, and a single -space. Each message is followed with a newline ("\n"). The effective -timestamp resolution may be much less than one nanosecond. Timestamps -increase monotonically. The timestamp origin is currently unspecified. - -## Defining log outlets - -`hlog` provides macros for declaring outlets, and for statically -configuring an outlet, its parent, and its initial state. - -Use `HLOG_OUTLET_DECL(name)` to declare shared outlets in header -files. `HLOG_OUTLET_DECL(name)` declares an `extern` symbol. -There must not be any quotation marks on *name*. - -Use `HLOG_OUTLET_SHORT_DEFN(name, parent)` to define an outlet with the -given name and parent in state *pass*. There must not be any quotation -marks on *name*. - -Use `HLOG_OUTLET_MEDIUM_DEFN(name, parent, state)` to define an outlet -with the given name, parent, and state. The state is given by an -`hlog_outlet_state_t`, one of `HLOG_OUTLET_S_ON`, `HLOG_OUTLET_S_OFF`, -or `HLOG_OUTLET_S_PASS`. There must not be any quotation marks on -*name*. - -## Enabling and disabling outlets with the environment - -An environment variable, `HLOG`, sets initial outlet states for a -program. If `HLOG` may be set to the empty string, in which case -outlet states stay at their program defaults. `HLOG` may also be -set to one or more *outlet name*=*state* pairs, separated by either -whitespace or commas. *state* is one of *pass*, *on*, or *off*, -and *outlet-name* is a string matching `[_a-zA-Z][_a-zA-Z0-9]*`. -For example, to enable the `tick` outlet and `pbrm` outlets while -the program `./vfd_swmr_zoo_writer` runs, you can use this command -in `csh` or Bourne shell: - -``` -env HLOG="tick=on pbrm=on" ./vfd_swmr_zoo_writer -``` - -# Implementation notes - -`hlog_fast(outlet name, format string, ...)` is implemented as a -macro that only evaluates its format string or other arguments if -it decides to write the message to `stderr`. `hlog_fast` avoids -repeatedly walking child-parent links by caching its decision to -write or discard in the named outlet. - -# Future improvements - -The timestamp origin is unspecified, now. For the user's convenience, -the timestamp probably should be measured from `hlog` library -initialization. Also, `hlog` should provide a routine for setting -the timestamp origin to the current time. - |