libcult/documentation/trace

The libcult trace library provides a general-purpose -program tracing facility. The following code fragment can be found -in libcult/examples/trace:

- -

-struct foo {};
-
-std::ostream&
-operator<< (std::ostream& o, foo const&)
-{
-  return o << "::foo";
-}
-
-namespace trace = cult::trace;
-
-trace::stream tout ("main", 4);
-
-int
-main ()
-{
-  using trace::record;
-
-  trace::log::instance ().level (9);
-
-  record a ("main", 2);
-  a << "notationally burdensome";
-  tout << a;
-
-  record b ("main", 2);
-  tout << (b << "a bit better, but still burdensome");
-
-  tout << (record ("main", 2) << "this is"
-           << " somewhat"
-           << " twisted but nice to be able to");
-
-  tout << "concise, using default level";
-
-  tout << 9 << "concise, using custom level";
-
-  foo f;
-
-  tout << 3 << f << " " << 5;
-}
-

- -

Along with the proper implementation, a null implementation is -provided which can be used to completely optimize trace code away. For details -see the -Inlining code away essay.