Merge pull request #259 from DARMA-tasking/249-non-intrusive-examples…

…-and-docs

#249: Non-Intrusive examples and docs

docs/md/checkpoint_learn_example_2.md

@@ -3,5 +3,6 @@
 The full code for this *checkpoint* example can be found here:
 `examples/checkpoint_example_2.cc`
 
+\subsubsection ex Example source code:
 \snippet examples/checkpoint_example_2.cc Serialize custom structure
 

docs/md/checkpoint_learn_example_2_nonintrusive.md

@@ -0,0 +1,10 @@
+\page ckpt_learn_ex2_nonintrusive Non-Intrusive Program Example 2
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_2_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_2_nonintrusive.cc Non-Intrusive Serialize custom structure
+

docs/md/checkpoint_learn_example_3.md

@@ -3,4 +3,5 @@
 The full code for this *checkpoint* example can be found here:
 `examples/checkpoint_example_3.cc`
 
+\subsubsection ex3 Example source code:
 \snippet examples/checkpoint_example_3.cc Serialize constraints constructor destructor

docs/md/checkpoint_learn_example_3_nonintrusive.md

@@ -0,0 +1,9 @@
+\page ckpt_learn_ex3_nonintrusive Non-Intrusive Program Example 3
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_3_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_3_nonintrusive.cc Non-Intrusive Serialize constraints constructor destructor

docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md

@@ -0,0 +1,9 @@
+\page ckpt_learn_example_polymorphic_macro_nonintrusive Non-Intrusive Polymorphic Serialization Example w/Macros
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_polymorphic_macro_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_polymorphic_macro_nonintrusive.cc Non-Intrusive Serialize polymorphic macro

docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md

@@ -0,0 +1,9 @@
+\page ckpt_learn_example_polymorphic_nonintrusive Non-Intrusive Polymorphic Serialization Example
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_polymorphic_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_polymorphic_nonintrusive.cc Non-Intrusive Serialize polymorphic

docs/md/checkpoint_learn_example_to_file.md

@@ -1,8 +1,10 @@
 \page ckpt_learn_ex_tofile Program Example Serialize To File
 
-The full code for this example can be found here:
-`examples/checkpoint_example_to_file.cc`
 One potential application for this approach is to generate a restart file
 for a simulation.
 
+The full code for this example can be found here:
+`examples/checkpoint_example_to_file.cc`
+
+\subsubsection ex Example source code:
 \snippet examples/checkpoint_example_to_file.cc Serialize structure to file

docs/md/checkpoint_learn_example_to_file_nonintrusive.md

@@ -0,0 +1,12 @@
+\page ckpt_learn_ex_tofile_nonintrusive Non-Intrusive Program Example Serialize To File
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+One potential application for this approach is to generate a restart file
+for a simulation.
+
+The full code for this example can be found here:
+`examples/checkpoint_example_to_file_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_to_file_nonintrusive.cc Non-Intrusive Serialize structure to file

docs/md/checkpoint_learn_example_traversal.md

@@ -0,0 +1,8 @@
+\page ckpt_learn_ex_traversal Program Example Traversal
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_traversal.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_traversal.cc Serialization with custom traverser
+

docs/md/checkpoint_learn_example_traversal_nonintrusive.md

@@ -0,0 +1,10 @@
+\page ckpt_learn_ex_traversal_nonintrusive Non-Intrusive Program Example Traversal
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_traversal_nonintrusive.cc`
+
+\subsubsection ex Example source code:
+\snippet examples/checkpoint_example_traversal_nonintrusive.cc Non-Intrusive Serialization with custom traverser
+

docs/md/checkpoint_learn_examples.md

@@ -1,11 +1,27 @@
 \page ckpt_learn_examples Examples
 
