From 2127dacf46591c2d824fcc01903472ad3fb610ec Mon Sep 17 00:00:00 2001 From: Matthieu Dorier Date: Fri, 13 Apr 2018 02:46:18 +0200 Subject: [PATCH] Commenting DataStore.hpp --- include/hepnos/DataStore.hpp | 531 +++++++++++++++++++++++++++++------ 1 file changed, 442 insertions(+), 89 deletions(-) diff --git a/include/hepnos/DataStore.hpp b/include/hepnos/DataStore.hpp index e37fead..6ec5402 100644 --- a/include/hepnos/DataStore.hpp +++ b/include/hepnos/DataStore.hpp @@ -9,62 +9,259 @@ namespace hepnos { class DataSet; +/** + * The DataStore class is the main handle referencing an HEPnOS service. + * It provides functionalities to navigate DataSets. + */ class DataStore { friend class DataSet; public: - DataStore(const std::string& configFile); - - DataStore(const DataStore&) = delete; - DataStore(DataStore&&); - DataStore& operator=(const DataStore&) = delete; - DataStore& operator=(DataStore&&); + /** + * @brief Constructor. Initializes the DataStore using a YAML + * configuration file (this file is generated by the HEPnOS + * service when started. + * + * @param configFile Path to a YAML configuration file. + */ + DataStore(const std::string& configFile); + + /** + * @brief Copy constructor is deleted. + */ + DataStore(const DataStore&) = delete; + + /** + * @brief Move constructor. + * + * @param other DataStore to move from. + */ + DataStore(DataStore&& other); + + /** + * @brief Copy-assignment operator. Deleted. + */ + DataStore& operator=(const DataStore&) = delete; + + /** + * @brief Move-assignment operator. + * + * @param other DataStore to move from. + * + * @return This DataStore. + */ + DataStore& operator=(DataStore&& other); - ~DataStore(); - - DataSet operator[](const std::string& datasetName) const; - - class iterator; - class const_iterator; - - iterator find(const std::string& datasetName); - - const_iterator find(const std::string& datasetName) const; - - iterator begin(); - - iterator end(); - - const_iterator cbegin() const; - - const_iterator cend() const; - - iterator lower_bound(const std::string& lb); - - const_iterator lower_bound(const std::string& lb) const; - - iterator upper_bound(const std::string& ub); - - const_iterator upper_bound(const std::string& ub) const; - - DataSet createDataSet(const std::string& name); + /** + * @brief Destructor. + */ + ~DataStore(); + + /** + * @brief Accesses an existint DataSet using the [] + * operator. If no DataSet correspond to the provided name, + * the function returns a DataSet instance d such that + * d.valid() is false. + * + * @param datasetName Name of the DataSet to retrieve. + * + * @return a DataSet corresponding to the provided name. + */ + DataSet operator[](const std::string& datasetName) const; + + /** + * @brief iterator class to navigate DataSets. + * This iterator is a forward iterator. DataSets are sorted + * alphabetically inside the DataStore. + */ + class iterator; + + /** + * @brief const_iterator class to navigate DataSets. + * This iterator is a forward iterator. DataSets are sorted + * alphabetically inside the DataStore. + */ + class const_iterator; + + /** + * @brief Searches the DataStore for an DataSet with + * the provided name and returns an iterator to it if found, + * otherwise it returns an iterator to DataStore::end(). + * + * @param datasetName Name of the DataSet to find. + * + * @return an iterator pointing to the DataSet if found, + * DataStore::end() otherwise. + */ + iterator find(const std::string& datasetName); + + /** + * @brief Searches the DataStore for an DataSet with + * the provided name and returns a const_iterator to it + * if found, otherwise it returns an iterator to DataStore::end(). + * + * @param datasetName Name of the DataSet to find. + * + * @return a const_iterator pointing to the DataSet if found, + * DataStore::cend() otherwise. + */ + const_iterator find(const std::string& datasetName) const; + + /** + * @brief Returns an iterator referring to the first DataSet + * in the DataStore. + * + * @return an iterator referring to the first DataSet in the DataStore. + */ + iterator begin(); + + /** + * @brief Returns an iterator referring to the end of the DataStore. + * The DataSet pointed to by this iterator is not valid (that is, + * `end()->valid()` return `false`). + * + * @return an iterator referring to the end of the DataStore. + */ + iterator end(); + + /** + * @brief Returns a const_iterator referring to the first DataSet + * in the DataStore. + * + * @return a const_iterator referring to the first DataSet in the DataStore. + */ + const_iterator cbegin() const; + + /** + * @brief Returns a const_iterator referring to the end of the DataStore. + * The DataSet pointed to by this iterator is not valid (that is, + * `cend()->valid()` return `false`). + * + * @return a const_iterator referring to the end of the DataStore. + */ + const_iterator cend() const; + + /** + * @brief Returns an iterator pointing to the first DataSet in the + * DataStore whose name is not considered to go before lb + * (i.e., either it is equal or goes after, alphabetically). + * + * @param lb DataSet name to search for. + * + * @return An iterator to the the first DataSet in the DataStore + * whose name is not considered to go before lb, or DataStore::end() + * if all keys are considered to go before it. + */ + iterator lower_bound(const std::string& lb); + + /** + * @brief Returns a const_iterator pointing to the first DataSet in the + * DataStore whose name is not considered to go before lb + * (i.e., either it is equal or goes after, alphabetically). + * + * @param lb DataSet name to search for. + * + * @return A const_iterator to the the first DataSet in the DataStore + * whose name is not considered to go before lb, or DataStore::cend() + * if all DataSet names are considered to go before it. + */ + const_iterator lower_bound(const std::string& lb) const; + + /** + * @brief Returns an iterator pointing to the first DataSet in the + * DataStore whose key is considered to go after ub. + * + * @param ub DataSet name to search for. + * + * @return An iterator to the the first DataSet in the DataStore + * whose name is considered to go after ub, or DataStore::end() if + * no DataSet names are considered to go after it. + */ + iterator upper_bound(const std::string& ub); + + /** + * @brief Returns a const_iterator pointing to the first DataSet in the + * DataStore whose key is considered to go after ub. + * + * @param ub DataSet name to search for. + * + * @return A const_iterator to the the first DataSet in the DataStore + * whose name is considered to go after ub, or DataStore::end() if + * no DataSet names are considered to go after it. + */ + const_iterator upper_bound(const std::string& ub) const; + + /** + * @brief Creates a dataset with a given name inside the + * DataStore. This name must not have the '/' and '#' characters. + * A DataSet object pointing to the created dataset is returned. + * If a dataset with this name already exists in the DataStore, + * it is not created, but a DataSet object pointing to the + * existing one is returned instead. + * + * @param name Name of DataSet. + * + * @return A DataSet instance pointing to the created dataset. + */ + DataSet createDataSet(const std::string& name); private: - class Impl; - std::unique_ptr m_impl; - - bool load(uint8_t level, const std::string& containerName, - const std::string& objectName, std::vector& data) const; - - bool store(uint8_t level, const std::string& containerName, - const std::string& objectName, const std::vector& data); - - size_t nextKeys(uint8_t level, const std::string& containerName, - const std::string& lower, - std::vector& keys, size_t maxKeys) const; + /** + * @brief Implementation of the class (using Pimpl idiom) + */ + class Impl; + std::unique_ptr m_impl; /*!< Pointer to implementation */ + + /** + * @brief Function used by the DataSet, Run, SubRuns, and Event + * classes to load binary data associated with a particular object. + * + * @param level Level of nesting (0 for data products) + * @param containerName Name of the container + * @param objectName Name of the object + * @param data Resulting byte buffer containing the object's data + * + * @return true if the object was found an loaded correctly, + * false otherwise. + */ + bool load(uint8_t level, const std::string& containerName, + const std::string& objectName, std::vector& data) const; + + /** + * @brief Function used by the DataSet, Run, SubRuns, and Event + * classes to load binary data associated with a particular object. + * + * @param level Level of nesting (0 for data products) + * @param containerName Name of the container + * @param objectName Name of the object + * @param data Byte buffer to write + * + * @return true is the object did not exist and was correctly written, + * false otherwise. + */ + bool store(uint8_t level, const std::string& containerName, + const std::string& objectName, const std::vector& data); + + /** + * @brief Given a lowerBound for dataset names, retrieve at most + * maxDataSets dataset names coming striclty after lowerBound + * from the DataStore, for a given level and container name. + * Returns the number of dataset names actually retrieved + * + * @param level Level of nesting + * @param containerName Name of the container in which to search + * @param lowerBound Lower bound name to search for + * @param keys Resulting vector of dataset names + * @param maxDataSets Maximum number of datasets to retrieve. + * + * @return The actual number of dataset names retrieved. + */ + size_t nextKeys(uint8_t level, const std::string& containerName, + const std::string& lowerBound, + std::vector& keys, size_t maxDataSets) const; }; class DataStore::const_iterator { @@ -74,62 +271,218 @@ class DataStore::const_iterator { protected: - class Impl; - std::unique_ptr m_impl; - - const_iterator(DataStore& ds); - const_iterator(DataStore& ds, const DataSet& current); + /** + * @brief Implementation of the class (using Pimpl idiom) + */ + class Impl; + std::unique_ptr m_impl; /*!< Pointer to implementation */ + + /** + * @brief Constructor. Creates a const_iterator pointing + * to an invalid DataSet. + * + * @param ds DataStore creating this const_iterator. + */ + const_iterator(DataStore& ds); + + /** + * @brief Constructor. Creates a const_iterator pointing + * to a given DataSet. The DataSet may or may not be valid. + * + * @param ds DataStore creating this const_iterator. + * @param current DataSet to make the const_iterator point to. + */ + const_iterator(DataStore& ds, const DataSet& current); public: - typedef const_iterator self_type; - typedef DataSet value_type; - typedef DataSet& reference; - typedef DataSet* pointer; - typedef int difference_type; - typedef std::forward_iterator_tag iterator_category; - - virtual ~const_iterator(); - const_iterator(const const_iterator&); - const_iterator(const_iterator&&); - const_iterator& operator=(const const_iterator&); - const_iterator& operator=(const_iterator&&); - - self_type operator++(); - self_type operator++(int); - const reference operator*(); - const pointer operator->(); - bool operator==(const self_type& rhs) const; - bool operator!=(const self_type& rhs) const; + typedef const_iterator self_type; + typedef DataSet value_type; + typedef DataSet& reference; + typedef DataSet* pointer; + typedef int difference_type; + typedef std::forward_iterator_tag iterator_category; + + /** + * @brief Destructor. This destructor is virtual because + * the iterator class inherits from const_iterator. + */ + virtual ~const_iterator(); + + /** + * @brief Copy-constructor. + * + * @param other const_iterator to copy. + */ + const_iterator(const const_iterator& other); + + /** + * @brief Move-constructor. + * + * @param other const_iterator to move. + */ + const_iterator(const_iterator&& other); + + /** + * @brief Copy-assignment operator. + * + * @param other const_iterator to copy. + * + * @return this. + */ + const_iterator& operator=(const const_iterator&); + + /** + * @brief Move-assignment operator. + * + * @param other const_iterator to move. + * + * @return this. + */ + const_iterator& operator=(const_iterator&&); + + /** + * @brief Increments the const_iterator, returning + * a copy of the iterator after incrementation. + * + * @return a copy of the iterator after incrementation. + */ + self_type operator++(); + + /** + * @brief Increments the const_iterator, returning + * a copy of the iterator before incrementation. + * + * @return a copy of the iterator after incrementation. + */ + self_type operator++(int); + + /** + * @brief Dereference operator. Returns a const reference + * to the DataSet this const_iterator points to. + * + * @return a const reference to the DataSet this + * const_iterator points to. + */ + const reference operator*(); + + /** + * @brief Returns a const pointer to the DataSet this + * const_iterator points to. + * + * @return a const pointer to the DataSet this + * const_iterator points to. + */ + const pointer operator->(); + + /** + * @brief Compares two const_iterators. The two const_iterators + * are equal if they point to the same DataSet or if both + * correspond to DataStore::cend(). + * + * @param rhs const_iterator to compare with. + * + * @return true if the two const_iterators are equal, false otherwise. + */ + bool operator==(const self_type& rhs) const; + + /** + * @brief Compares two const_iterators. + * + * @param rhs const_iterator to compare with. + * + * @return true if the two const_iterators are different, false atherwise. + */ + bool operator!=(const self_type& rhs) const; }; class DataStore::iterator : public DataStore::const_iterator { - friend class DataStore::Impl; - friend class DataStore; + friend class DataStore::Impl; + friend class DataStore; private: - iterator(DataStore& ds); - iterator(DataStore& ds, const DataSet& current); + /** + * @brief Constructor. Builds an iterator pointing to an + * invalid DataSet. + * + * @param ds DataStore creating the iterator. + */ + iterator(DataStore& ds); + + /** + * @brief Constructor. Builds an iterator pointing to + * an existing DataSet. The DataSet may or may not be + * valid. + * + * @param ds DataStore creating the iterator. + * @param current DataSet to point to. + */ + iterator(DataStore& ds, const DataSet& current); public: - typedef iterator self_type; - typedef DataSet value_type; - typedef DataSet& reference; - typedef DataSet* pointer; - typedef int difference_type; - typedef std::forward_iterator_tag iterator_category; - - ~iterator(); - iterator(const iterator&); - iterator(iterator&&); - iterator& operator=(const iterator&); - iterator& operator=(iterator&&); - - reference operator*(); - pointer operator->(); + typedef iterator self_type; + typedef DataSet value_type; + typedef DataSet& reference; + typedef DataSet* pointer; + typedef int difference_type; + typedef std::forward_iterator_tag iterator_category; + + /** + * @brief Destructor. + */ + ~iterator(); + + /** + * @brief Copy constructor. + * + * @param other iterator to copy. + */ + iterator(const iterator& other); + + /** + * @brief Move constructor. + * + * @param other iterator to move. + */ + iterator(iterator&& other); + + /** + * @brief Copy-assignment operator. + * + * @param other iterator to copy. + * + * @return this. + */ + iterator& operator=(const iterator& other); + + /** + * @brief Move-assignment operator. + * + * @param other iterator to move. + * + * @return this. + */ + iterator& operator=(iterator&& other); + + /** + * @brief Dereference operator. Returns a reference + * to the DataSet this iterator points to. + * + * @return A reference to the DataSet this iterator + * points to. + */ + reference operator*(); + + /** + * @brief Returns a pointer to the DataSet this iterator + * points to. + * + * @return A pointer to the DataSet this iterator points to. + */ + pointer operator->(); }; } -- 2.26.2