Log Messages — ViennaRNA Package

# 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

    Default log level.

        #include <ViennaRNA/utils/log.h>

    See also

    vrna_log_level_set(), vrna_log_reset(), vrna_log_level(), vrna_log_levels_e

  VRNA_LOG_OPTION_QUIET

    Log option to turn off internal logging.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_options_set(), vrna_log_options(), vrna_log_reset(), VRNA_LOG_OPTION_TRACE_CALL, VRNA_LOG_OPTION_TRACE_TIME, VRNA_LOG_OPTION_DEFAULT

  VRNA_LOG_OPTION_TRACE_CALL

    Log option to turn on call tracing.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_options_set(), vrna_log_options(), vrna_log_reset(), VRNA_LOG_OPTION_QUIET, VRNA_LOG_OPTION_TRACE_TIME, VRNA_LOG_OPTION_DEFAULT

  VRNA_LOG_OPTION_TRACE_TIME

    Log option to turn on time stamp.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_options_set(), vrna_log_options(), vrna_log_reset(), VRNA_LOG_OPTION_QUIET, VRNA_LOG_OPTION_TRACE_CALL, VRNA_LOG_OPTION_DEFAULT

  VRNA_LOG_OPTION_DEFAULT

    Log option representing the default options.

        #include <ViennaRNA/utils/log.h>

    When this option is set via vrna_log_options_set() the default options will be set.

    See also

    vrna_log_options_set(), vrna_log_options(), vrna_log_reset(), VRNA_LOG_OPTION_QUIET, VRNA_LOG_OPTION_TRACE_CALL, VRNA_LOG_OPTION_TRACE_TIME

  vrna_log_debug(...)

    Issue a debug log message.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_info, vrna_log_warning, vrna_log_error, vrna_log_critical, vrna_log(), vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()

  vrna_log_info(...)

    Issue an info log message.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_debug, vrna_log_warning, vrna_log_error, vrna_log_critical, vrna_log(), vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()

  vrna_log_warning(...)

    Issue a warning log message.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_debug, vrna_log_info, vrna_log_error, vrna_log_critical, vrna_log(), vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()

  vrna_log_error(...)

    Issue an error log message.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_debug, vrna_log_info, vrna_log_warning, vrna_log_critical, vrna_log(), vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()

  vrna_log_critical(...)

    Issue a critical log message.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_debug, vrna_log_info, vrna_log_warning, vrna_log_error, vrna_log(), vrna_log_level_set(), vrna_log_options_set(), vrna_log_fp_set()

  Typedefs

  typedef struct vrna_log_event_s vrna_log_event_t

    A log event.

        #include <ViennaRNA/utils/log.h>

  typedef void (*vrna_log_lock_f)(int lock, void *lock_data)

    The lock function prototype that may be passed to the logging system.

        #include <ViennaRNA/utils/log.h>

    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)

    The log callback function prototype.

        #include <ViennaRNA/utils/log.h>

    See also

    vrna_log_cb_add(), vrna_log_cb_num(), vrna_log_cb_remove()

    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.

        #include <ViennaRNA/utils/log.h>

    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, ...)

    Issue a log message.

        #include <ViennaRNA/utils/log.h>

    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

    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)

    Get the current default log level.

        #include <ViennaRNA/utils/log.h>

    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)

    Set the default log level.

        #include <ViennaRNA/utils/log.h>

    Set the log level for the default log output system. Any user-defined log callback mechanism will not be affected…

    See also

    vrna_log_level(), vrna_log_levels_e, vrna_log_cb_add(), vrna_log_reset()

    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)

    Get the current log options of the default logging system.

        #include <ViennaRNA/utils/log.h>

    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)

    Set the log options for the default logging system.

        #include <ViennaRNA/utils/log.h>

    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)

    Get the output file pointer for the default logging system.

        #include <ViennaRNA/utils/log.h>

    Returns:

      The file pointer where the default logging system will print log messages to

  void vrna_log_fp_set(FILE *fp)

    Set the output file pointer for the default logging system.

        #include <ViennaRNA/utils/log.h>

    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)

    Add a user-defined log message callback.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_cb_f, vrna_log_cb_num(), vrna_log_cb_remove(), vrna_log_reset()

    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)

    Get the current number of log message callbacks.

        #include <ViennaRNA/utils/log.h>

    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)

    Remove a log message callback.

        #include <ViennaRNA/utils/log.h>

    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.

    See also

    vrna_log_cb_f, vrna_log_cb_num(), vrna_log_cb_add(), vrna_log_reset()

    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)

    Specify a lock function to be used for the logging system.

        #include <ViennaRNA/utils/log.h>

    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)

    Reset the logging system.

        #include <ViennaRNA/utils/log.h>

    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

          #include <ViennaRNA/utils/log.h>

      The printf-like format string containing the log information

    va_list params

          #include <ViennaRNA/utils/log.h>

      The parameters for the printf-like format string

    vrna_log_levels_e level

          #include <ViennaRNA/utils/log.h>

      The log level

    int line_number

          #include <ViennaRNA/utils/log.h>

      The source code line number that issued the log

    const char *file_name

          #include <ViennaRNA/utils/log.h>

      The source code file that issued the log