Merge branch 'master' into next

6 files changed, 176 insertions, 7 deletions

diff --git a/host/include/uhd/config.hpp b/host/include/uhd/config.hpp
index 6fd2932cf..96dfe8ed0 100644
--- a/host/include/uhd/config.hpp
+++ b/host/include/uhd/config.hpp
@@ -76,6 +76,13 @@ typedef ptrdiff_t ssize_t;
     #define UHD_API UHD_IMPORT
 #endif // UHD_DLL_EXPORTS
 
+// The user can enable this with -DUHD_FUTURE
+#ifdef UHD_FUTURE
+    #define UHD_API_FUTURE UHD_API
+#else
+    #define UHD_API_FUTURE
+#endif
+
 // Platform defines for conditional parts of headers:
 // Taken from boost/config/select_platform_config.hpp,
 // however, we define macros, not strings for platforms.
diff --git a/host/include/uhd/utils/CMakeLists.txt b/host/include/uhd/utils/CMakeLists.txt
index 71808ac98..875c4731f 100644
--- a/host/include/uhd/utils/CMakeLists.txt
+++ b/host/include/uhd/utils/CMakeLists.txt
@@ -23,6 +23,8 @@ INSTALL(FILES
     byteswap.ipp
     gain_group.hpp
     images.hpp
+    log.hpp
+    msg.hpp
     pimpl.hpp
     props.hpp
     safe_call.hpp
diff --git a/host/include/uhd/utils/log.hpp b/host/include/uhd/utils/log.hpp
new file mode 100644
index 000000000..8d8f42fd0
--- /dev/null
+++ b/host/include/uhd/utils/log.hpp
@@ -0,0 +1,93 @@
+//
+// Copyright 2011 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#ifndef INCLUDED_UHD_UTILS_LOG_HPP
+#define INCLUDED_UHD_UTILS_LOG_HPP
+
+#include <uhd/config.hpp>
+#include <boost/current_function.hpp>
+#include <ostream>
+#include <string>
+
+/*! \file log.hpp
+ * The UHD logging facility.
+ *
+ * The logger enables UHD library code to easily log events into a file.
+ * Log entries are time-stamped and stored with file, line, and function.
+ * Each call to the UHD_LOG macros is synchronous and thread-safe.
+ *
+ * The log file can be found in the path <temp-directory>/uhd.log,
+ * where <temp-directory> is the user or system's temporary directory.
+ * To override <temp-directory>, set the UHD_TEMP_PATH environment variable.
+ *
+ * All log messages with verbosity greater than or equal to the log level
+ * (in other words, as often or less often than the current log level)
+ * are recorded into the log file. All other messages are sent to null.
+ *
+ * The default log level is "regular", but can be overridden:
+ *  - at compile time by setting the pre-processor define UHD_LOG_LEVEL.
+ *  - at runtime by setting the environment variable UHD_LOG_LEVEL.
+ *
+ * UHD_LOG_LEVEL can be the name of a verbosity enum or integer value:
+ *   - Example pre-processor define: -DUHD_LOG_LEVEL=3
+ *   - Example pre-processor define: -DUHD_LOG_LEVEL=regularly
+ *   - Example environment variable: export UHD_LOG_LEVEL=3
+ *   - Example environment variable: export UHD_LOG_LEVEL=regularly
+ */
+
+/*!
+ * A UHD logger macro with configurable verbosity.
+ * Usage: UHD_LOGV(very_rarely) << "the log message" << std::endl;
+ */
+#define UHD_LOGV(verbosity) \
+    uhd::_log::log(uhd::_log::verbosity, __FILE__, __LINE__, BOOST_CURRENT_FUNCTION)()
+
+/*!
+ * A UHD logger macro with default verbosity.
+ * Usage: UHD_LOG << "the log message" << std::endl;
+ */
+#define UHD_LOG \
+    UHD_LOGV(regularly)
+
+
+namespace uhd{ namespace _log{
+
+    //! Verbosity levels for the logger
+    enum verbosity_t{
+        always      = 1,
+        often       = 2,
+        regularly   = 3,
+        rarely      = 4,
+        very_rarely = 5,
+        never       = 6,
+    };
+
+    //! Internal logging object (called by UHD_LOG macros)
+    struct UHD_API_FUTURE log{
+        log(
+            const verbosity_t verbosity,
+            const std::string &file,
+            const unsigned int line,
+            const std::string &function
+        );
+        ~log(void);
+        std::ostream &operator()(void);
+    };
+
+}} //namespace uhd::_log
+
+#endif /* INCLUDED_UHD_UTILS_LOG_HPP */
diff --git a/host/include/uhd/utils/msg.hpp b/host/include/uhd/utils/msg.hpp
new file mode 100644
index 000000000..17179f551
--- /dev/null
+++ b/host/include/uhd/utils/msg.hpp
@@ -0,0 +1,63 @@
+//
+// Copyright 2011 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#ifndef INCLUDED_UHD_UTILS_MSG_HPP
+#define INCLUDED_UHD_UTILS_MSG_HPP
+
+#include <uhd/config.hpp>
+#include <ostream>
+#include <string>
+
+/*!
+ * A UHD message macro with configurable type.
+ * Usage: UHD_MSG(warning) << "some warning message" << std::endl;
+ */
+#define UHD_MSG(type) \
+    uhd::msg::_msg(uhd::msg::type)()
+
+
+namespace uhd{ namespace msg{
+
+    //! Possible message types
+    enum type_t{
+        status  = 's',
+        warning = 'w',
+        error   = 'e',
+        fastpath= 'f'
+    };
+
+    //! Typedef for a user-registered message handler
+    typedef void (*handler_t)(type_t, const std::string &);
+
+    /*!
+     * Register the handler for uhd system messages.
+     * Only one handler can be registered at once.
+     * This replaces the default std::cout/cerr handler.
+     * \param handler a new handler callback function
+     */
+    UHD_API_FUTURE void register_handler(const handler_t &handler);
+
+    //! Internal message object (called by UHD_MSG macro)
+    struct UHD_API_FUTURE _msg{
+        _msg(const type_t type);
+        ~_msg(void);
+        std::ostream &operator()(void);
+    };
+
+}} //namespace uhd::msg
+
+#endif /* INCLUDED_UHD_UTILS_MSG_HPP */
diff --git a/host/include/uhd/utils/safe_call.hpp b/host/include/uhd/utils/safe_call.hpp
index 6b2c210af..ab287cc66 100644
--- a/host/include/uhd/utils/safe_call.hpp
+++ b/host/include/uhd/utils/safe_call.hpp
@@ -20,12 +20,12 @@
 
 #include <uhd/config.hpp>
 #include <uhd/exception.hpp>
-#include <uhd/utils/warning.hpp>
+#include <uhd/utils/log.hpp>
 
 //! helper macro for safe call to produce warnings
-#define _UHD_SAFE_CALL_WARNING(code, what) uhd::warning::post( \
+#define _UHD_SAFE_CALL_WARNING(code, what) UHD_LOGV(rarely) << \
     UHD_THROW_SITE_INFO("Exception caught in safe-call.") + #code + " -> " + what \
-);
+;
 
 /*!
  * A safe-call catches all exceptions thrown by code,
diff --git a/host/include/uhd/utils/warning.hpp b/host/include/uhd/utils/warning.hpp
index a1e3f0d1e..ae614d59e 100644
--- a/host/include/uhd/utils/warning.hpp
+++ b/host/include/uhd/utils/warning.hpp
@@ -23,6 +23,10 @@
 #include <vector>
 #include <string>
 
+/*! \file warning.hpp
+ * EVERYTHING IN THIS FILE IS TOTALLY DEPRECATED! DO NOT USE IT!
+ */
+
 namespace uhd{ namespace warning{
 
     //! Callback function type for a message handler
@@ -32,7 +36,7 @@ namespace uhd{ namespace warning{
      * Post a warning message to all registered handlers.
      * \param msg the multiline warning message
      */
-    UHD_API void post(const std::string &msg);
+    UHD_API UHD_DEPRECATED void post(const std::string &msg);
 
     /*!
      * Register a new handler with this name.
@@ -41,7 +45,7 @@ namespace uhd{ namespace warning{
      * \param name a unique name for this handler
      * \param handler the callback handler function
      */
-    UHD_API void register_handler(const std::string &name, const handler_t &handler);
+    UHD_API UHD_DEPRECATED void register_handler(const std::string &name, const handler_t &handler);
 
     /*!
      * Unregister a handler for this name.
@@ -49,13 +53,13 @@ namespace uhd{ namespace warning{
      * \return the handler that was registered
      * \throw error when the name was not found in the registry
      */
-    UHD_API handler_t unregister_handler(const std::string &name);
+    UHD_API UHD_DEPRECATED handler_t unregister_handler(const std::string &name);
 
     /*!
      * Get a list of registered handler names.
      * \return a vector of unique string names
      */
-    UHD_API const std::vector<std::string> registry_names(void);
+    UHD_API UHD_DEPRECATED const std::vector<std::string> registry_names(void);
 
 }} //namespace uhd::warning