Creating a logging configure function that can be used to select which output handlers you want to use and setting the framework to allow for multiple output handlers in the logging code.

cr https://code.amazon.com/reviews/CR-3734291

Author: nburek

CMakeLists.txt

@@ -11,9 +11,14 @@ if(NOT CMAKE_CXX_STANDARD)
   set(CMAKE_CXX_STANDARD 14)
 endif()
 
+include(cmake/get_default_rc_logging_implementation.cmake)
+
+
 find_package(ament_cmake_python REQUIRED)
 find_package(ament_cmake_ros REQUIRED)
 
+get_default_rc_logging_implementation(RC_LOGGING_IMPL)
+
 ament_python_install_package(${PROJECT_NAME})
 
 include_directories(include)
@@ -91,6 +96,8 @@ add_library(
   ${PROJECT_NAME}
   ${rcutils_sources})
 
+target_link_libraries(${PROJECT_NAME} ${${RC_LOGGING_IMPL}_LIBRARIES})
+
 # Causes the visibility macros to use dllexport rather than dllimport,
 # which is appropriate when building the dll but not consuming it.
 target_compile_definitions(${PROJECT_NAME} PRIVATE "RCUTILS_BUILDING_DLL")

cmake/get_default_rc_logging_implementation.cmake

@@ -0,0 +1,46 @@
+# Copyright 2018 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#
+# Get the package name of the default logging implementation.
+#
+# Either selecting it using the variable RC_LOGGING_IMPLEMENTATION or
+# choosing a default from the available implementations.
+#
+# :param var: the output variable name containing the package name
+# :type var: string
+#
+macro(get_default_rc_logging_implementation var)
+
+  # if logging implementation already specified or RC_LOGGING_IMPLEMENTATION environment variable is set then use that,
+  # otherwise default to using rc_logging_log4cxx
+  if(NOT "${RC_LOGGING_IMPLEMENTATION}" STREQUAL "")
+    set(_logging_implementation "${RC_LOGGING_IMPLEMENTATION}")
+  elseif(NOT "$ENV{RC_LOGGING_IMPLEMENTATION}" STREQUAL "")
+    set(_logging_implementation "$ENV{RC_LOGGING_IMPLEMENTATION}")
+  else()
+    set(_logging_implementation rc_logging_log4cxx)
+  endif()
+
+  # persist implementation decision in cache
+  # if it was not determined dynamically
+  set(
+    RC_LOGGING_IMPLEMENTATION "${_logging_implementation}"
+    CACHE STRING "Select ROS middleware implementation to link against" FORCE
+  )
+
+  find_package("${_logging_implementation}" REQUIRED)
+
+  set(${var} ${_logging_implementation})
+endmacro()

include/rcutils/logging.h

@@ -142,6 +142,31 @@ RCUTILS_PUBLIC
 RCUTILS_WARN_UNUSED
 rcutils_ret_t rcutils_logging_shutdown(void);
 
