Merge branch 'devel' of github.com:stack-of-tasks/dynamic-graph into devel

doc/additionalDoc/debug-doc.h

@@ -2,9 +2,14 @@
 \page debug Debugging
 
 They are several ways to perform debugging in dynamic-graph depending on your needs or situation:
+- Programmatically inside the entity in C++ will write inside a buffer in a different thread and output in a stream
+(either std::cout or a file). It is detailed in \subpage subp_debug_rt_logger.
+- Programmatically inside the entity in C++ using a member of the entities and the previous real-time mechanism. 
+It provides 4 levels of messags :(DEBUG,INFO, WARNING, ERROR). It is described in details here:
+\subpage subp_logger
+- Programmatically in C++ to avoid overhead with macros and handling level as an int: \subpage subp_dbg_trace
 - If you just need to collect informations from signals (like rosbag). You can use
-an entity called Tracer inside the graph:\subpage tracerdoc
-- programmatically in C++ with macros \subpage subp_dbg_trace
-- programmatically inside the entity in C++ using member of the entities:
-\subpage tracerrealtimedoc
+an entity called Tracer inside the graph:\subpage tracerdoc . <br>
+A real time version exists
+to write directly inside a memory buffer \subpage tracerrealtimedoc
 **/

doc/additionalDoc/debug-logger.h

+/** 
+\page subp_logger Loggers
+
+\section sec_logger Initialization of the logger
+
+\subsection subsec_logger_hcpp Header and preprocessor variable
+
+In order to activate the logger you need to add the following lines:
+\code
+#define ENABLE_RT_LOG
+#include <dynamic-graph/real-time-logger.h>
+#include <dynamic-graph/logger.h>
+\endcode
+
+\subsection subsec_logger_ Initialize the output stream
+
+It is possible to set the output stream of the messages inside a file:
+\code
+  dynamicgraph::RealTimeLogger::instance();
+  of.open("/tmp/dg-LOGS.txt",std::ofstream::out|std::ofstream::app); 
+  dgADD_OSTREAM_TO_RTLOG (of);
+  
+  dynamicgraph::RealTimeLogger::destroy();
+\endcode
+Here the file is "/tmp/dg-LOGS.txt". 
+
+\subsection subsec_logger_init Initialization of the logger
+
+Inside the constructor of the entity:
+\code
+      logger_.setTimeSample(0.001);
+      logger_.setStreamPrintPeriod(0.005);
+      logger_.setVerbosity(VERBOSITY_ALL);
+      LoggerVerbosity alv = logger_.getVerbosity();
+\endcode
+
+The first line sets the frequency at which the logger will be updated.<br>
+The second line specifies at which frequency the message should be
+printed.<br>
+The third line specifies the level of message to accept.<br>
+The fourth line returns the level of verbosity.
+In this case, all messages are accepted. <br>
+
+The full list of options are:
+<ul>
+<li>VERBOSITY_ALL: Accept all messages</li>
+<li>VERBOSITY_INFO_WARNING_ERROR: Accept messages at minimum level : INFO, WARNING, ERROR</li>
+<li>VERBOSITY_WARNING_ERROR: Accept messages at minimum level : WARNING, ERROR</li>
+<li>VERBOSITY_ERROR: Accept messages at minimum level : ERROR</li>
+</ul>
+
+
+\section sec_logger_tests Displaying messages
+
+Here is some example on how to display or record some information.
+\code
+      sendMsg("This is a message of level MSG_TYPE_DEBUG",MSG_TYPE_DEBUG);
+      sendMsg("This is a message of level MSG_TYPE_INFO",MSG_TYPE_INFO);
+      sendMsg("This is a message of level MSG_TYPE_WARNING",MSG_TYPE_WARNING);
+      sendMsg("This is a message of level MSG_TYPE_ERROR",MSG_TYPE_ERROR);
+      sendMsg("This is a message of level MSG_TYPE_DEBUG_STREAM",MSG_TYPE_DEBUG_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_INFO_STREAM",MSG_TYPE_INFO_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_WARNING_STREAM",MSG_TYPE_WARNING_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_ERROR_STREAM",MSG_TYPE_ERROR_STREAM);
+
+      logger_.countdown();
+\endcode
+*/

doc/additionalDoc/debug-real-time-logger.h

