1052 Implement epoch scopes

cmake/define_build_types.cmake

@@ -54,6 +54,7 @@ set(
    CatEnum::vrt_coll     | \
    CatEnum::group        | \
    CatEnum::phase        | \
+   CatEnum::epoch        | \
    CatEnum::broadcast      \
    "
 )

docs/md/epoch.md

@@ -0,0 +1,10 @@
+\page epoch Epoch Manager
+\brief Manage TD epochs
+
+The epoch manager component `vt::epoch::EpochManip`, accessed via
+`vt::theEpoch()`, manages termination epochs that are allocated and deallocated
+as a program executes to encapsulate and order distributed work. The epoch
+manager controls the bits allocated for these along with scopes (distinct,
+collective strands of epoch bit allocation) for generating the bits. The epoch
+manager also allows inspection of information embedded in the epoch bit field
+`vt::EpochType` that encodes the epoch type, category, scope, rank, etc.

docs/md/vt.md

@@ -62,6 +62,7 @@ management.
 | \subpage seq                | `vt::theSeq()`         | \copybrief seq              | @m_class{m-label m-danger} **Experimental**    |
 | \subpage vrtseq             | `vt::theVirtualSeq()`  | \copybrief vrtseq           | @m_class{m-label m-danger} **Experimental**    |
 | \subpage term               | `vt::theTerm()`        | \copybrief term             | @m_class{m-label m-success} **Core**           |
+| \subpage epoch              | `vt::theEpoch()`       | \copybrief epoch            | @m_class{m-label m-success} **Core**           |
 | \subpage time-trigger       | `vt::theTimeTrigger()` | \copybrief time-trigger     | @m_class{m-label m-warning} **Optional**       |
 | \subpage trace              | `vt::theTrace()`       | \copybrief trace            | @m_class{m-label m-warning} **Optional**       |
 | \subpage stats-reader       | `vt::theStatsReader()` | \copybrief stats-reader     | @m_class{m-label m-warning} **Optional**       |

src/vt/configs/arguments/app_config.h

