Merge pull request #1264 from LLNL/feature/han12/slic_tags

Slic tags for streams and messages

src/axom/lumberjack/CMakeLists.txt

@@ -18,6 +18,7 @@ set(lumberjack_headers
     MPIUtility.hpp
     RootCommunicator.hpp
     TextEqualityCombiner.hpp
+    TextTagCombiner.hpp
     )
 
 set(lumberjack_sources

src/axom/lumberjack/Lumberjack.cpp

@@ -23,7 +23,7 @@ void Lumberjack::initialize(Communicator* communicator, int ranksLimit)
 {
   m_communicator = communicator;
   m_ranksLimit = ranksLimit;
-  m_combiners.push_back(new TextEqualityCombiner);
+  m_combiners.push_back(new TextTagCombiner);
 }
 
 void Lumberjack::finalize()

src/axom/lumberjack/Lumberjack.hpp

@@ -22,7 +22,7 @@
 #include "axom/lumberjack/Combiner.hpp"
 #include "axom/lumberjack/Communicator.hpp"
 #include "axom/lumberjack/Message.hpp"
-#include "axom/lumberjack/TextEqualityCombiner.hpp"
+#include "axom/lumberjack/TextTagCombiner.hpp"
 
 namespace axom
 {

src/axom/lumberjack/TextEqualityCombiner.hpp

@@ -34,13 +34,16 @@ namespace lumberjack
  *  you. If you want it removed call Lumberjack::removeCombiner with the string
  * "TextEqualityCombiner" as it's parameter.
  *
+ * \warning Using the TextEqualityCombiner with Message::tag has undefined
+ *          behavior.
+ *
  * \see Combiner Lumberjack
  *******************************************************************************
  */
 class TextEqualityCombiner : public Combiner
 {
 public:
-  TextEqualityCombiner() : m_id("TextEqualityCombiner") { }
+  TextEqualityCombiner() { }
 
   /*!
    *****************************************************************************
@@ -65,11 +68,7 @@ class TextEqualityCombiner : public Combiner
   bool shouldMessagesBeCombined(const Message& leftMessage,
                                 const Message& rightMessage)
   {
-    if(leftMessage.text().compare(rightMessage.text()) == 0)
-    {
-      return true;
-    }
-    return false;
+    return (leftMessage.text().compare(rightMessage.text()) == 0);
   }
 
   /*!
@@ -83,6 +82,8 @@ class TextEqualityCombiner : public Combiner
    * \param [in] combinee the Message that is combined into the other.
    * \param [in] ranksLimit The limit on how many individual ranks are tracked
    *  in the combined Message. Message::rankCount is always incremented.
+   *
+   * \pre shouldMessagesBeCombined(combined, combinee) must be true
    *****************************************************************************
    */
   void combine(Message& combined, const Message& combinee, const int ranksLimit)
@@ -91,7 +92,7 @@ class TextEqualityCombiner : public Combiner
   }
 
 private:
-  std::string m_id;
+  const std::string m_id = "TextEqualityCombiner";
 };
 
 }  // end namespace lumberjack

src/axom/lumberjack/TextTagCombiner.hpp

