Improve examples

examples/apps/CMakeLists.txt

@@ -16,7 +16,7 @@ set(CALIPER_CXX_EXAMPLE_APPS
   cali-functional
   cali-regionprofile)
 set(CALIPER_C_EXAMPLE_APPS
-  cali-basic-annotations-c
+  c-example
   cali-print-snapshot)
 set(CALIPER_Fortran_EXAMPLE_APPS
   fortran-example

examples/apps/c-example.c

@@ -0,0 +1,113 @@
+// Copyright (c) 2015-2020, Lawrence Livermore National Security, LLC.
+// See top-level LICENSE file for details.
+
+// A C Caliper instrumentation and ConfigManager example
+
+//   Usage: $ cali-basic-annotations <configuration-string>
+// For example, "$ cali-basic-annotations runtime-report" will print a
+// hierarchical runtime summary for all annotated regions.
+
+#include <caliper/cali.h>
+#include <caliper/cali-manager.h>
+
+#include <stdio.h>
+#include <string.h>
+
+void print_help()
+{
+    const char* helpstr = 
+        "Usage: c-example [caliper-config(arg=...,),...]."
+        "\nRuns \"runtime-report\" configuration by default."
+        "\nUse \"none\" to run without a ConfigManager configuration."
+        "\nAvailable configurations: ";
+
+    puts(helpstr);
+}
+
+double foo(int i)
+{
+    //   A function annotation. Opens region "function=foo" in Caliper,
+    // and automatically closes it at the end of the function.
+    CALI_MARK_FUNCTION_BEGIN;
+    double res = 0.5 * i;
+    CALI_MARK_FUNCTION_END;
+    return res;
+}
+
+int main(int argc, char* argv[])
+{
+    //   The ConfigManager manages built-in or custom Caliper measurement
+    // configurations, and provides an API to control performance profiling.
+    cali_ConfigManager mgr;
+    cali_ConfigManager_new(&mgr);
+
+    //   We can set default parameters for the Caliper configurations.
+    // These can be overridden in the user-provided configuration string.
+    cali_ConfigManager_set_default_parameter(&mgr, "aggregate_across_ranks", "false");
+
+    //   Use the "runtime-report" configuration by default to print a
+    // runtime summary for all annotated regions. Let users overwrite
+    // the default configuration with their own on the command line.
+    const char* configstr = "runtime-report";
+
+    if (argc > 1) {
+        if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) {
+            print_help();
+            return 0;
+        } else {
+            configstr = argv[1];
+        }
+    }
+
+    if (strcmp(configstr, "none") == 0)
+        configstr = "";
+
+    //   Enable the requested performance measurement channels and start
+    // profiling.
+    cali_ConfigManager_add(&mgr, configstr);
+
+    if (cali_ConfigManager_error(&mgr)) {
+        cali_SHROUD_array errmsg;
+        cali_ConfigManager_error_msg_bufferify(&mgr, &errmsg);
+        fprintf(stderr, "Caliper config error: %s\n", errmsg.addr.ccharp);
+        cali_SHROUD_memory_destructor(&errmsg.cxx);
+    }
+
+    cali_ConfigManager_start(&mgr);
+
+    //   Mark begin of the current function. Must be manually closed.
+    // Opens region "function=main" in Caliper.
+    CALI_MARK_FUNCTION_BEGIN;
+
+    // Mark a code region. Opens region "annotation=init" in Caliper.
+    CALI_MARK_BEGIN("init");
+    int count = 4;
+    double  t = 0;
+    CALI_MARK_END("init");
+
+    // Mark a loop. Opens region "loop=mainloop" in Caliper.
+    CALI_MARK_LOOP_BEGIN(loop_ann, "mainloop");
+
+    for (int i = 0; i < count; ++i) {
+        //   Mark loop iterations of an annotated loop.
+        // Sets "iteration#main loop=<i> in Caliper.
+        CALI_MARK_ITERATION_BEGIN(loop_ann, i);
+
+        //   A Caliper snapshot taken at this point will contain
+        // { "function"="main", "loop"="mainloop", "iteration#main loop"=<i> }
+
+        t += foo(i);
+
+        CALI_MARK_ITERATION_END(loop_ann);
+    }
+
+    // Mark the end of the "loop=mainloop" region.
+    CALI_MARK_LOOP_END(loop_ann);
+    // Mark the end of the "function=main" region.
+    CALI_MARK_FUNCTION_END;
+
+    //   Trigger output in all Caliper control channels.
+    // This should be done after all measurement regions have been closed.
+    cali_ConfigManager_flush(&mgr);
+    cali_ConfigManager_delete(&mgr);
+}