-| Examples    | Description | Link |
-| ----------- | ----------- | ---- |
+| Intrusive Examples    | Description | Link |
+| --------------------- | ----------- | ---- |
 | checkpoint_example_1 | Serialization of a structure | \subpage ckpt_learn_ex1 |
 | checkpoint_example_2 | Serialization of a custom structure | \subpage ckpt_learn_ex2 |
 | checkpoint_example_3 | Illustrate needs for constructor/destructor | \subpage ckpt_learn_ex3 |
 | checkpoint_example_to_file | Serialize / deserialize structure to file | \subpage ckpt_learn_ex_tofile |
 | checkpoint_example_polymorphic | Serialization of polymorphic class hierarchy | \subpage ckpt_learn_example_polymorphic |
 | checkpoint_example_polymorphic_macro | Serialization of polymorphic class hierarchy with macros | \subpage ckpt_learn_example_polymorphic_macro |
+| checkpoint_example_traversal | Serialization with custom traverser | \subpage ckpt_learn_ex_traversal |
 
+ 
+ 
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+Please do not put serialize methods in global magistrate namespace.
+
+| Non-Intrusive Examples    | Description | Link |
+| ------------------------- | ----------- | ---- |
+| checkpoint_example_1 | Serialization of a structure | \subpage ckpt_learn_ex1_nonintrusive |
+| checkpoint_example_2 | Serialization of a custom structure | \subpage ckpt_learn_ex2_nonintrusive |
+| checkpoint_example_3 | Illustrate needs for constructor/destructor | \subpage ckpt_learn_ex3_nonintrusive |
+| checkpoint_example_to_file | Serialize / deserialize structure to file | \subpage ckpt_learn_ex_tofile_nonintrusive |
+| checkpoint_example_polymorphic | Serialization of polymorphic class hierarchy | \subpage ckpt_learn_example_polymorphic_nonintrusive |
+| checkpoint_example_polymorphic_macro | Serialization of polymorphic class hierarchy with macros | \subpage ckpt_learn_example_polymorphic_macro_nonintrusive |
+| checkpoint_example_traversal | Serialization with custom traverser | \subpage ckpt_learn_ex_traversal_nonintrusive |

docs/shared/checkpoint_learn_example_1_nonintrusive.md

@@ -0,0 +1,9 @@
+\page ckpt_learn_ex1_nonintrusive Non-Intrusive Program Example 1
+
+\attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
+
+The full code for this *checkpoint* example can be found here:
+`examples/checkpoint_example_1_nonintrusive.cc`
+
+\subsubsection ex1 Example source code:
+\snippet examples/checkpoint_example_1_nonintrusive.cc Non-Intrusive serialize custom structure

examples/checkpoint_example_1.cc

@@ -47,7 +47,7 @@
 
 #include <cstdio>
 