@@ -0,0 +1,100 @@
+// Copyright (c) 2017-2023, Lawrence Livermore National Security, LLC and
+// other Axom Project Developers. See the top-level LICENSE file for details.
+//
+// SPDX-License-Identifier: (BSD-3-Clause)
+
+/*!
+ *******************************************************************************
+ * \file TextTagCombiner.hpp
+ *
+ * \brief This file contains the class implementation of the
+ * TextTagCombiner.
+ *******************************************************************************
+ */
+
+#ifndef TEXTTAGCOMBINER_HPP
+#define TEXTTAGCOMBINER_HPP
+
+#include "axom/lumberjack/Combiner.hpp"
+#include "axom/lumberjack/Message.hpp"
+
+#include <string>
+
+namespace axom
+{
+namespace lumberjack
+{
+/*!
+ *******************************************************************************
+ * \class TextTagCombiner
+ *
+ * \brief Combines Message classes if their Message::text and Message::tag
+ *        are equal.
+ *
+ *  This class can be added to Lumberjack's Lumberjack by calling
+ *  Lumberjack::addCombiner with a
+ *  TextTagCombiner instance as its parameter.
+ *
+ * \see Combiner Lumberjack
+ *******************************************************************************
+ */
+class TextTagCombiner : public Combiner
+{
+public:
+  TextTagCombiner() { }
+
+  /*!
+   *****************************************************************************
+   * \brief Returns the unique string identifier for this combiner. Used by
+   *  Lumberjack to differentiate between other combiners.
+   *****************************************************************************
+   */
+  const std::string id() { return m_id; }
+
+  /*!
+   *****************************************************************************
+   * \brief Function used by Lumberjack to indicate whether two messages should
+   *  be combined.
+   *
+   * They are not actually combined by this function. Message classes are
+   * triggered for combination if both Message::text and Message::tag are equal.
+   *
+   * \param [in] leftMessage One of the Messages to be compared.
+   * \param [in] rightMessage One of the Messages to be compared.
+   *****************************************************************************
+   */
+  bool shouldMessagesBeCombined(const Message& leftMessage,
+                                const Message& rightMessage)
+  {
+    return (leftMessage.text().compare(rightMessage.text()) == 0 &&
+            leftMessage.tag().compare(rightMessage.tag()) == 0);
+  }
+
+  /*!
+   *****************************************************************************
+   * \brief Combines the combinee into the combined Message.
+   *
+   * The only thing truly combined in this Combiner is the ranks from combinee
+   * to combined, since text is already equal.
+   *
+   * \param [in,out] combined the Message that will be modified.
+   * \param [in] combinee the Message that is combined into the other.
+   * \param [in] ranksLimit The limit on how many individual ranks are tracked
+   *  in the combined Message. Message::rankCount is always incremented.
+   *
+   * \pre shouldMessagesBeCombined(combined, combinee) must be true
+   *****************************************************************************
+   */
+  void combine(Message& combined, const Message& combinee, const int ranksLimit)
+  {
+    combined.addRanks(combinee.ranks(), combinee.count(), ranksLimit);
+  }
+
+private:
+  const std::string m_id = "TextTagCombiner";
+};
+
+}  // end namespace lumberjack
+}  // end namespace axom
+
+#endif

src/axom/lumberjack/docs/sphinx/combiner_class.rst

@@ -23,6 +23,18 @@ combine                   Combines the second message into the first.
 Concrete Instances
 ------------------
 
+.. _texttagcombiner_class_label:
+
+TextTagCombiner
+^^^^^^^^^^^^^^^
+
+This Combiner combines the two given Messages if the Message text strings and tag strings are equal.
+It does so by adding the second Message's ranks to the first Message (if not past
+the ranksLimit) and incrementing the Message's count as well.  This is handled by
+Message.addRanks().
+
+.. note:: This is the only Combiner automatically added to Lumberjack for you.  You can remove it by calling Lumberjack::removeCombiner("TextTagCombiner").
+
 .. _textequalitycombiner_class_label:
 
 TextEqualityCombiner
@@ -33,4 +45,4 @@ It does so by adding the second Message's ranks to the first Message (if not pas
 the ranksLimit) and incrementing the Message's count as well.  This is handled by
 Message.addRanks().
 
-.. note:: This is the only Combiner automatically added to Lumberjack for you.  You can remove it by calling Lumberjack::removeCombiner("TextEqualityCombiner").
+.. note:: You can add this Combiner by calling Lumberjack::addCombiner(new TextEqualityCombiner).

src/axom/lumberjack/docs/sphinx/core_concepts.rst

@@ -16,18 +16,18 @@ your program.  It does so by giving the currently held Messages at the current n
 two at a time, to the Combiner classes that are currently registered to Lumberjack
 when a Push happens.
 