examples/apps/cxx-example.cpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2015-2019, Lawrence Livermore National Security, LLC.
+// Copyright (c) 2015-2020, Lawrence Livermore National Security, LLC.
 // See top-level LICENSE file for details.
 
 // A C++ Caliper instrumentation and ConfigManager example
@@ -14,16 +14,18 @@
 #include <iostream>
 #include <string>
 
-void print_help()
+void print_help(const cali::ConfigManager& mgr)
 {
     std::cerr << "Usage: cxx-example [caliper-config(arg=...,),...]."
               << "\nRuns \"runtime-report\" configuration by default."
               << "\nUse \"none\" to run without a ConfigManager configuration."
               << "\nAvailable configurations: ";
 
+    auto configs = mgr.available_config_specs();
+
     // Print info on all available ConfigManager configurations.
-    for (auto str : cali::ConfigManager::get_config_docstrings())
-        std::cerr << '\n' << str;
+    for (auto str : configs)
+        std::cerr << "\n" << mgr.get_documentation_for_spec(str.c_str());
 
     std::cerr << std::endl;
 }
@@ -39,24 +41,22 @@ double foo(int i)
 
 int main(int argc, char* argv[])
 {
-    //   A Caliper ConfigManager object manages built-in Caliper measurement
-    // configurations. It parses a configuration string and creates a set of
-    // control channels for the requested measurement configurations.
+    //   The ConfigManager manages built-in or custom Caliper measurement
+    // configurations, and provides an API to control performance profiling.
     cali::ConfigManager mgr;
 
     //   We can set default parameters for the Caliper configurations.
     // These can be overridden in the user-provided configuration string.
     mgr.set_default_parameter("aggregate_across_ranks", "false");
 
-    //   The "runtime-report" configuration will print a hierarchical
-    // runtime summary for all annotated regions.
+    //   Use the "runtime-report" configuration by default to print a
+    // runtime summary for all annotated regions. Let users overwrite
+    // the default configuration with their own on the command line.
     std::string configstr = "runtime-report";
 
-    //   Let users overwrite the default configuration with their own
-    // on the command line.
     if (argc > 1) {
         if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) {
-            print_help();
+            print_help(mgr);
             return 0;
         } else {
             configstr = argv[1];
@@ -66,17 +66,13 @@ int main(int argc, char* argv[])
     if (configstr == "none")
         configstr.clear();
 
-    //   Configure Caliper performance measurement channels based on
-    // the configuration string.
+    //   Enable the requested performance measurement channels and start
+    // profiling.
     mgr.add(configstr.c_str());
 
-    //   Check if the configuration string was parsed successfully.
-    // If not, print an error message.
     if (mgr.error())
         std::cerr << "Caliper config error: " << mgr.error_msg() << std::endl;
 
-    //   Start all requested Caliper measurement control channels.
-    // Should be done prior to the first region annotations.
     mgr.start();
 
     //   Mark begin of the current function. Must be manually closed.
@@ -89,22 +85,22 @@ int main(int argc, char* argv[])
     double  t = 0;
     CALI_MARK_END("init");
 
-    // Mark a loop. Opens region "loop=main loop" in Caliper.
-    CALI_CXX_MARK_LOOP_BEGIN(mainloop, "main loop");
+    // Mark a loop. Opens region "loop=mainloop" in Caliper.
+    CALI_CXX_MARK_LOOP_BEGIN(loop_ann, "mainloop");
 
     for (int i = 0; i < count; ++i) {
         //   Mark loop iterations of an annotated loop.
         // Sets "iteration#main loop=<i> in Caliper.
-        CALI_CXX_MARK_LOOP_ITERATION(mainloop, i);
+        CALI_CXX_MARK_LOOP_ITERATION(loop_ann, i);
 
         //   A Caliper snapshot taken at this point will contain
-        // { "function"="main", "loop"="main loop", "iteration#main loop"=<i> }
+        // { "function"="main", "loop"="mainloop", "iteration#main loop"=<i> }
 
         t += foo(i);
     }
 
-    // Mark the end of the "loop=main loop" region.
-    CALI_CXX_MARK_LOOP_END(mainloop);
+    // Mark the end of the "loop=mainloop" region.
+    CALI_CXX_MARK_LOOP_END(loop_ann);
     // Mark the end of the "function=main" region.
     CALI_MARK_FUNCTION_END;