Log Messages
The ViennaRNA Package comes with a log message system that allows for filtering and (re-)routing of all messages issued by the library.
The default log message system prints messages that meet a certain log level to a file pointer that defaults to stderr. This file pointer, the log level threshold and the content of the messages can be adapted with the functions below.
In addition, the logging system allows for adding user-defined callbacks that can also retrieve the log messages for further processing. Along with that, the default logging mechanism can be turned off entirely such that only the callbacks process the log messages.
Below are all API symbols for interacting with the ViennaRNA logging system.
Logging System API
Defines
-
VRNA_LOG_LEVEL_DEFAULT
- #include <ViennaRNA/utils/log.h>
Default log level.
-
VRNA_LOG_OPTION_QUIET
- #include <ViennaRNA/utils/log.h>
Log option to turn off internal logging.
When this option is set via vrna_log_options_set() the internal logging system will be deactivated and only user-defined callbacks will be seeing any logs.
-
VRNA_LOG_OPTION_TRACE_CALL
- #include <ViennaRNA/utils/log.h>
Log option to turn on call tracing.
When this option is set via vrna_log_options_set() the internal logging system will include a call trace to the log output, i.e. the source code file and line numbers will be included in the log message.
-
VRNA_LOG_OPTION_TRACE_TIME
- #include <ViennaRNA/utils/log.h>
Log option to turn on time stamp.
When this option is set via vrna_log_options_set() the internal logging system will include a time stamp to the log output, i.e. the time when the log message was issued will be included in the log message.
-
VRNA_LOG_OPTION_DEFAULT
- #include <ViennaRNA/utils/log.h>
Log option representing the default options.
When this option is set via vrna_log_options_set() the default options will be set.
-
vrna_log_debug(...)
- #include <ViennaRNA/utils/log.h>
Issue a debug log message.
This macro expects a printf-like format string followed by a variable list of arguments for the format string and passes this content to the log system.
-
vrna_log_info(...)
- #include <ViennaRNA/utils/log.h>
Issue an info log message.
This macro expects a printf-like format string followed by a variable list of arguments for the format string and passes this content to the log system.
-
vrna_log_warning(...)
- #include <ViennaRNA/utils/log.h>
Issue a warning log message.
This macro expects a printf-like format string followed by a variable list of arguments for the format string and passes this content to the log system.
-
vrna_log_error(...)
- #include <ViennaRNA/utils/log.h>
Issue an error log message.
This macro expects a printf-like format string followed by a variable list of arguments for the format string and passes this content to the log system.
-
vrna_log_critical(...)
- #include <ViennaRNA/utils/log.h>
Issue a critical log message.
This macro expects a printf-like format string followed by a variable list of arguments for the format string and passes this content to the log system.
Typedefs
-
typedef struct vrna_log_event_s vrna_log_event_t
- #include <ViennaRNA/utils/log.h>
A log event.
-
typedef void (*vrna_log_lock_f)(int lock, void *lock_data)
- #include <ViennaRNA/utils/log.h>
The lock function prototype that may be passed to the logging system.
See also
- Param lock:
A parameter indicating whether to lock (lock != 0) or unlock (lock == 0)
- Param lock_data:
An arbitrary user-defined data pointer for the user-defined locking system
-
typedef void (*vrna_log_cb_f)(vrna_log_event_t *event, void *log_data)
- #include <ViennaRNA/utils/log.h>
The log callback function prototype.
- Param event:
The log event
- Param log_data:
An arbitrary user-defined data pointer for the user-define log message receiver
-
typedef void (*vrna_logdata_free_f)(void *data)
- #include <ViennaRNA/utils/log.h>
Enums
-
enum vrna_log_levels_e
The log levels.
Values:
-
enumerator VRNA_LOG_LEVEL_UNKNOWN
Unknown log level
-
enumerator VRNA_LOG_LEVEL_DEBUG
Debug log level
-
enumerator VRNA_LOG_LEVEL_INFO
Info log level
-
enumerator VRNA_LOG_LEVEL_WARNING
Warning log level
-
enumerator VRNA_LOG_LEVEL_ERROR
Error log level
-
enumerator VRNA_LOG_LEVEL_CRITICAL
Critical log level
-
enumerator VRNA_LOG_LEVEL_SILENT
Silent log level
-
enumerator VRNA_LOG_LEVEL_UNKNOWN
Functions
-
void vrna_log(vrna_log_levels_e level, const char *file_name, int line_number, const char *format_string, ...)
- #include <ViennaRNA/utils/log.h>
Issue a log message.
This is the low-level log message function. Usually, you don’t want to call it directly but rather call one of the following high-level macros instead:
See also
vrna_log_debug, vrna_log_info, vrna_log_warning, vrna_log_error, vrna_log_critical, vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()
- Parameters:
level – The log level
file_name – The source code file name of the file that issued the log
line_number – The source code line number that issued the log
format_string – The printf-like format string containing the log message
... – The variable argument list for the printf-like
format_string
-
vrna_log_levels_e vrna_log_level(void)
- #include <ViennaRNA/utils/log.h>
Get the current default log level.
See also
- Returns:
The current default log level
-
int vrna_log_level_set(vrna_log_levels_e level)
- #include <ViennaRNA/utils/log.h>
Set the default log level.
Set the log level for the default log output system. Any user-defined log callback mechanism will not be affected…
- Parameters:
level – The new log level for the default logging system
- Returns:
The (updated) log level of the default logging system
-
unsigned int vrna_log_options(void)
- #include <ViennaRNA/utils/log.h>
Get the current log options of the default logging system.
See also
vrna_log_options_set(), VRNA_LOG_OPTION_QUIET, VRNA_LOG_OPTION_TRACE_TIME VRNA_LOG_OPTION_TRACE_CALL, VRNA_LOG_OPTION_DEFAULT
- Returns:
The current options for the default logging system
-
void vrna_log_options_set(unsigned int options)
- #include <ViennaRNA/utils/log.h>
Set the log options for the default logging system.
See also
vrna_log_options(), VRNA_LOG_OPTION_QUIET, VRNA_LOG_OPTION_TRACE_TIME VRNA_LOG_OPTION_TRACE_CALL, VRNA_LOG_OPTION_DEFAULT
- Parameters:
options – The new options for the default logging system
-
FILE *vrna_log_fp(void)
- #include <ViennaRNA/utils/log.h>
Get the output file pointer for the default logging system.
- Returns:
The file pointer where the default logging system will print log messages to
-
void vrna_log_fp_set(FILE *fp)
- #include <ViennaRNA/utils/log.h>
Set the output file pointer for the default logging system.
- Parameters:
fp – The file pointer where the default logging system should print log messages to
-
size_t vrna_log_cb_add(vrna_log_cb_f cb, void *data, vrna_logdata_free_f data_release, vrna_log_levels_e level)
- #include <ViennaRNA/utils/log.h>
Add a user-defined log message callback.
This function will add the user-defined callback
cb
to the logging system that will receive log messages from RNAlib. The callback will be called for each issued message that has a level of at leastlevel
. The pointerdata
will be passed-through to the callback and may store arbitrary data required for the callback.- Parameters:
cb – The callback function
data – The data passed through to the callback function
data_release – A function that releases memory occupied by
data
(maybe NULL)level – The log level threshold for this callback
- Returns:
The current number of log message callbacks stored in the logging system
-
size_t vrna_log_cb_num(void)
- #include <ViennaRNA/utils/log.h>
Get the current number of log message callbacks.
- Returns:
The current number of log message callbacks stored in the logging system
-
size_t vrna_log_cb_remove(vrna_log_cb_f cb, void *data)
- #include <ViennaRNA/utils/log.h>
Remove a log message callback.
This function removes the log message callback
cb
from the logging system. It does so by searching through the list of known log message callbacks and comparing function (and data) addresses.Warning
The first callback stored in the logging system that matches
cb
will be removed! Ifdata
is supplied as well, the first callback that matches both, function and data address will be removed.- Parameters:
cb – The callback function to remove
data – The data that goes along with the callback
- Returns:
0 on any error, e.g. if the callback was not found, non-zero if it was removed
-
void vrna_log_lock_set(vrna_log_lock_f cb, void *data)
- #include <ViennaRNA/utils/log.h>
Specify a lock function to be used for the logging system.
To prevent undefined behavior in multi-threaded calls to the log system, each log message should be issued as an atomic block. For this to happen, a locking-/unlocking mechanism is required that ensures that log messages from other threads will be blocked until the current log message has been finalized. By default, we use pthreads mutex locking. Using this function, the locking mechanism can be changed to something else, or implemented after all if the ViennaRNA Package was compiled without pthreads support.
See also
- Parameters:
cb – The locking-/unlocking callback
data – An arbitrary data pointer passed through to the callback
-
void vrna_log_reset(void)
- #include <ViennaRNA/utils/log.h>
Reset the logging system.
This resets the logging system and restores default settings
-
struct vrna_log_event_s
- #include <ViennaRNA/utils/log.h>
A log event.
Public Members
-
const char *format_string
The printf-like format string containing the log information
-
va_list params
The parameters for the printf-like format string
-
vrna_log_levels_e level
The log level
-
int line_number
The source code line number that issued the log
-
const char *file_name
The source code file that issued the log
-
const char *format_string
-
VRNA_LOG_LEVEL_DEFAULT