+/**  
+\page subp_debug_rt_logger Real-time Logger
+
+ It is intended to be used like this:
+   \code
+   #define ENABLE_RT_LOG
+   #include <dynamic-graph/real-time-logger.h>
+  
+   // Somewhere in the main function of your executable
+   int main (int argc, char** argv) {
+     dgADD_OSTREAM_TO_RTLOG (std::cout);
+   }
+  
+   // Somewhere in your library
+   dgRTLOG() << "your message. Prefer to use \n than std::endl."
+   \endcode
+  
+   \note Thread safety. This class expects to have:
+   - only one reader: the one who take the log entries and write them somewhere.
+   - one writer at a time. Writing to the logs is **never** a blocking
+     operation. If the resource is busy, the log entry is discarded.
+*/

doc/additionalDoc/extension.h

@@ -4,15 +4,18 @@
 \section usecase How to use this package
 
 \subsection use_programmatically General introduction
+
+For control purposes the main use of this package is to create new entities and connect them through signals.
+
 Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
-declared within the code and compiled to shared libraries (.so/.dll files).
+declared within the code and compiled as shared libraries (.so/.dll files).
 These libraries can be loaded at run-time using the PluginLoader methods,
 and at the same time register their class names to the Factory (see the
 examples in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core documentation</a> 
 for advanced control examples).
 
 The Factory can then create instances of these objects and subsequently
