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

vrna_log_lock_set()

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

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:

vrna_log_debug
vrna_log_info
vrna_log_warning
vrna_log_error
vrna_log_critical

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

vrna_log_level_set(), vrna_log_levels_e

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.

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.

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 least level. The pointer data 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! If data 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

vrna_log_lock_f, vrna_log_reset()

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