HEPnOS client API: DataStore and DataSet
Let's dive into the HEPnOS client-side API. This API is in C++ and provides a number of classes, among which DataStore and DataSet, which are discussed in this section.
The HEPnOS API is located in
hepnos.hpp, which is a small file including other files containing class definitions. In the following, we assume that
#include <hepnos.hpp> is present at the top of your file, and will not explicitly write it.
All the classes and functions of the HEPnOS API are in the
hepnos namespace. To simplify codes, we assume that
using namespace hepnos; is present, and we will not be using the
The DataStore class is the main class to instantiate to point to a running HEPnOS service.
DataStore can be instantiated in two ways:
// using the path to the configuration file generated by the service DataStore datastore("/path/to/config.yml"); // using the HEPNOS_CONFIG_FILE environment variable, which should point to the file DataStore datastore();
Important note: the created DataStore instance must outlive any instances of other HEPnOS classes (DataSet, Run, SubRun, Event, etc.), since instances of these classes hold a pointer to the DataStore object to which they belong.
New DataSets can be created at the root of the datastore using the following method:
DataSet ds = datastore.createDataSet("mydataset");
This function creates a new dataset at the root of the datastore and returns a handle to it. If a dataset with the same name already exists, this function does nothing but returns a handle to the existing dataset.
Important note: the name of the created DataSet should not have
# characters, since those are reserved by HEPnOS.
The DataStore class presents an interface similar to that of an
std::map<std::string, DataSet>. It includes
const_iterator classes that can be dereferenced into
const DataSet& respectively, as well as the following functions.
end(): return an iterator (or a const_iterator if the DataStore is const) pointing to the beginning and the end of the list of datasets contained by the root of the datastore, sorted alphabetically.
cend()return const_iterators to the beginning and the end of the DataStore.
find(name): returns an iterator (or a const_iterator if the DataStore is const) pointing to the DataSet matching the provided name (or
end()if there is no such DataSet).
lower_bound(name): returns an iterator (or a const_iterator if the DataStore is const) pointing to the first DataSet in the DataStore whose name is greater than or equal to the provided name (when compared alphabetically), or
end()if no such DataSet exists.
upper_bound(name): returns an iterator (or a const_iterator if the DataStore is const) pointing to the first DataSet in the DataStore who name is strictly less than the provided name (when compared alphabetically), or
end()if no such DataSet exists.
operator(name): returns a DataSet object whose name matches the provided name. Contrary to the bracket operator from
std::map, this operator does not create the DataSet if it does not exist in the underlying service. Instead, it returns a DataSet instance
Note: the DataStore class also provides a
shutdown() method that is used to shut down all nodes running the HEPnOS service. This function can be useful for a user-deployed HEPnOS service that should be terminated with the application that used it. In a facility-scale deployment of HEPnOS, this method would not be enabled to users.