Config improvements (#61)

* Factor out read_char/read_word functions into util lib

* Use more robust config string parser

* Add runtime config C interface

* Add CI test case for C config API and report

* Update example report config entry, fix doc typo

* Add warning when trying to use config API after init

* Add --caliper-config argument for cali-query

examples/configs/branch_mispred.conf

@@ -2,6 +2,6 @@ CALI_LIBPFM_ENABLE_SAMPLING=false
 CALI_LIBPFM_RECORD_COUNTERS=true
 CALI_LIBPFM_EVENTS=branch-misses,branches
 
-CALI_REPORT_CONFIG=SELECT *,percentage(libpfm.counter.branch-misses,libpfm.counter.branches) GROUP BY function format table
+CALI_REPORT_CONFIG="SELECT *,percentage(libpfm.counter.branch-misses,libpfm.counter.branches) GROUP BY function format table"
 
 CALI_SERVICES_ENABLE=libpfm:pthread:event:trace:timestamp:report

include/caliper/cali.h

@@ -411,25 +411,84 @@ cali_err
 cali_end_byname(const char* attr_name);
 
 /**
- * \} // name
- * \} // addtogroup 
+ * \}
+ * \}
  */
 
 /*
- * --- Runtime system configuration and management
+ * --- Runtime system configuration
+ */
+
+/**
+ * \name Runtime configuration
+ * \{
+ */
+
+/**
+ * \copydoc cali::RuntimeConfig::preset
  */
+
+void
+cali_config_preset(const char* key, const char* value);
+
+/**
+ * \copydoc cali::RuntimeConfig::set
+ */
+
+void
+cali_config_set(const char* key, const char* value);
 
 /**
- * \brief Add a value to Caliper's runtime configuration system.
+ * \copybrief cali::RuntimeConfig::define_profile
  *
- * \note  This is only effective _before_ the Caliper runtime system is initialized.
+ * A configuration profile is a named set of specific
+ * configuration settings. The entire set can be enabled by its name
+ * with a single configuration entry.
  *
- * \param key   Configuration key (e.g., CALI_SERVICES_ENABLE)
- * \param value Configuration value 
+ * This function only defines a configuration profile, but does not
+ * enable it. %Caliper uses the profiles named in the
+ * \c CALI_CONFIG_PROFILE configuration entry; to enable a profile
+ * set this configuration entry accordingly.
+ *
+ * Example:
+ *
+ * \code
+ *   const char* my_profile[][2] =
+ *     { { "CALI_SERVICES_ENABLE", "aggregate,event,timestamp,trace" },
+ *       { "CALI_EVENT_TRIGGER",   "annotation" },
+ *       { NULL, NULL }
+ *     };
+ *
+ *   // Define the "my_profile" config profile
+ *   cali_config_define_profile("my_profile", my_profile);
+ *   cali_config_set("CALI_CONFIG_PROFILE", "my_profile");
+ * \endcode
+ *
+ * \param name Name of the configuration profile.
+ * \param keyvallist A list of key-value pairs as array of two strings
+ *    that contains the profile's configuration entries. The first string
+ *    in each entry is the configuration key, the second string is its
+ *    value. Keys must be all uppercase. Terminate the list with two
+ *    NULL entries: <tt> { NULL, NULL } </tt>.
  */
 
 void
-cali_config_preset(const char* key, const char* value);
+cali_config_define_profile(const char* name, const char* keyvallist[][2]);
+
+/**
+ * \copydoc cali::RuntimeConfig::allow_read_env(bool)
+ */
+
+void
+cali_config_allow_read_env(int allow);
+
+/**
+ * \}
+ */
+
+/*
+ * --- Runtime system management
+ */
 
 /**
  * \brief Initialize Caliper.

include/caliper/common/RuntimeConfig.h

@@ -85,15 +85,19 @@ class RuntimeConfig
     /// \brief Pre-set config entry \a key to \a value.
     ///
     /// The value may be overwritten by configuration files or environment
-    /// variables. Only effective *before*
-    /// initialization of the %Caliper runtime system.
+    /// variables.
+    ///
+    /// \note: Only effective *before* initialization of the %Caliper
+    ///   runtime system.
     static void            preset(const char* key, const std::string& value);
 
     /// \brief Set config entry \a key to \a value.
     ///
     /// The value will *not* be overwritten by configuration files,
-    /// profile settings, or environment variables. Only effective *before*
-    /// initialization of the %Caliper runtime system.
+    /// profile settings, or environment variables.
+    ///
+    /// \note: Only effective *before* initialization of the %Caliper
+    ///   runtime system.
     static void            set(const char* key, const std::string& value);
 
     /// \brief Initialize a ConfigSet.
@@ -126,7 +130,7 @@ class RuntimeConfig
     ///
     /// \param name Name of the configuration profile.
     /// \param keyvallist A list of key-value pairs as array of two strings
-    //     that contains the profile's configuration entries. The first string
+    ///    that contains the profile's configuration entries. The first string
     ///    in each entry is the configuration key, the second string is its
     ///    value. Keys must be all uppercase. Terminate the list with two
     ///    NULL entries: <tt> { NULL, NULL } </tt>.
@@ -143,11 +147,15 @@ class RuntimeConfig
     /// ability to debug %Caliper (e.g., increasing the log level).
     /// Consider providing other means to modify configuration settings
     /// at runtime in this case, e.g. command-line arguments.
+    ///
+    /// \note Only effective *before* initialization of the %Caliper
+    ///   runtime system.
     static bool            allow_read_env(bool allow);
 
     /// \brief Print the current configuration settings.
     ///
-    /// Only effective after initialization of the %Caliper runtime system.
+    /// \note Only effective after initialization of the %Caliper
+    ///   runtime system.
     static void print(std::ostream& os);
 
 }; // class RuntimeConfig

src/caliper/cali.cpp

@@ -554,9 +554,37 @@ cali_end_byname(const char* attr_name)
 void
 cali_config_preset(const char* key, const char* value)
 {
+    if (Caliper::is_initialized())
+        Log(0).stream() << "Warning: Caliper is already initialized. "
+                        << "cali_config_preset(\"" << key << "\", \"" << value
+                        << "\") has no effect." << std::endl;
+
     RuntimeConfig::preset(key, value);
 }
 
+void
+cali_config_set(const char* key, const char* value)
+{
+    if (Caliper::is_initialized())
+        Log(0).stream() << "Warning: Caliper is already initialized. "
+                        << "cali_config_set(\"" << key << "\", \"" << value
+                        << "\") has no effect." << std::endl;
+
+    RuntimeConfig::set(key, value);
+}
+
+void
+cali_config_define_profile(const char* name, const char* keyvallist[][2])
+{
+    RuntimeConfig::define_profile(name, keyvallist);
+}
+
+void
+cali_config_allow_read_env(int allow)
+{
+    RuntimeConfig::allow_read_env(allow != 0);
+}
+
 void
 cali_init()
 {

src/common/CMakeLists.txt

@@ -19,10 +19,12 @@ set(CALIPER_COMMON_SOURCES
 
 add_subdirectory(csv)
 add_subdirectory(c-util)
+add_subdirectory(util)
 
 add_library(caliper-common
   $<TARGET_OBJECTS:caliper-csv>
   $<TARGET_OBJECTS:c-util>
+  $<TARGET_OBJECTS:util>
   ${CALIPER_COMMON_SOURCES})
 
 set_target_properties(caliper-common PROPERTIES SOVERSION ${CALIPER_MAJOR_VERSION})