-namespace checkpoint { namespace examples {
+namespace magistrate { namespace intrusive { namespace examples {
 
 // \struct MyTest
 // \brief Simple structure with two variables of built-in types
@@ -68,7 +68,7 @@ struct MyTest {
   //
   MyTest(int ai, int bi) : a(ai), b(bi) { };
 
-  /// \brief Printing function unto the standard display
+  // \brief Printing function unto the standard display
   void print() {
     printf("MyTest: a=%d, b=%d\n", a, b);
   }
@@ -105,10 +105,10 @@ struct MyTest {
   }
 };
 
-}} // end namespace checkpoint::examples
+}}} // end namespace magistrate::intrusive::examples
 
 int main(int, char**) {
-  using namespace checkpoint::examples;
+  using namespace magistrate::intrusive::examples;
 
   // Define a variable of custom type `MyTest`
   MyTest my_test_inst(11, 12);

examples/checkpoint_example_nonintrusive.cc → examples/checkpoint_example_1_nonintrusive.cc

@@ -2,7 +2,7 @@
 //@HEADER
 // *****************************************************************************
 //
-//                      checkpoint_example_nonintrusive.cc
+//                    checkpoint_example_1_nonintrusive.cc
 //                 DARMA/checkpoint => Serialization Library
 //
 // Copyright 2019 National Technology & Engineering Solutions of Sandia, LLC
@@ -41,44 +41,85 @@
 //@HEADER
 */
 
+/// [Non-Intrusive serialize custom structure]
+
 #include <checkpoint/checkpoint.h>
 
 #include <cstdio>
 
-namespace checkpoint { namespace examples {
+// \brief Namespace containing type which will be serialized
+namespace magistrate { namespace nonintrusive { namespace examples {
 
+// \brief Simple structure with three variables of built-in types
 struct MyTest3 {
   int a = 1, b = 2 , c = 3;
 
+  // \brief Printing function unto the standard display
   void print() {
     printf("MyTest3: a=%d, b=%d, c=%d\n", a, b, c);
   }
 };
 
-template <typename Serializer>
-void serialize(Serializer& s, MyTest3& my_test3) {
-  s | my_test3.a;
-  s | my_test3.b;
-  s | my_test3.c;
-}
+}}} // end namespace magistrate::nonintrusive::examples
+
+// \brief Function to serialize the MyTest3 structure.
+// In Non-Intrusive way, this function needs to be placed in the namespace
+// of the type which will be serialized.
+namespace magistrate { namespace nonintrusive { namespace examples {
+  // \brief Templated function for serializing/deserializing
+  // a variable of type `MyTest3`. Non-nonintrusive version of the function
+  // placed outside of `MyTest3` structure.
+  //
+  // \tparam <Serializer> The type of serializer depending on the pass
+  // \param[in,out] s the serializer for traversing this class
+  //
+  // \note The serialize method is typically called three times when
+  // (de-)serializing to a byte buffer:
+  //
+  // 1) Sizing: The first time its called, it sizes all the data it recursively
+  // traverses to generate a final size for the buffer.
+  //
+  // 2) Packing: As the traversal occurs, it copies the data traversed to the
+  // byte buffer in the appropriate location.
+  //
+  // 3) Unpacking: As the byte buffer is traversed, it extracts the bytes from
+  // the buffer to recursively reconstruct the types and setup the class members.
+  //
+  template <typename Serializer>
+  void serialize(Serializer& s, MyTest3& my_test3) {
+    // a, b, c - variable of type `int` (built-in type)
+    s | my_test3.a;
+    s | my_test3.b;
+    s | my_test3.c;
+  }
 
-}} // end namespace checkpoint::examples
+}}} // end namespace magistrate::nonintrusive::examples
 
 int main(int, char**) {
-  using namespace checkpoint::examples;
+  using namespace magistrate::nonintrusive::examples;
 
+  // Define a variable of custom type `MyTest3`
   MyTest3 my_test3;
   my_test3.print();
 
+  // Call the serialization routine for the variable `my_test3`
+  // The output is a unique pointer: `std::unique_ptr<SerializedInfo>`
+  // (defined in `src/checkpoint_api.h`)
   auto ret = checkpoint::serialize(my_test3);
 
   auto const& buf = ret->getBuffer();
   auto const& buf_size = ret->getSize();
 
+  // Print the buffer address and its size
   printf("ptr=%p, size=%ld\n", static_cast<void*>(buf), buf_size);
 
+  // Deserialize the variable `my_test3` from the serialized buffer
   auto t = checkpoint::deserialize<MyTest3>(buf);
+
+  // Display the de-serialized data
   t->print();
 
   return 0;
 }
+
+/// [Non-Intrusive serialize custom structure]

examples/checkpoint_example_2.cc

@@ -47,7 +47,7 @@
 
 #include <cstdio>
 
-namespace checkpoint { namespace examples {
+namespace magistrate { namespace intrusive { namespace examples {
 
 // \struct MyTest2
 // \brief Simple structure with one variable of built-in type
@@ -125,10 +125,10 @@ struct MyTest {
   }
 };
 
-}} // end namespace checkpoint::examples
+}}} // end namespace magistrate::intrusive::examples
 
 int main(int, char**) {
-  using namespace checkpoint::examples;
+  using namespace magistrate::intrusive::examples;
 
   // Define a variable of custom type `MyTest`
   MyTest my_test_inst;