-Lumberjack only provides one Combiner, the TextEqualityCombiner. You can write your own
+Lumberjack provides one Combiner as default, the TextTagCombiner. You can write your own
 Combiners and register them with Lumberjack.  The idea is that each Combiner would have
 its own criteria for whether a Message should be combined and how to combine that specific
 Message with another of the same type.
 
 Combiner's have two main functions, shouldMessagesBeCombined and combine.
 
-The function shouldMessagesBeCombined, returns True if the pair of messages satisfy the associated criteria.  For example in the TextEqualityCombiner,
-if the Text strings are exactly equal, it signals they should be combined.
+The function shouldMessagesBeCombined, returns True if the pair of messages satisfy the associated criteria.  For example in the TextTagCombiner,
+if the Text strings and tag strings are exactly equal, it signals they should be combined.
 
 The function combine, takes two Messages and combines them in the way that is specific
-to that Combiner class.  For example in the TextEqualityCombiner, the only thing
+to that Combiner class.  For example in the TextTagCombiner, the only thing
 that happens is the second Message's ranks gets added to the first and the message count
 is increased.  This is because the text strings were equal.  This may not be the case
 for all Combiners that you write yourself.

src/axom/lumberjack/docs/sphinx/lumberjack_classes.rst

@@ -15,6 +15,7 @@ Combiners
 Handles Message combination and tests whether Message classes should be combined.
 
 * :ref:`Combiner <combiner_class_label>` - Abstract base class that all Combiners must inherit from.
+* :ref:`TextTagCombiner <texttagcombiner_class_label>` - Combines Message classes that have equal Text and Tag member variables.
 * :ref:`TextEqualityCombiner <textequalitycombiner_class_label>` - Combines Message classes that have equal Text member variables.
 
 

src/axom/lumberjack/tests/CMakeLists.txt