+/// Configures the logging system.
+/**
+ * This function should be called during the ROS initialization process. It will
+ * add the enabled log output appenders to the root logger.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | No
+ * Uses Atomics       | No
+ * Lock-Free          | Yes
+ *
+ * \param default_level The default severity level to log at
+ * \param config_file The configuration file for the external logging library to use. Should be a null terminated string.
+ *      If NULL or an empty string the default configuration will be used
+ * \param enable_stdout Should the stdout output appender be enabled
+ * \param enable_rosout Should the rosout output appender be enabled
+ * \param enable_ext_lib Should the external logger library output appender be enabled
+ * \return `RCUTILS_RET_OK` if successful.
+ * \return `RCUTILS_RET_ERR` if a general error occurs
+ */
+RCUTILS_PUBLIC
+rcutils_ret_t rcutils_logging_configure(int default_level, const char * config_file, bool enable_stdout, bool enable_rosout, bool enable_ext_lib);
+
 /// The structure identifying the caller location in the source code.
 typedef struct rcutils_log_location_t
 {
@@ -196,16 +221,14 @@ rcutils_logging_severity_level_from_string(
  * \param severity The severity level
  * \param name The name of the logger
  * \param timestamp The timestamp
- * \param format The format string
- * \param args The variable argument list
+ * \param log_str The string to be logged
  */
 typedef void (* rcutils_logging_output_handler_t)(
   const rcutils_log_location_t *,  // location
   int,  // severity
   const char *,  // name
   rcutils_time_point_value_t,  // timestamp
-  const char *,  // format
-  va_list *  // args
+  const char *  // log_str
 );
 
 /// The function pointer of the current output handler.
@@ -418,7 +441,8 @@ int rcutils_logging_get_logger_effective_level(const char * name);
  * <hr>
  * Attribute          | Adherence
  * ------------------ | -------------
- * Allocates Memory   | No
+ * Allocates Memory   | No, for formatted outputs <= 1023 characters
+ *                    | Yes, for formatted outputs >= 1024 characters
  * Thread-Safe        | No
  * Uses Atomics       | No
  * Lock-Free          | Yes
@@ -449,8 +473,7 @@ void rcutils_log(
  * <hr>
  * Attribute          | Adherence
  * ------------------ | -------------
- * Allocates Memory   | No, for formatted outputs <= 1023 characters
- *                    | Yes, for formatted outputs >= 1024 characters
+ * Allocates Memory   | No
  * Thread-Safe        | Yes, if the underlying *printf functions are
  * Uses Atomics       | No
  * Lock-Free          | Yes
@@ -459,14 +482,13 @@ void rcutils_log(
  * \param severity The severity level
  * \param name The name of the logger, must be null terminated c string
  * \param timestamp The timestamp for when the log message was made
- * \param format The format string for the message contents
- * \param args The variable argument list for the message format string
+ * \param log_str The string to be logged
  */
 RCUTILS_PUBLIC
 void rcutils_logging_console_output_handler(
   const rcutils_log_location_t * location,
   int severity, const char * name, rcutils_time_point_value_t timestamp,
-  const char * format, va_list * args);
+  const char * log_str);
 
 // Provide the compiler with branch prediction information
 #ifndef _WIN32

include/rcutils/logging_external_interface.h

@@ -0,0 +1,66 @@
+// Copyright 2018 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RCUTILS_LOGGING_EXTERNAL_INTERFACE_H_
+#define RCUTILS_LOGGING_EXTERNAL_INTERFACE_H_
+
+#include <stdarg.h>
+#include "rcutils/types/rcutils_ret.h"
+#include "rcutils/visibility_control.h"
+
+
+/**
+ *  \brief Initializes the external logging library.
+ *
+ *  \param config_file The location of a config file that the external logging library should use to configure itself.
+ *          If no config file is provided this will be set to an empty string. Must be a NULL terminated c string.
+ *  \return RC_EXTERNAL_LOGGING_RET_OK if initialized successfully or an error code if not.
+ */
+RCUTILS_PUBLIC
+rcutils_ret_t rcutils_logging_external_initialize(const char * config_file);
+
+/**
+ *  \brief Free the resources allocated for the external logging system.
+ *  This puts the system into a state equivalent to being uninitialized
+ *
+ *  \return RC_EXTERNAL_LOGGING_RET_OK if successfully shutdown or an error code if not.
+ */
+RCUTILS_PUBLIC
+rcutils_ret_t rcutils_logging_external_shutdown();
+
+/**
+ *  \brief Logs a message
+ *
+ *  \param severity The severity level of the message being logged
+ *  \param name The name of the logger, must be a null terminated c string or NULL. If NULL or empty the root logger will
+ *          be used.
+ *  \param msg The message to be logged. Must be a null terminated c string.
+ */
+RCUTILS_PUBLIC
+void rcutils_logging_external_log(int severity, const char * name, const char * msg);
+
+
+/**
+ *  \brief Set the severity level for a logger.
+ *  Sets the severity level for the specified logger. If the name provided is an empty string or NULL it will change the
+ *  level of the root logger.
+ *
+ *  \param name The name of the logger. Must be a NULL terminated c string or NULL.
+ *  \param level - The severity level to be used for the specified logger
+ *  \return RC_EXTERNAL_LOGGING_RET_OK if set successfully or an error code if not.
+ */
+RCUTILS_PUBLIC
+rcutils_ret_t rcutils_logging_external_set_logger_level(const char * name, int level);
+
+#endif

include/rcutils/macros.h

@@ -62,6 +62,7 @@ extern "C"
 
 #define RCUTILS_STRINGIFY_IMPL(x) #x
 #define RCUTILS_STRINGIFY(x) RCUTILS_STRINGIFY_IMPL(x)
+#define RCUTILS_UNUSED(x) (void)(x)
 
 #ifdef __cplusplus
 }

package.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <?xml-model href="http://download.ros.org/schema/package_format2.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
-<package format="2">
+<package format="3">
   <name>rcutils</name>
   <version>0.6.0</version>
   <description>Package containing various utility types and functions for C</description>
@@ -10,6 +10,9 @@
   <buildtool_depend>ament_cmake_ros</buildtool_depend>
   <buildtool_depend>python3-empy</buildtool_depend>
 
+  <depend>rc_logging_log4cxx</depend>
+  <group_depend>rc_logging_packages</group_depend>
+
   <test_depend>ament_cmake_gmock</test_depend>
   <test_depend>ament_cmake_gtest</test_depend>
   <test_depend>ament_cmake_pytest</test_depend>

src/allocator.c

@@ -31,28 +31,28 @@
 static void *
 __default_allocate(size_t size, void * state)
 {
-  (void)state;  // unused
+  RCUTILS_UNUSED(state);
   return malloc(size);
 }
 
 static void
 __default_deallocate(void * pointer, void * state)
 {
-  (void)state;  // unused
+  RCUTILS_UNUSED(state);
   free(pointer);
 }
 
 static void *
 __default_reallocate(void * pointer, size_t size, void * state)
 {
-  (void)state;  // unused
+  RCUTILS_UNUSED(state);
   return realloc(pointer, size);
 }
 
 static void *
 __default_zero_allocate(size_t number_of_elements, size_t size_of_element, void * state)
 {
-  (void)state;  // unused
+  RCUTILS_UNUSED(state);
   return calloc(number_of_elements, size_of_element);
 }