goby-util: Overview of Utility Libraries

Table of Contents for goby-util: Overview of Utility Libraries.

• Overview
• Logging
  • Configurable extension of std::ostream - liblogger
• TCP and Serial port communications - liblinebasedcomms

Overview

The goby-util libraries are intended to provide functions and classes for handling "utility" tasks, such as logging, string manipulation, scientific calculations, etc. Wherever possible, a high quality open source peer reviewed solution is used (such as the C++ STL, boost). However, many of these libraries are very full-featured complex and are simplified here for Goby specific tasks.

Logging

Because Goby is designed first and foremost as an engineering testbed and scientific research architecture, comprehensive logging is extremely important for debugging both at runtime and post-mission. Thus, Goby provides a logging utility (goby::util::FlexOstream) based on C++ STL streams that provides highly configurable runtime (i.e. terminal window) and/or post-mission (text log file) logging. The syntax inside the code should be familiar to any C++ programmer, as any std::ostream functions can be used. The goby-acomms API classes all have a constructor which can take a pointer to std::ostream object that will be used to log. Thus, for runtime debugging one might instantiate them with std::cout:

goby::acomms::DCCLCodec dccl(&std::cout);

In which case you get output (to std::cout, aka the terminal window) that looks like:

[ 2011-Mar-01 04:06:35.169817 ]               {dccl_enc}: cryptography enabled with given passphrase
[ 2011-Mar-01 04:06:35.170610 ]               {dccl_enc}: starting encode for TEST
[ 2011-Mar-01 04:06:35.170683 ]               {dccl_enc}: 	B: bool: true
...

The timestamp (in Universal Coordinated Time) is given, with a group name (dccl_enc = DCCL Encoder) and finally the message. These groups are provided by using the manipulator "group". Text in the stream is a member of the given group until the next flush (std::endl or std::flush). For example:

// prints [ 2011-Mar-01 04:06:35.169817 ]               {my_group}: my message
std::cout << group("my_group") << "my message" << std::endl; // endl flushes my_group

Several other manipulators are provided:

• "debug" indicates that the buffer output is insignificant except for debugging (not useful for normal runtime)
• "warn" prints the buffer until the next flush as a warning.
• "die" is a fatal warning that calls "exit" with a non-zero code (indicating a fatal error). "die" should be used very sparingly.

Configurable extension of std::ostream - liblogger

goby::util::FlexOstream extends std::ostream to provide a number of extra logging features. This is generally the preferred logger (instead of std::cout, etc.) for goby applications. Use goby::util::glogger() in the same way you would use std::cout or a std::ofstream object. These features include:

• Often it is desirable to log simultaneously to a text file (std::ofstream) and the terminal window (std::cout). goby::util::FlexOstream allows you to attach any number of streams to it, which are all written to with a single call to operator<< on the goby::util::FlexOstream object.
• Color support for ANSI terminals (std::cout and std::cerr stream objects only)
• Multiple verbosity settings for each attached stream: QUIET (display nothing to this stream), WARN (display only warnings), VERBOSE (display warnings and normal text, but not debug text), DEBUG (display warnings, normal text, and debug messages), GUI (display all messages in an NCurses terminal GUI window, splitting groups into different displays)
• Optional thread safe access using a simple lock / unlock syntax.

The best way to get used to goby:util::glogger() is to compile and play with the flexostream_simple.cpp example.

A handful of examples:

Graphical user interface logger mode:

Simultaneous terminal window and file logging:

flexostream_simple quiet|warn|verbose|debug|gui test.txt

test.txt:

[ 2011-Mar-01 05:33:26.224050 ]               {}: (Warning): this is warning text
[ 2011-Mar-01 05:33:26.224277 ]               {}: this is normal text
[ 2011-Mar-01 05:33:26.224320 ]               {}: this is light blue text (in color terminals)
[ 2011-Mar-01 05:33:26.224362 ]               {}: (Debug): this is debug text
[ 2011-Mar-01 05:33:26.224388 ]               {a}: this text is related to a
[ 2011-Mar-01 05:33:26.224429 ]               {b}: this text is related to b
[ 2011-Mar-01 05:33:26.224471 ]               {c}: (Warning): this warning is related to c

TCP and Serial port communications - liblinebasedcomms

liblinebasedcomms provides a common interface (goby::util::LineBasedInterface) for line-based (defined as blocks of text offset by a common delimiter such as "\\r\\n" or "\\n") text communications over a TCP or serial connection. liblinebasedcomms using the boost::asio library to perform the actual communications.

You should create the proper subclass for your needs:

• Serial communications: goby::util::SerialClient
• TCP Client: goby::util::TCPClient
• TCP Server: goby::util::TCPServer - all incoming messages (as read by goby::util::LineBasedInterface::readline) are interleaved in the order they are received from all connected clients. Outgoing messages are sent to all connected clients unless using goby::util::LineBasedInterface::write (const protobuf::Datagram &msg) and msg.dest() is set to a specific endpoint (ip:port, e.g. "192.168.1.101:5123").