@@ -12,7 +12,8 @@
 set(lumberjack_serial_tests
     lumberjack_Lumberjack.hpp
     lumberjack_Message.hpp
-    lumberjack_TextEqualityCombiner.hpp )
+    lumberjack_TextEqualityCombiner.hpp
+    lumberjack_TextTagCombiner.hpp )
 
 axom_add_executable(NAME       lumberjack_serial_tests
                     SOURCES    lumberjack_serial_main.cpp

src/axom/lumberjack/tests/lumberjack_TextTagCombiner.hpp

@@ -0,0 +1,110 @@
+// Copyright (c) 2017-2023, Lawrence Livermore National Security, LLC and
+// other Axom Project Developers. See the top-level LICENSE file for details.
+//
+// SPDX-License-Identifier: (BSD-3-Clause)
+
+#include "gtest/gtest.h"
+
+#include "axom/lumberjack/TextTagCombiner.hpp"
+
+TEST(lumberjack_TextTagCombiner, case01)
+{
+  //Test positive case: two equal texts and tags
+  std::string text = "I never wanted to do this job in the first place!";
+  axom::lumberjack::Message m1;
+  m1.text(text);
+  m1.addRank(13, 5);
+  m1.fileName("foo.cpp");
+  m1.lineNumber(154);
+  m1.tag("myTag");
+
+  axom::lumberjack::Message m2;
+  m2.text(text);
+  m2.addRank(14, 5);
+  m2.fileName("foo.cpp");
+  m2.lineNumber(154);
+  m2.tag("myTag");
+
+  axom::lumberjack::TextTagCombiner c;
+
+  bool shouldMessagesBeCombined = c.shouldMessagesBeCombined(m1, m2);
+
+  c.combine(m1, m2, 5);
+
+  EXPECT_EQ(shouldMessagesBeCombined, true);
+  EXPECT_EQ(m1.text().compare(text), 0);
+  EXPECT_EQ(m1.count(), 2);
+  EXPECT_EQ(m1.ranks()[0], 13);
+  EXPECT_EQ(m1.ranks()[1], 14);
+  EXPECT_EQ(m2.tag().compare("myTag"), 0);
+}
+
+TEST(lumberjack_TextTagCombiner, case02)
+{
+  //Test negative case: two not-equal texts, but equal tags
+  std::string text1 = "I never wanted to do this job in the first place!";
+  axom::lumberjack::Message m1;
+  m1.text(text1);
+  m1.addRank(13, 5);
+  m1.fileName("foo.cpp");
+  m1.lineNumber(154);
+  m1.tag("myTag");
+
+  std::string text2 = "This text is not equal to the first.";
+  axom::lumberjack::Message m2;
+  m2.text(text2);
+  m2.addRank(14, 5);
+  m2.fileName("foo.cpp");
+  m2.lineNumber(154);
+  m2.tag("myTag");
+
+  axom::lumberjack::TextTagCombiner c;
+
+  bool shouldMessagesBeCombined = c.shouldMessagesBeCombined(m1, m2);
+
+  EXPECT_EQ(shouldMessagesBeCombined, false);
+  EXPECT_EQ(m1.text().compare(text1), 0);
+  EXPECT_EQ(m1.count(), 1);
+  EXPECT_EQ(m1.ranks()[0], 13);
+  EXPECT_EQ(m1.tag().compare("myTag"), 0);
+
+  EXPECT_EQ(m2.text().compare(text2), 0);
+  EXPECT_EQ(m2.count(), 1);
+  EXPECT_EQ(m2.ranks()[0], 14);
+  EXPECT_EQ(m2.tag().compare("myTag"), 0);
+}
+
+TEST(lumberjack_TextTagCombiner, case03)
+{
+  //Test negative case: two equal texts, but not-equal tags
+  std::string text = "I never wanted to do this job in the first place!";
+
+  axom::lumberjack::Message m1;
+  m1.text(text);
+  m1.addRank(13, 5);
+  m1.fileName("foo.cpp");
+  m1.lineNumber(154);
+  m1.tag("tag1");
+
+  axom::lumberjack::Message m2;
+  m2.text(text);
+  m2.addRank(14, 5);
+  m2.fileName("foo.cpp");
+  m2.lineNumber(154);
+  m2.tag("tag2");
+
+  axom::lumberjack::TextTagCombiner c;
+
+  bool shouldMessagesBeCombined = c.shouldMessagesBeCombined(m1, m2);
+
+  EXPECT_EQ(shouldMessagesBeCombined, false);
+  EXPECT_EQ(m1.text().compare(text), 0);
+  EXPECT_EQ(m1.count(), 1);
+  EXPECT_EQ(m1.ranks()[0], 13);
+  EXPECT_EQ(m1.tag().compare("tag1"), 0);
+
+  EXPECT_EQ(m2.text().compare(text), 0);
+  EXPECT_EQ(m2.count(), 1);
+  EXPECT_EQ(m2.ranks()[0], 14);
+  EXPECT_EQ(m2.tag().compare("tag2"), 0);
+}

src/axom/lumberjack/tests/lumberjack_serial_main.cpp

@@ -8,6 +8,7 @@
 #include "lumberjack_Lumberjack.hpp"
 #include "lumberjack_Message.hpp"
 #include "lumberjack_TextEqualityCombiner.hpp"
+#include "lumberjack_TextTagCombiner.hpp"
 
 int main(int argc, char** argv)
 {

src/axom/slic/core/LogStream.hpp

@@ -88,6 +88,8 @@ class LogStream
    * \param [in] line the line within the file at which the message is appended.
    * \param [in] filter_duplicates optional parameter that indicates whether
    * duplicate messages resulting from running in parallel will be filtered out.
+   * /param [in] tag_stream_only optional parameter that indicates whether the
+   * message will go only to streams bound to tagName.
    *
    * \note The following wildcards may be used to ignore a particular field:
    * <ul>
@@ -101,7 +103,8 @@ class LogStream
                       const std::string& tagName,
                       const std::string& fileName,
                       int line,
-                      bool filter_duplicates) = 0;
+                      bool filter_duplicates,
+                      bool tag_stream_only) = 0;
 
   /*!
    * \brief Outputs the log stream on the current rank to the console.