@@ -151,6 +151,7 @@ struct AppConfig {
   bool vt_epoch_graph_terse    = false;
   bool vt_term_rooted_use_ds   = false;
   bool vt_term_rooted_use_wave = false;
+  double vt_term_gc_threshold  = 0.10;
   int64_t vt_hang_freq         = 1024;
 
 #if (vt_diagnostics_runtime != 0)
@@ -200,6 +201,7 @@ struct AppConfig {
   bool vt_debug_broadcast    = false;
   bool vt_debug_objgroup     = false;
   bool vt_debug_phase        = false;
+  bool vt_debug_epoch        = false;
 
   bool vt_debug_print_flush = false;
 
@@ -299,6 +301,7 @@ struct AppConfig {
       | vt_epoch_graph_terse
       | vt_term_rooted_use_ds
       | vt_term_rooted_use_wave
+      | vt_term_gc_threshold
       | vt_hang_freq
 
       | vt_pause
@@ -336,6 +339,7 @@ struct AppConfig {
       | vt_debug_group
       | vt_debug_broadcast
       | vt_debug_objgroup
+      | vt_debug_epoch
 
       | vt_debug_print_flush
 

src/vt/configs/arguments/args.cc

@@ -251,6 +251,7 @@ void ArgConfig::addDebugPrintArgs(CLI::App& app) {
   auto cbp = "Enable debug_broadcast    = \"" debug_pp(broadcast)    "\"";
   auto dbp = "Enable debug_objgroup     = \"" debug_pp(objgroup)     "\"";
   auto dcp = "Enable debug_phase        = \"" debug_pp(phase)        "\"";
+  auto ddp = "Enable debug_epoch        = \"" debug_pp(epoch)        "\"";
 
   auto r  = app.add_flag("--vt_debug_all",          config_.vt_debug_all,          rp);
   auto r1 = app.add_flag("--vt_debug_verbose",      config_.vt_debug_verbose,      rq);
@@ -286,6 +287,7 @@ void ArgConfig::addDebugPrintArgs(CLI::App& app) {
   auto cb = app.add_flag("--vt_debug_broadcast",    config_.vt_debug_broadcast,    cbp);
   auto db = app.add_flag("--vt_debug_objgroup",     config_.vt_debug_objgroup,     dbp);
   auto dc = app.add_flag("--vt_debug_phase",        config_.vt_debug_phase,        dcp);
+  auto dd = app.add_flag("--vt_debug_epoch",        config_.vt_debug_epoch,        ddp);
   auto debugGroup = "Debug Print Configuration (must be compile-time enabled)";
   r->group(debugGroup);
   r1->group(debugGroup);
@@ -321,6 +323,7 @@ void ArgConfig::addDebugPrintArgs(CLI::App& app) {
   cb->group(debugGroup);
   db->group(debugGroup);
   dc->group(debugGroup);
+  dd->group(debugGroup);
 
   auto dbq = "Always flush VT runtime prints";
   auto eb  = app.add_flag("--vt_debug_print_flush", config_.vt_debug_print_flush, dbq);
@@ -412,14 +415,17 @@ void ArgConfig::addTerminationArgs(CLI::App& app) {
   auto graph_on     = "Output epoch graph to file (DOT) when hang is detected";
   auto terse        = "Output epoch graph to file in terse mode";
   auto progress     = "Print termination counts when progress is stalled";
+  auto gc_thresh    = "Set the threshold for garbage collecting used epoch (0.1 -> 10% of total epochs)";
   auto hfd          = 1024;
+  auto thresh       = 0.1;
   auto x  = app.add_flag("--vt_no_detect_hang",        config_.vt_no_detect_hang,       hang);
   auto x1 = app.add_flag("--vt_term_rooted_use_ds",    config_.vt_term_rooted_use_ds,   ds);
   auto x2 = app.add_flag("--vt_term_rooted_use_wave",  config_.vt_term_rooted_use_wave, wave);
   auto x3 = app.add_option("--vt_epoch_graph_on_hang", config_.vt_epoch_graph_on_hang,  graph_on, true);
   auto x4 = app.add_flag("--vt_epoch_graph_terse",     config_.vt_epoch_graph_terse,    terse);
   auto x5 = app.add_option("--vt_print_no_progress",   config_.vt_print_no_progress,    progress, true);
-  auto y = app.add_option("--vt_hang_freq",            config_.vt_hang_freq,      hang_freq, hfd);
+  auto y = app.add_option("--vt_hang_freq",            config_.vt_hang_freq,            hang_freq, hfd);
+  auto z = app.add_option("--vt_term_gc_threshold",    config_.vt_term_gc_threshold,    gc_thresh, thresh);
   auto debugTerm = "Termination";
   x->group(debugTerm);
   x1->group(debugTerm);
@@ -428,6 +434,7 @@ void ArgConfig::addTerminationArgs(CLI::App& app) {
   x4->group(debugTerm);
   x5->group(debugTerm);
   y->group(debugTerm);
+  z->group(debugTerm);
 }
 
 void ArgConfig::addDebuggerArgs(CLI::App& app) {

src/vt/configs/debug/debug_config.h

@@ -82,6 +82,7 @@ enum CatEnum : uint64_t {
   objgroup     = 1ull<<29,
   gossiplb     = 1ull<<30,
   phase        = 1ull<<31,
+  epoch        = 1ull<<32
 };
 
 enum CtxEnum : uint64_t {
@@ -120,6 +121,7 @@ vt_option_category_pretty_print(none,         "none")
 vt_option_category_pretty_print(active,       "active")
 vt_option_category_pretty_print(barrier,      "barrier")
 vt_option_category_pretty_print(broadcast,    "bcast")
+vt_option_category_pretty_print(epoch,        "epoch")
 vt_option_category_pretty_print(event,        "event")
 vt_option_category_pretty_print(gen,          "general")
 vt_option_category_pretty_print(group,        "group")

src/vt/epoch/epoch.h

@@ -61,18 +61,22 @@ namespace vt { namespace epoch {
  *
  *   w-1 .............. w-h-1 ...............w-h-c-1 ....................0
  *   | <EpochHeader> ... | <EpochCategory> ... | <Sequential Epoch ID>   |
- *
- *      *where*    h = epoch_header_num_bits,
- *                 c = epoch_category_num_bits,
- *                 w = sizeof(EpochType) * 8
- *                 n = sizeof(NodeType)        ^             ^           ^
- *                                             | .... n .... | ..........|
- *                                               <NodeType>  <SeqEpochID>
+ *                                             |                          \
+ *      *where*    h = epoch_header_num_bits,  |                           \
+ *                 c = epoch_category_num_bits,|                            \
+ *                 w = sizeof(EpochType) * 8   |                             \
+ *                 n = sizeof(NodeType)        ^  16  ^ 5 ^   [remainder]     ^
+ *                                            /                               |
+ *                                           /                                |
+ *                                   _______                                  |
+ *                                  /                                          \
+ *                                  | .... n .... | ... scope ... | ...........|
+ *                                    <NodeType>   <EpochScopeType> <SeqEpochID>
  *
  *  +++++++++++++++++++++++++++++++++++++++++++  Rooted Extended Layout ++
  *
- *   <EpochHeader>   = <IsRooted> <HasCategory> <IsUser>
- *   ....3 bits...   = ..bit 1..   ...bit 2...  ..bit 3..
+ *   <EpochHeader>   = <IsRooted> <HasCategory>
+ *   ....3 bits...   = ..bit 1..   ...bit 2...
  *
  * =======================================================================
  * \endverbatim
@@ -82,17 +86,11 @@ namespace vt { namespace epoch {
  * \brief The header bit positions for an epoch (\c vt::EpochType)
  */
 enum struct eEpochHeader : int8_t {
-  RootedEpoch   = 1,
-  CategoryEpoch = 2,
-  UserEpoch     = 3
+  RootedEpoch   = 1
 };
 
 /// Number of bits for root flag
 static constexpr BitCountType const epoch_root_num_bits = 1;
-/// Number of bits for category flag
-static constexpr BitCountType const epoch_hcat_num_bits = 1;
-/// Number of bits for user flag
-static constexpr BitCountType const epoch_user_num_bits = 1;
 
 /**
  *  Important: if you add new types of epoch headers to the preceding enum, you
@@ -101,6 +99,15 @@ static constexpr BitCountType const epoch_user_num_bits = 1;
  *
  */
 
+/**
+ * \brief The number of bits for all types of categories.
+ *
+ *  Important: if you add categories to the enum of epoch categories, you must
+ *  ensure the \c epoch_category_num_bits is sufficiently large.
+ *
+ */
+static constexpr BitCountType const epoch_category_num_bits = 2;
+
 /**
  * \brief These are different categories of epochs that are allowed.
  *
@@ -118,43 +125,78 @@ inline std::ostream& operator<<(std::ostream& os, eEpochCategory const& cat) {
   return debug::printEnum<eEpochCategory>(os,cat);
 }
 
-/**
- * \brief The number of bits for all types of categories.
- *
- *  Important: if you add categories to the enum of epoch categories, you must
- *  ensure the \c epoch_category_num_bits is sufficiently large.
- *
- */
-static constexpr BitCountType const epoch_category_num_bits = 2;
+/// Holds a epoch scope ID (collectively generated)
+using EpochScopeType = uint64_t;
+
+/// The default, global epoch scope
+static constexpr EpochScopeType const global_epoch_scope = 0;
+
+// Number of bits allocated for an epoch scope
+static constexpr BitCountType const scope_bits = 20;
 
-/// The total number of bits remaining the sequential part of the \c EpochType
-static constexpr BitCountType const epoch_seq_num_bits = sizeof(EpochType) * 8 -
-  (epoch_root_num_bits     +
-   epoch_hcat_num_bits     + epoch_user_num_bits +
-   epoch_category_num_bits + node_num_bits);
+/// The limit on number of live scopes at a given time;
+/// Scope 0 is the default scope so that is excluded as a valid scope
+static constexpr EpochScopeType const scope_limit = (1<<scope_bits) - 1;
+
+/// The scope sentinel
+static constexpr EpochScopeType const no_scope = ~0ull;
+
+/// The number of sequential ID bits remaining for a collective \c EpochType
+static constexpr BitCountType const epoch_seq_coll_num_bits =
+  sizeof(EpochType) * 8 -
+  (epoch_root_num_bits + epoch_category_num_bits + scope_bits);
+
+/// The total number of bits remaining for a rooted \c EpochType
+static constexpr BitCountType const epoch_seq_root_num_bits =
+  sizeof(EpochType) * 8 -
+  (epoch_root_num_bits + epoch_category_num_bits + scope_bits + node_num_bits);
 
 /**
- *  \brief Epoch layout enum to help with manipuating the bits
+ *  \brief Epoch layout enum for collective epochs to help with manipulating the
+ *  bits
  *
  *  This describes the layout of the epoch used by \c EpochManip to get/set the
  *  bits on an \c EpochType field
  */
-enum eEpochLayout {
-  EpochSequential   = 0,
-  EpochNode         = eEpochLayout::EpochSequential  + epoch_seq_num_bits,
-  EpochCategory     = eEpochLayout::EpochNode        + node_num_bits,
-  EpochUser         = eEpochLayout::EpochCategory    + epoch_category_num_bits,
-  EpochHasCategory  = eEpochLayout::EpochUser        + epoch_user_num_bits,
-  EpochIsRooted     = eEpochLayout::EpochHasCategory + epoch_hcat_num_bits,
-  EpochSentinelEnd  = eEpochLayout::EpochIsRooted
+enum eEpochColl {
+  cEpochSequential = 0,
+  cEpochScope      = eEpochColl::cEpochSequential + epoch_seq_coll_num_bits,
+  cEpochCategory   = eEpochColl::cEpochScope      + scope_bits,
+  cEpochIsRooted   = eEpochColl::cEpochCategory   + epoch_category_num_bits
 };
 
 /**
- *  The first basic epoch: BasicEpoch, NoCategoryEpoch:
+ *  \brief Epoch layout enum for rooted epochs to help with manipulating the
+ *  bits
+ *
+ *  This describes the layout of the epoch used by \c EpochManip to get/set the
+ *  bits on an \c EpochType field
  */
+enum eEpochRoot {
+  rEpochSequential = 0,
+  rEpochNode       = eEpochRoot::rEpochSequential + epoch_seq_root_num_bits,
+  rEpochScope      = eEpochRoot::rEpochNode       + node_num_bits,
+  rEpochCategory   = eEpochRoot::rEpochScope      + scope_bits,
+  rEpochIsRooted   = eEpochRoot::rEpochCategory   + epoch_category_num_bits
+};
 
+/// The first epoch sequence number
 static constexpr EpochType const first_epoch = 1;
 
+/// The default epoch node used for non-rooted epochs
+static constexpr NodeType const default_epoch_node = uninitialized_destination;
+
+/// The default epoch category
+static constexpr eEpochCategory const default_epoch_category =
+  eEpochCategory::NoCategoryEpoch;
+
 }} //end namespace vt::epoch
 
+namespace vt {
+
+/// Type for epoch scope bits embedded in an \c EpochType
+using EpochScopeType = epoch::EpochScopeType;
+
+} /* end namespace vt */
+
 #endif /*INCLUDED_EPOCH_EPOCH_H*/

src/vt/epoch/epoch_manip_set.h → src/vt/epoch/epoch_garbage_collect.cc

@@ -2,7 +2,7 @@
 //@HEADER
 // *****************************************************************************
 //
-//                              epoch_manip_set.h
+//                           epoch_garbage_collect.cc
 //                           DARMA Toolkit v. 1.0.0
 //                       DARMA/vt => Virtual Transport
 //
@@ -42,55 +42,44 @@
 //@HEADER
 */
 
-#if !defined INCLUDED_EPOCH_EPOCH_MANIP_SET_H
-#define INCLUDED_EPOCH_EPOCH_MANIP_SET_H
-
 #include "vt/config.h"
-#include "vt/epoch/epoch.h"
+#include "vt/epoch/epoch_garbage_collect.h"
+#include "vt/epoch/garbage_collect_msg.h"
 #include "vt/epoch/epoch_manip.h"
-#include "vt/utils/bits/bits_common.h"
-#include "vt/utils/bits/bits_packer.h"
+#include "vt/collective/collective_alg.h"
 
 namespace vt { namespace epoch {
 
-/*static*/ inline
-void EpochManip::setIsRooted(EpochType& epoch, bool const is_rooted) {
-  BitPackerType::boolSetField<eEpochLayout::EpochIsRooted,1,EpochType>(epoch,is_rooted);
-}
+void GarbageCollectTrait::reducedEpochsImpl(GarbageCollectMsg* msg) {
+  auto const ep = msg->getEpoch();
 
-/*static*/ inline
-void EpochManip::setHasCategory(EpochType& epoch, bool const has_cat) {
-  BitPackerType::boolSetField<eEpochLayout::EpochHasCategory,1,EpochType>(
-    epoch,has_cat
+  vt_debug_print(
+    epoch, node,
+    "GarbageCollectTrait::reducedEpochsImpl: archetype={:x}\n", ep
   );
-}
 
-/*static*/ inline
-void EpochManip::setIsUser(EpochType& epoch, bool const is_user) {
-  BitPackerType::boolSetField<eEpochLayout::EpochUser,1,EpochType>(
-    epoch,is_user
-  );
-}
+  auto const mask = 0xFFFFFFFF00000000ull;
+  vtAssert((ep & mask) == ep, "Archetype bits should not extend past 32 bits");
+  TagType const topbits = static_cast<TagType>(ep >> 32);
 
-/*static*/ inline
-void EpochManip::setCategory(EpochType& epoch, eEpochCategory const cat) {
-  BitPackerType::setField<
-    eEpochLayout::EpochCategory, epoch_category_num_bits
-  >(epoch,cat);
-}
+  // Achieve consensus on garbage collecting these epochs
+  auto scope = theCollective()->makeCollectiveScope(topbits);
 
-/*static*/ inline
-void EpochManip::setNode(EpochType& epoch, NodeType const node) {
-  BitPackerType::setField<eEpochLayout::EpochNode, node_num_bits>(epoch,node);
-}
+  vt_debug_print(
+    epoch, node,
+    "reducedEpochsImpl: archetype={:x} start MPI collective: num epochs={}\n",
+    ep, msg->getVal().getSet().size()
+  );
+
+  scope.mpiCollectiveWait([ep,msg]{
+    auto window = theEpoch()->getTerminatedWindow(ep);
+    window->garbageCollect(msg->getVal().getSet());
+  });
 
-/*static*/ inline
-void EpochManip::setSeq(EpochType& epoch, EpochType const seq) {
-  BitPackerType::setField<
-    eEpochLayout::EpochSequential, epoch_seq_num_bits
-  >(epoch,seq);
+  vt_debug_print(
+    epoch, node,
+    "reducedEpochsImpl: archetype={:x} done MPI collective\n", ep
+  );
 }
 
 }} /* end namespace vt::epoch */
-
-#endif /*INCLUDED_EPOCH_EPOCH_MANIP_SET_H*/