#672: docs: start writing docs for AM, Context, overvie

docs/Doxyfile.in-mcss

@@ -3,4 +3,17 @@ GENERATE_HTML           = YES
 GENERATE_XML            = YES
 XML_PROGRAMLISTING      = NO
 M_SHOW_UNDOCUMENTED     = YES
-EXTRACT_ALL             = YES
+EXTRACT_ALL             = YES
+
+ALIASES += \
+    "vt=<b><i>vt</i></b>" \
+    "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
+    "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
+    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
+    "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
+    "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
+    "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
+    "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
+    "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly"

scripts/build_vt.pl

@@ -154,6 +154,7 @@ sub mk {
       -DCMAKE_BUILD_TYPE=$build_mode                                         \\
       -DCMAKE_VERBOSE_MAKEFILE:BOOL=$verbose                                 \\
       -DCMAKE_CXX_COMPILER=$cxx                                              \\
+      -Dvt_doxygen_enabled:BOOL=true\\
       -DCMAKE_C_COMPILER=$cc                                                 \\
       ${mpi_str}
 CMAKESTR

src/active-messenger.md

@@ -0,0 +1,23 @@
+
+\page active-messenger Active Messenger
+\brief Asynchronous send/receive of messages
+
+The active messenger, accessed via `vt::theMsg()`, asynchronously sends and
+receives messages across nodes using MPI internally. When sending a message, it
+uses the \vt registry to consistently dispatch messages and data to handlers
+(function pointers, functors, or methods) across nodes (even with address space
+randomization). Each message contains an envelope `vt::Envelope` to store
+meta-data associated with the message, such as the destination and handler to
+trigger when it arrives. Sending a message entails setting up the envelope,
+optionally serializing the message (depending on whether the serialize overload is
+present), and then using `MPI_Isend` to asynchronously transfer the bytes to the
+destination node. On the receive side, the active messenger is always probing for a
+incoming message and begins a transfer when it discovers one. The \vt scheduler
+polls the active messenger to make progress on any incoming messages.
+
+\copydoc vt::messaging::ActiveMessenger
+
+\section am-simple-example Sending a message
+
+\code{.cpp}
+\endcode

src/context.md

@@ -0,0 +1,36 @@
+
+\page context Context
+\brief Node-aware context
+
+The context component, accessed via `vt::theContext()`, provides context-aware
+querying of the current node (analogous to MPI's \c MPI_Comm_rank), number of
+nodes (analogous to MPI's \c MPI_Comm_size), and kernel threading/ULT
+information if worker threads are enabled. The context also provides the MPI
+communicator that an instance of \vt is currently using.
+
+\copybrief vt::ctx::Context
+\copydetails vt::ctx::Context
+
+\subsection get-node Current node/rank
+
+\copybrief vt::ctx::Context::getNode()
+
+To get the current node, one may query this method:
+
+\code{.cpp}
+vt::NodeType this_node = vt::theContext()->getNode();
+\endcode
+
+\subsection get-num-nodes Number of nodes/ranks
+
+\copybrief vt::ctx::Context::getNumNodes()
+
+To get the number of nodes or ranks that an instance of \vt is using, one may
+query this method:
+
+\code{.cpp}
+vt::NodeType num_nodes = vt::theContext()->getNumNodes();
+\endcode
+
+\note The result from \c getNode or \c getNumNodes will depend on the
+communicator that was passed to VT during initialization.

src/vt.md

@@ -0,0 +1,95 @@
+
+\page introduction Introduction to DARMA/vt
+\brief Overview of functionality in \vt
+
+\tableofcontents
+
+\section what-is What is vt?
+
+\vt is an active messaging layer that utilizes C++ object virtualization to
+manage virtual endpoints with automatic location management. \vt is directly
+built on top of MPI to provide efficient portability across different machine
+architectures. Empowered with virtualization, \vt can automatically perform
+dynamic load balancing to schedule scientific applications across diverse
+platforms with minimal user input.
+
+\vt abstracts the concept of a `node`/`rank`/`worker`/`thread` so a program can
+be written in terms of virtual entities that are location independent. Thus,
+they can be automatically migrated and thereby executed on varying hardware
+resources without explicit programmer mapping, location, and communication
+management.
+
+\section vt-features Features in vt
+
+- Active messaging to type-safe handlers across nodes
+- Groups for scalable construction of node subsets
+- Optional serialization of messages
+- Termination detection across entire or subset of DAG with \e epochs
+- Opaque callbacks/pipes to generalized endpoints
+- Efficient memory pooling for message allocation
+- RDMA using MPI one-sided for data transfer
+- Asynchronous Collectives across nodes/groups (scatter, async barrier, reduce, ...)
+- General scheduler with prioritization
+- Built-in interoperability with MPI and threading libraries (Kokkos, OpenMP, ...)
+- Object groups for node-level encapsulation
+- Virtual contexts for migratable virtualization and dispatch
+- Abstractions for multi-dimensional indices, mapping, and linearization
+- Virtual collections (dense, sparse, dynamic insertable) for decomposing domains
+- Fully distributed load balancer for virtual entities
+
+\section vt-components Components in vt
+
+| Component                   | Singleton           | Details                     |
+| --------------------------- | ------------------- | --------------------------- |
+| \subpage context            | `vt::theContext()`  | \copybrief context          |
+| \subpage active-messenger   | `vt::theMsg()`      | \copybrief active-messenger |
+
+\section vt-hello-world Example
+
+\m_class{m-block m-success}
+\parblock
+    \m_class{m-code-figure} \parblock
+        \code{.cpp}
+        struct HelloMsg : vt::Message {
+          HelloMsg(vt::NodeType in_from) : from(in_from) { }
+          vt::NodeType from = 0;
+        };
+
+        void hello_world(HelloMsg* msg) {
+          vt::NodeType this_node = vt::theContext()->getNode();
+          fmt::print("{}: Hello from node {}\n", this_node, msg->from);
+        }
+
+        int main(int argc, char** argv) {
+          vt::initialize(argc, arv);
+
+          vt::NodeType this_node = vt::theContext()->getNode();
+          vt::NodeType num_nodes = vt::theContext()->getNumNodes();
+
+          if (this_node == 0) {
+            auto msg = vt::makeMessage<HelloMsg>(this_node);
+            vt::theMsg()->broadcastMsg<HelloMsg, hello_world>(msg.get());
+          }
+
+          vt::finalize();
+          return 0;
+        }
+        \endcode
+
+        Running:
+
+        \code{.shell-session}
+        $ mpirun -n 4 ./hello_world
+        \endcode
+
+        Output:
+        \code{.shell-session}
+        3: Hello from node 0
+        1: Hello from node 0
+        2: Hello from node 0
+        \endcode
+
+        \note An active message broadcast sends to all nodes except for
+the sender (root of the broadcast).
+    \endparblock
+\endparblock