Add option to allow Lumberjack to own communicator

RELEASE-NOTES.md

@@ -43,6 +43,7 @@ to use Open Cascade's file I/O capabilities in support of Quest applications.
 - Adds intersection routines between `primal::Ray` objects and `primal::NURBSCurve`/`primal::NURBSPatch` objects.
 - Adds LineFileTagCombiner to Lumberjack to allow combining messages if line number, file, and tag are equal.
 - Adds some support for 2D shaping in `quest::IntersectionShaper`, using STL meshes with zero for z-coordinates or in-memory triangles as input.
+- Adds ability in Lumberjack to own and set communicators.
 - Adds `NonCollectiveRootCommunicator` to Lumberjack to provide an MPI-based communicator for logging messages non-collectively.
 
 ###  Changed

src/axom/lumberjack/Lumberjack.cpp

@@ -14,20 +14,37 @@
  */
 
 #include "axom/lumberjack/Lumberjack.hpp"
+#include <iostream>
 
 namespace axom
 {
 namespace lumberjack
 {
-void Lumberjack::initialize(Communicator* communicator, int ranksLimit)
+void Lumberjack::initialize(Communicator* communicator,
+                            int ranksLimit,
+                            bool isCommunicatorOwned)
 {
-  m_communicator = communicator;
-  m_ranksLimit = ranksLimit;
-  m_combiners.push_back(new TextTagCombiner);
+  if(m_isInitialized == false)
+  {
+    m_isInitialized = true;
+    m_communicator = communicator;
+    m_isCommunicatorOwned = isCommunicatorOwned;
+    m_ranksLimit = ranksLimit;
+    m_combiners.push_back(new TextTagCombiner);
+  }
+  else
+  {
+    std::cerr << "Lumberjack::initialize called more than once" << std::endl;
+  }
 }
 
 void Lumberjack::finalize()
 {
+  if(m_isCommunicatorOwned && m_communicator != nullptr)
+  {
+    m_communicator->finalize();
+    delete m_communicator;
+  }
   m_communicator = nullptr;
   clearCombiners();
   clearMessages();
@@ -179,6 +196,22 @@ void Lumberjack::pushMessagesFully()
 
 bool Lumberjack::isOutputNode() { return m_communicator->isOutputNode(); }
 
+void Lumberjack::setCommunicator(Communicator* communicator,
+                                 bool isCommunicatorOwned)
+{
+  if(m_isCommunicatorOwned && m_communicator != nullptr)
+  {
+    m_communicator->finalize();
+    delete m_communicator;
+  }
+  m_isCommunicatorOwned = isCommunicatorOwned;
+  m_communicator = communicator;
+}
+
+Communicator* Lumberjack::getCommunicator() { return m_communicator; }
+
+bool Lumberjack::isCommunicatorOwned() { return m_isCommunicatorOwned; }
+
 void Lumberjack::combineMessages()
 {
   int messagesSize = (int)m_messages.size();
@@ -229,4 +262,4 @@ void Lumberjack::combineMessages()
   m_messages.swap(finalMessages);
 }
 }  // end namespace lumberjack
-}  // end namespace axom
+}  // end namespace axom

src/axom/lumberjack/Lumberjack.hpp

@@ -55,9 +55,13 @@ class Lumberjack
    * messages
    * \param [in] ranksLimit Limit on how many ranks are individually tracker per
    * Message.
+   * \param [in] isCommunicatorOwned When set to true, Lumberjack will be 
+   * responsible for freeing communication object when finalize() is called.
    *****************************************************************************
    */
-  void initialize(Communicator* communicator, int ranksLimit);
+  void initialize(Communicator* communicator,
+                  int ranksLimit,
+                  bool isCommunicatorOwned = false);
 
   /*!
    *****************************************************************************
@@ -229,6 +233,33 @@ class Lumberjack
    */
   bool isOutputNode();
 
+  /*!
+   *****************************************************************************
+   * \brief set communicator pointer stored in object as well as ownership
+   *
+   *****************************************************************************
+   */
+  void setCommunicator(Communicator* communicator, bool isCommunicatorOwned);
+
+  /*!
+   *****************************************************************************
+   * \brief get communicator pointer stored in object
+   *
+   * \return Communicator pointer
+   *****************************************************************************
+   */
+  Communicator* getCommunicator();
+
+  /*!
+   *****************************************************************************
+   * \brief Returns Boolean flag that controls whether communicator instance is 
+   * owned by Lumberjack
+   *
+   * \return Communicator pointer
+   *****************************************************************************
+   */
+  bool isCommunicatorOwned();
+
 private:
   /*!
    *****************************************************************************
@@ -238,7 +269,10 @@ class Lumberjack
    */
   void combineMessages();
 
