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.

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:

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.

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.

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