-register them in the Pool, where they can be listed, accessed, and acted upon
+register them in the Pool. From the pool they can be listed, accessed, and acted upon
 (see PoolStorage documentation). Basic commands defined by entities include
 signal connection graph file generation, help and name print, and signals.
 This is usually done through a scripting language such as python (see
@@ -27,12 +30,82 @@ For an example of a program creating entities in C++, see the unit test
 test_pool.cpp (in your package source directory/tests).
 
 \subsection Tutorial
-A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>
+A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>.
+It is providing a step-by-step way of building an entity
 
 \section sec_htw_helpers Helpers
 
 When writing entities you might use some macros which are very useful to write your class.
 They are given also in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core</a> package as well.
 
+\subsection subsec_howto_typedef Entity helpers
+
+The header <b>entity-helper.h</b> is defining a type called EntityClassName 
+\section sec_howto_macros_helpers Macro helpers
+
+\subsection subsec_howto_macros_helpers Preprocessing macros for signals
+
+<ul>
+  <li>  Macro for input signals
+    <ul>
+      <li> <b>DECLARE_SIGNAL_IN(signal_name,type)</b>:
+      Declare an input time dependent signal as a field of the class with the following name:
+      \code
+      m_signal_nameSIN
+      \endcode
+      </li>
+      <li> <b>CONSTRUCT_SIGNAL_IN(signal_name,type)</b>:
+      This macro is used in the constructor of the entity class handling this signal.
+      It is calling the signal constructor and set the signal name to:
+      \code
+      EntityClassName(entity-name)::input(type)::signal_name
+      \endcode
+    </ul>
+  </li>
+  <li>  Macro for output signals
+    <ul>
+      <li> <b>DECLARE_SIGNAL_OUT(signal_name,type)</b>:
+      Declare an output time dependent signal as a field of the class with the following name:
+      \code
+      m_signal_nameSOUT
+      \endcode
+      It also declares a method with the following pattern:
+      \code
+      type signal_nameSOUT_function(type &,int)
+      \endcode
+      The second pattern is the time when calling the output.
+      </li>
+      <li> <b>CONSTRUCT_SIGNAL_OUT(signal_name,type)</b>
+      This macro is used in the constructor of the entity class handling this signal.
+      It creates the binding to the method described previously, and set the signal name to:
+      \code
+      EntityClassName(entity_name)::output(type)::signal_name
+      \endcode
+      where entity_name is the name of the entity currently instanciated.
+      </li>
+
+      <li> <b>DEFINE_SIGNAL_OUT_FUNCTION(signal_name, type)</b>:
+      This macro is used when implementing the method specific to the output signal.
+      It is used in the main body of the entity class to declare the header of the method 
+      with the following pattern:
+      \code
+      type EntityClassName::signal_nameSOUT_function(type &, int iter)
+      \endcode
+      </li>
+
+    </ul>
+  <li> 
+  </li>
+      <li> <b> DECLARE_SIGNAL_INNER(signal_name,type)</b>
+      Inner signal are signal that depend on a state of the entity and not on input signals.
+      This macro declares an inner signal with the following pattern:
+      \code
+      m_signal_nameSINNER
+      \endcode
+   </li>
+   <li> <b>DEFINE_SIGNAL_INNER_FUNCTION</b> 
+This macro 
+</li>
+</ul>
 
 */

tests/CMakeLists.txt

@@ -59,3 +59,5 @@ DYNAMIC_GRAPH_TEST(real-time-logger)
 DYNAMIC_GRAPH_TEST(debug-trace)
 DYNAMIC_GRAPH_TEST(debug-tracer)
 TARGET_LINK_LIBRARIES(debug-tracer tracer)
+DYNAMIC_GRAPH_TEST(debug-logger)
+DYNAMIC_GRAPH_TEST(debug-logger-winit)

tests/debug-logger.cpp

+/* Copyright 2019, LAAS-CNRS
+ *
+ * Olivier Stasse
+ *
+ * See LICENSE file
+ *
+ */
+#include <sstream>
+#include <iostream>
+#include <dynamic-graph/entity.h>
+#include <dynamic-graph/exception-factory.h>
+#include "dynamic-graph/factory.h"
+#include "dynamic-graph/pool.h"
+
+#define ENABLE_RT_LOG
+#include <dynamic-graph/real-time-logger.h>
+#include <dynamic-graph/logger.h>
+
+#define BOOST_TEST_MODULE debug-logger
+
+#include <boost/test/unit_test.hpp>
+#include <boost/test/output_test_stream.hpp>
+
+using boost::test_tools::output_test_stream;
+
+
+namespace dynamicgraph
+{
+  class CustomEntity : public Entity
+  {
+  public:
+    static const std::string CLASS_NAME;
+    virtual const std::string& getClassName () const
+    {
+      return CLASS_NAME;
+    }
+    CustomEntity (const std::string n)
+      : Entity (n)
+    {
+      logger_.setTimeSample(0.001);
+      logger_.setStreamPrintPeriod(0.005);
+      logger_.setVerbosity(VERBOSITY_ALL);
+      LoggerVerbosity alv = logger_.getVerbosity();
+      BOOST_CHECK(alv==VERBOSITY_ALL);
+    }
+    
+    ~CustomEntity()
+    {
+    }
+    void testDebugTrace()
+    {
+      sendMsg("This is a message of level MSG_TYPE_DEBUG",MSG_TYPE_DEBUG);
+      sendMsg("This is a message of level MSG_TYPE_INFO",MSG_TYPE_INFO);
+      sendMsg("This is a message of level MSG_TYPE_WARNING",MSG_TYPE_WARNING);
+      sendMsg("This is a message of level MSG_TYPE_ERROR",MSG_TYPE_ERROR);
+      sendMsg("This is a message of level MSG_TYPE_DEBUG_STREAM",MSG_TYPE_DEBUG_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_INFO_STREAM",MSG_TYPE_INFO_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_WARNING_STREAM",MSG_TYPE_WARNING_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_ERROR_STREAM",MSG_TYPE_ERROR_STREAM);
+
+      logger_.countdown();
+
+    }
+  };
+  DYNAMICGRAPH_FACTORY_ENTITY_PLUGIN (CustomEntity,"CustomEntity");
+}
+
+BOOST_AUTO_TEST_CASE(debug_logger)
+{
+  std::ofstream of;
+  dynamicgraph::RealTimeLogger::instance();
+  of.open("/tmp/dg-LOGS.txt",std::ofstream::out|std::ofstream::app); 
+  dgADD_OSTREAM_TO_RTLOG (of);
+  
+  BOOST_CHECK_EQUAL (dynamicgraph::CustomEntity::CLASS_NAME, "CustomEntity");
+  
+  dynamicgraph::CustomEntity& entity = *(dynamic_cast<dynamicgraph::CustomEntity *>(
+    dynamicgraph::FactoryStorage::getInstance()->newEntity("CustomEntity",
+							   "my-entity")));
+
+  for(unsigned int i=0;i<10000;i++)
+    {
+      entity.testDebugTrace();
+    }
+
+  dynamicgraph::RealTimeLogger::destroy();
+}
+
+