+  bool m_isInitialized = false;
+
   Communicator* m_communicator;
+  bool m_isCommunicatorOwned;
   int m_ranksLimit;
   std::vector<Combiner*> m_combiners;
   std::vector<Message*> m_messages;

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

@@ -18,8 +18,8 @@ General
 ============== ===================
 Name           Description
 ============== ===================
-initialize     Starts up Lumberjack. Must be called before anything else.
-finalize       Cleans up Lumberjack. Must be called when done with Lumberjack.
+initialize     Starts up Lumberjack. Must be called before anything else. Can only be called once per instance.
+finalize       Cleans up Lumberjack. Must be called when done with Lumberjack. Can only be called once per instance.
 isOutputNode   Returns whether this node should output messages.
 ranksLimit     Sets the limit on individually tracked ranks
 ranksLimit     Gets the limit on individually tracked ranks
@@ -49,3 +49,13 @@ pushMessagesOnce   Moves Messages up the communication scheme once
 pushMessagesFully  Moves all Messages through the communication scheme to the output node.
 ================== ===================
 
+Communicators
+^^^^^^^^^^^^^
+
+===================== ===================
+Name                  Description
+===================== ===================
+setCommunicator       Sets communicator instance stored in Lumberjack and sets the communicator ownership status
+getCommunicator       Returns pointer to communicator instance stored in Lumberjack
+isCommunicatorOwned   Returns Boolean flag that controls whether communicator instance is owned by Lumberjack
+===================== ===================

src/axom/lumberjack/tests/lumberjack_Lumberjack.hpp

@@ -437,3 +437,77 @@ TEST(lumberjack_Lumberjack, combineMessagesLargeMessages)
   lumberjack.finalize();
   communicator.finalize();
 }
+
+TEST(lumberjack_Lumberjack, setNonOwnedCommunicator)
+{
+  int ranksLimit = 5;
+  auto communicator1 = new TestCommunicator();
+  communicator1->initialize(MPI_COMM_NULL, ranksLimit);
+
+  auto communicator2 = new TestCommunicator();
+  communicator2->initialize(MPI_COMM_NULL, ranksLimit);
+
+  axom::lumberjack::Lumberjack lumberjack;
+
+  lumberjack.initialize(communicator1, ranksLimit);
+
+  EXPECT_EQ(communicator1, lumberjack.getCommunicator());
+  EXPECT_EQ(lumberjack.isCommunicatorOwned(), false);
+
+  lumberjack.setCommunicator(communicator2, false);
+
+  /* communicator1 should still be valid after set
+     because it's not owned by Lumberjack*/
+  EXPECT_NE(communicator1, nullptr);
+  EXPECT_EQ(communicator2, lumberjack.getCommunicator());
+
+  lumberjack.finalize();
+  communicator1->finalize();
+  communicator2->finalize();
+  delete communicator1;
+  delete communicator2;
+}
+
+TEST(lumberjack_Lumberjack, setOwnedCommunicator)
+{
+  int ranksLimit = 5;
+  auto communicator = new TestCommunicator();
+  communicator->initialize(MPI_COMM_NULL, ranksLimit);
+
+  axom::lumberjack::Lumberjack lumberjack;
+
+  lumberjack.initialize(new TestCommunicator(), ranksLimit, true);
+
+  EXPECT_NE(lumberjack.getCommunicator(), nullptr);
+  EXPECT_EQ(lumberjack.isCommunicatorOwned(), true);
+
+  lumberjack.setCommunicator(communicator, true);
+
+  EXPECT_EQ(lumberjack.getCommunicator(), communicator);
+  EXPECT_EQ(lumberjack.isCommunicatorOwned(), true);
+
+  lumberjack.finalize();
+}
+
+TEST(lumberjack_Lumberjack, setOwnedAndNonOwnedCommunicator)
+{
+  int ranksLimit = 5;
+  auto communicator = new TestCommunicator();
+  communicator->initialize(MPI_COMM_NULL, ranksLimit);
+
+  axom::lumberjack::Lumberjack lumberjack;
+
+  lumberjack.initialize(new TestCommunicator(), ranksLimit, true);
+
+  EXPECT_NE(lumberjack.getCommunicator(), nullptr);
+  EXPECT_EQ(lumberjack.isCommunicatorOwned(), true);
+
+  lumberjack.setCommunicator(communicator, false);
+
+  EXPECT_EQ(lumberjack.getCommunicator(), communicator);
+  EXPECT_EQ(lumberjack.isCommunicatorOwned(), false);
+
+  lumberjack.finalize();
+  communicator->finalize();
+  delete communicator;
+}