Logging support

[Jef Driesen]

Hi,

I'm currently polishing the public API to prepare for a first release. 
Please don't ask for a date, because I won't be able to give one. 
Anyway, since some of these changes requires breaking backwards 
compatibility, I want to take this opportunity to reconsider a few other 
items as well. And one of these things is the logging support.

Currently, the libdivecomputer API exposes the message() and 
message_set_logfile() functions. The first one is a simple printf() 
style logging function sending its output to stderr, and the second one 
allows to duplicate the output to a logfile. The main purpose of these 
functions is to allow non-technical people to easily email the output of 
the test applications, without having to redirect the output manually to 
a file. Running a command line application is already difficult enough.

Originally, these functions were intended for internal use only. They 
where never supposed to be part of the public api. Applications are 
supposed to rely on the status code that are returned. The logfile 
should be used at most for troubleshooting and diagnostics purposes. The 
only reason why they are included in the public api today, is because of 
the test applications. To make the output easier to interpret, the test 
applications write some additional info (e.g. the name of the functions 
being called). Since the test applications are no different from other 
applications, these functions had to be public.

But there are a number of potential problems:

1. Thread-safety. The logging functions use a number of global 
variables without any locking, and are therefore not thread-safe. This 
is not ideal considered the remainder of the library was designed to be 
used safely in a multi-threaded application (under a number of 
conditions).

In practice it's not that bad because the global variables used for the 
logging or not that critical (e.g. timestamps), and most C stdio 
libraries implementations are thread-safe by default (thus the actual 
file writing should be fine, and in case two threads want to log at the 
same time, the output might be interleaved.).

I believe the only real solution is either to implement proper locking 
(which is a heavyweight solution considered we don't require any 
explicit locking elsewhere in the code) or disable all logging by 
default. Disabling the logging could be done at build time (e.g. logging 
in debug builds only) or at runtime (see next item). Note that disabling 
at runtime wouldn't be truly thread-safe either.

2. Verbosity. By default only errors are logged. However, for 
troubleshooting this minimal info is almost useless and a much more 
verbose logfile is required. For this reason, the test applications are 
using a special patched version of the library, which is not ideal.

This could be solved by adding a new function to let the application 
specify the loglevel (e.g. None, Errors, Warnings, Debug), with a 
default setting of "None".

If anyone has ideas to improve this situation, you're welcome to share 
them!

My personal preference is to allow to disable the logging at build time 
(e.g. the easiest solution), to avoid the entire thread-safety issues, 
and build with logging when necessary (e.g. in the single threaded test 
applications). But on the other hand, it would be great if those verbose 
diagnostics logs could be generated directly from within the 
applications, so users are not forced to use the very user unfriendly 
commandline based test applications.

Jef