libbdilog.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2024 MAK Technologies, Inc.
 * All rights reserved.
 ****************************************************************************/

 /**********************************************************************
 **
 *t  Boston Dynamics Log Library
 **
 **    The Boston Dynamics log library is used by most of Boston Dynamics'
 **    software.  It allows programs to write errors, debugging
 **    information, etc., to zero, one, or more outputs including
 **    stderr, a file, or a user-supplied output.
 */

#pragma once

#ifdef SWIG
%module libbdilog
#define CHECK_PRINTF_FORMAT
#else
#define CPLUSPLUS_ONLY
#if defined(__GNUC__) && (__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ > 4))
#define CHECK_PRINTF_FORMAT  __attribute__ ((format (printf, 2, 3)))
#else
#define CHECK_PRINTF_FORMAT  /* No support for non-GCC compilers */
#endif
#endif

#ifdef __cplusplus
extern "C"
{
#endif

#include <declspec_bdiutil.h>

/*****************************************************************************
 **
 *2  Constants and Types
 */

#ifdef CPLUSPLUS_ONLY

typedef int bdiCallbackHandle;

#define BDI_LOG_MAX_CALLBACKS       (8)
#define BDI_LOG_BAD_CALLBACK_HANDLE (-1)

#endif

/*l
 **    Log notify levels.  A lower number indicates higher importance.
 */
#define BDI_LOG_NOTHING    (-1)
#define BDI_LOG_ALWAYS     (0)
#define BDI_LOG_FATAL      (1)
#define BDI_LOG_ERROR      (2)
#define BDI_LOG_WARN       (3)
#define BDI_LOG_INFO       (4)
#define BDI_LOG_DEBUG      (5)
#define BDI_LOG_DEBUG_LV1  (6)
#define BDI_LOG_DEBUG_LV2  (7)
#define BDI_LOG_DEBUG_LV3  (8)
#define BDI_LOG_DEBUG_LV4  (9)
#define BDI_LOG_DEBUG_LV5  (10)
#define BDI_LOG_DEBUG_LV6  (11)
#define BDI_LOG_DEBUG_LV7  (12)
#define BDI_LOG_DEBUG_LV8  (13)
#define BDI_LOG_DEBUG_LV9  (14)
#define BDI_LOG_EVERYTHING (15)

/*
 *  Callback prototype.
 */
#ifdef CPLUSPLUS_ONLY

typedef int bdiLogCallbackFunction(int notify_level, const char* string, void* user_data);
typedef int bdiLogFatalExitFunction(void);
typedef const char* bdiLogPrefixFunction(void* user_data);

#endif


/*****************************************************************************
 **
 *2  Standard stderr/stdout Callbacks
 */

/*l
 *b  Description:
 **
 **    This function will route a copy of appropriate log messages to
 **    stdio's stderr.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    notify_level - only messages whose notify level is at least as important
 *a                   as this will appear in this log
 */
BDI_DECLSPEC_bdiutil int bdi_log_stderr_enable( int notify_level );

/*l
 *b  Description:
 **
 **    This function shuts down the log opened by bdi_log_stderr_enable().
 */
BDI_DECLSPEC_bdiutil int bdi_log_stderr_disable();

/*l
 *b  Description:
 **
 **    This function will route a copy of appropriate log messages to
 **    stdio's stdout.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    notify_level - only messages whose notify level is at least as important
 *a                   as this will appear in this log
 */
BDI_DECLSPEC_bdiutil int bdi_log_stdout_enable( int notify_level );

/*l
 *b  Description:
 **
 **    This function shuts down the log opened by bdi_log_stdout_enable().
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 */
BDI_DECLSPEC_bdiutil int bdi_log_stdout_disable();


/*****************************************************************************
 **
 *2  File Callbacks
 */

/*l
 *b  Description:
 **
 **    This function will route a copy of appropriate log messages to
 **    the named file.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    notify_level - only messages whose notify level is at least as important
 *a                   as this will appear in this log
 *a    filename     - name of the file in which messages will appear
 *a    clear_file   - 0 or 1; 1 means clear out prior contents of file,
 *a                   0 means append to the file
 */
BDI_DECLSPEC_bdiutil int bdi_log_file_enable( int notify_level, const char* filename, int clear_file );

/*l
 *b  Description:
 **
 **    This function shuts down the log opened by bdi_log_file_enable().
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 */
BDI_DECLSPEC_bdiutil int bdi_log_file_disable();

/*l
 *b  Description:
 **
 **    This function sets the log file notify level.  Messages whose notify_level
 **    argument is less important than this will not be printed, regardless of
 **    the notify_level used to open logs.
 **
 **    The starting global notify level is BDI_LOG_EVERYTHING.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    notify_level - global level of importance
 */
BDI_DECLSPEC_bdiutil int bdi_log_set_file_notify_level( int notify_level );

/*l
 *b  Description:
 **
 **    Returns the most recent setting of bdi_log_set_file_notify_level(int).
 **
 *b  Arguments and Return Value:
 **
 *a    return value - most recent setting
 */
BDI_DECLSPEC_bdiutil int bdi_log_get_file_notify_level();


/*****************************************************************************
 **
 *2  Print Functions
 */

/*l
 *b  Description:
 **
 **    This function sends the specified string to all open logs.  Whether or not
 **    the string is actually printed depends the specified notify_level in
 **    this call and the notify_level with which each log was opened.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    string       - message to be (potentially) printed
 *a    notify_level - "importance" of message; lower is more important
 */
BDI_DECLSPEC_bdiutil int bdi_log_print( int notify_level, const char* string );

/*l
 *b  Description:
 **
 **    printf-like version of bdi_log_print().  Use just like printf, but add
 **    the notify_level as the first argument.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 */
#ifdef CPLUSPLUS_ONLY

BDI_DECLSPEC_bdiutil int bdi_log_printf( int notify_level, const char* format, ... ) CHECK_PRINTF_FORMAT;

#endif

/*l
 *b  Description:
 **
 **    This function sets the global notify level.  Messages whose notify_level
 **    argument is less important than this will not be printed, regardless of
 **    the notify_level used to open logs.
 **
 **    The starting global notify level is BDI_LOG_EVERYTHING.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    notify_level - global level of importance
 **
 *b  Example:
 **
 *e  // open a file log with notify level BDI_LOG_WARN
 *e  bdi_log_file_enable(BDI_LOG_WARN, "errors.txt", 1);
 *e
 *e  // this message WILL appear in the log
 *e  bdi_log_print(BDI_LOG_WARN, "Message 1.\n");
 *e
 *e  // set the global notify level to be more strict
 *e  bdi_log_set_global_notify_level(BDI_LOG_ERROR);
 *e
 *e  // this message WILL NOT appear in the log
 *e  // (log messages of importance less than BDI_LOG_ERROR are ignored.)
 *e  bdi_log_print(BDI_LOG_WARN, "Message 2.\n");
 */
BDI_DECLSPEC_bdiutil int bdi_log_set_global_notify_level( int notify_level );

/*l
 *b  Description:
 **
 **    Returns the most recent setting of bdi_log_set_global_notify_level().
 **
 *b  Arguments and Return Value:
 **
 *a    return value - most recent setting
 */
BDI_DECLSPEC_bdiutil int bdi_log_get_global_notify_level();


/*****************************************************************************
 **
 *2  Registration Functions
 */

/*l
 *b  Description:
 **
 **    This function registers a callback for the specified notify_level.
 **
 *b  Arguments and Return Value:
 **
 *a    return value      - a handle
 *a    callback          - pointer to the callback function
 *a    notify_level      - level of "importance" the callback will be
 *a                        called for
 *a    user_data         - pointer that will be supplied to the callback
 *a                        each time it is called.
 */
#ifdef CPLUSPLUS_ONLY

BDI_DECLSPEC_bdiutil bdiCallbackHandle bdi_log_register_callback( int notify_level,
   bdiLogCallbackFunction* callback, void* user_data );

#endif

/*l
 *b  Description:
 **
 **    This function unregisters a previously registered callback.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    handle       - the handle returned by bdi_log_register_callback()
 */
#ifdef CPLUSPLUS_ONLY

BDI_DECLSPEC_bdiutil int bdi_log_unregister_callback( bdiCallbackHandle handle );

#endif

/*l
 *b  Description:
 **
 **    This function returns the number of logs currently open.
 **
 *b  Arguments and Return Value:
 **
 *a    return value      - number of logs open
 */
#ifdef CPLUSPLUS_ONLY

BDI_DECLSPEC_bdiutil int bdi_log_get_num_logs_open();

#endif

/*l
 *b  Description:
 **
 **    This function changes the notify level of a registered callback.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - 0 on success, -1 on failure
 *a    handle       - the handle returned by bdi_log_register_callback()
 *a    notify_level - the new notify level
 */
BDI_DECLSPEC_bdiutil int bdi_log_set_notify_level( bdiCallbackHandle handle, int notify_level );

/*l
 *b  Description:
 **
 **    This function returns the notify level of a registered callback.
 **
 *b  Arguments and Return Value:
 **
 *a    return value - most recent setting or BDI_LOG_NOTHING if handle is invalid
 *a    handle       - the handle returned by bdi_log_register_callback()
 */
BDI_DECLSPEC_bdiutil int bdi_log_get_notify_level( bdiCallbackHandle handle );

/*l
 *b  Description:
 **
 **    Derives a string from the notify level and returns it in the passed
 **    result buffer.
 **
 *b  Arguments:
 *a
 *a    notify_level   - notify level to parse
 *a    result         - character buffer for result
 *a    result_max_len - result buffer size
 */
BDI_DECLSPEC_bdiutil void bdi_log_get_string_from_notify_level( int notify_level,
   char* result, int result_buf_size );

/*l
 *b  Description:
 **
 **    This function registers a function that will be called if a
 **    log message is sent with level BDI_LOG_FATAL.  The function
 **    should whatever it takes to shut down gracefully.
 **
 **    If no fatal exit function is registered, exit(EXIT_FAILURE) will be
 **    called by default.
 */
#ifdef CPLUSPLUS_ONLY

BDI_DECLSPEC_bdiutil void bdi_log_register_fatal_exit_function( bdiLogFatalExitFunction* fatal_exit_func );

/*l
 *b  Description:
 **
 **    This function prints using OutputDebugString on Windows, which will
 **    show up in the Output window in Microsoft Developer Studio.
 */
BDI_DECLSPEC_bdiutil int bdi_log_print_to_output_window( const char* format, ... );

#endif


/*l
 *b  Description:
 **
 **    This function grabs the lock of the logging system. This is pretty hacky.
 **    If you do not release this lock, you're in trouble. This can be useful for
 **    certain specialized interactions with log callback objects that rely on the
 **    libbdilog lock for their synchronization.
 */
BDI_DECLSPEC_bdiutil void bdi_log_lock();

/*l
 *b  Description:
 **
 **    This function releases the lock of the logging system. This is pretty hacky.
 **    If you do not release this lock, you're in trouble. This can be useful for
 **    certain specialized interactions with log callback objects that rely on the
 **    libbdilog lock for their synchronization.
 */
BDI_DECLSPEC_bdiutil void bdi_log_unlock();

/*
 *  Debug macros.  Using these macros allows for liberal use of debugging
 *   output and assertions for debug versions, with zero runtime performance
 *   hit for release versions (similar to use of standard assertions).
 */
#ifdef CPLUSPLUS_ONLY
#ifndef NDEBUG

#define bdi_log_assert(assertion) if (!(assertion)) {bdi_log_printf(BDI_LOG_ERROR, "ERROR: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define bdi_log_assert_fatal(assertion) if (!(assertion)) {bdi_log_printf(BDI_LOG_FATAL, "FATAL: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__); exit(EXIT_FAILURE);}
#define bdi_log_assert_warn(assertion) if (!(assertion)) {bdi_log_printf(BDI_LOG_WARN, "WARNING: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define bdi_log_assert_info(assertion) if (!(assertion)) {bdi_log_printf(BDI_LOG_INFO, "INFO: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define bdi_log_assert_debug(assertion) if (!(assertion)) {bdi_log_printf(BDI_LOG_DEBUG, "DEBUG: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}

#define bdi_log_debug(string) bdi_log_print(BDI_LOG_DEBUG, string)
#define bdi_log_debug_arg0(string) bdi_log_print(BDI_LOG_DEBUG, string)
#define bdi_log_debug_arg1(string, arg1) bdi_log_printf(BDI_LOG_DEBUG, string, arg1)
#define bdi_log_debug_arg2(string, arg1, arg2) bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2)
#define bdi_log_debug_arg3(string, arg1, arg2, arg3) bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3)
#define bdi_log_debug_arg4(string, arg1, arg2, arg3, arg4) bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4)
#define bdi_log_debug_arg5(string, arg1, arg2, arg3, arg4, arg5) bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5)
#define bdi_log_debug_arg6(string, arg1, arg2, arg3, arg4, arg5, arg6) bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5, arg6)

#define bdi_log_debug_lvn(level, string) bdi_log_print(BDI_LOG_DEBUG_LV##level, string)
#define bdi_log_debug_lvn_arg0(level, string) bdi_log_print(BDI_LOG_DEBUG_LV##level, string)
#define bdi_log_debug_lvn_arg1(level, string, arg1) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1)
#define bdi_log_debug_lvn_arg2(level, string, arg1, arg2) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2)
#define bdi_log_debug_lvn_arg3(level, string, arg1, arg2, arg3) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3)
#define bdi_log_debug_lvn_arg4(level, string, arg1, arg2, arg3, arg4) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4)
#define bdi_log_debug_lvn_arg5(level, string, arg1, arg2, arg3, arg4, arg5) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5)
#define bdi_log_debug_lvn_arg6(level, string, arg1, arg2, arg3, arg4, arg5, arg6) bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5, arg6)

#else

#define bdi_log_assert(assertion) /* */
#define bdi_log_assert_fatal(assertion) /* */
#define bdi_log_assert_warn(assertion) /* */
#define bdi_log_assert_info(assertion) /* */
#define bdi_log_assert_debug(assertion) /* */

#define bdi_log_debug(string) /* */
#define bdi_log_debug_arg0(string) /* */
#define bdi_log_debug_arg1(string, arg1) /* */
#define bdi_log_debug_arg2(string, arg1, arg2) /* */
#define bdi_log_debug_arg3(string, arg1, arg2, arg3) /* */
#define bdi_log_debug_arg4(string, arg1, arg2, arg3, arg4) /* */
#define bdi_log_debug_arg5(string, arg1, arg2, arg3, arg4, arg5) /* */
#define bdi_log_debug_arg6(string, arg1, arg2, arg3, arg4, arg5, arg6) /* */

#define bdi_log_debug_lvn(level, string) /* */
#define bdi_log_debug_lvn_arg0(level, string) /* */
#define bdi_log_debug_lvn_arg1(level, string, arg1) /* */
#define bdi_log_debug_lvn_arg2(level, string, arg1, arg2) /* */
#define bdi_log_debug_lvn_arg3(level, string, arg1, arg2, arg3) /* */
#define bdi_log_debug_lvn_arg4(level, string, arg1, arg2, arg3, arg4) /* */
#define bdi_log_debug_lvn_arg5(level, string, arg1, arg2, arg3, arg4, arg5) /* */
#define bdi_log_debug_lvn_arg6(level, string, arg1, arg2, arg3, arg4, arg5, arg6) /* */

#endif
#endif

#ifdef __cplusplus
}
#endif