From 44a3f306412a1ba5130ac14851666f4a90040659 Mon Sep 17 00:00:00 2001 From: Tobias Kremer Date: Tue, 29 Oct 2024 09:45:44 +0100 Subject: [PATCH] [Doc] Documentation for FDB.h Added some documentation for the C++-API of the FDB class. There are still some open questions linked to some of the functions. This is a first draft. --- src/fdb5/api/FDB.h | 219 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 212 insertions(+), 7 deletions(-) diff --git a/src/fdb5/api/FDB.h b/src/fdb5/api/FDB.h index 28529795c..3e02945b1 100644 --- a/src/fdb5/api/FDB.h +++ b/src/fdb5/api/FDB.h @@ -71,72 +71,277 @@ class FDB { // -------------- Primary API functions ---------------------------- + /** @brief Archive binary data to a FDB. + * + * @param handle eckit::message::Message to data to archive + */ void archive(eckit::message::Message msg); + + /** @brief Archive binary data to a FDB. + * + * Reads messages from the eckit#DataHandle and calls archive() the the + * corresponding messages. + * + * @param handle eckit::DataHandle reference data to archive + */ void archive(eckit::DataHandle& handle); + + /** @brief Archive binary data to a FDB . + * + * Internally creates a DataHandle and calls archive(). + * + * @param data Pointer to the binary data to archive + * @param length Size of the data to archive with the given + */ void archive(const void* data, size_t length); - // warning: not high-perf API - makes sure that all the requested fields are archived and there are no data exceeding the request + + /** @brief Archive binary data of a mars request and the corresponding binary data to a FDB. + * + * @warning: not high-perf API - makes sure that all the requested fields are archived and there are no data exceeding the request + * + * @param request, a mars request + * @param handle, a data handle pointing to the data + */ void archive(const metkit::mars::MarsRequest& request, eckit::DataHandle& handle); - // disclaimer: this is a low-level API. The provided key and the corresponding data are not checked for consistency - // Optional callback function is called upon receiving field location from the store. + /** @brief Archive binary data to a FDB. + * + * @warning this is a low-level API. The provided key and the corresponding data are not checked for consistency + * Optional callback function is called upon receiving field location from the store. + * + * @param key Key used for indexing and archiving the data + * @param data Pointer to the binary data to archive + * @param length Size of the data to archive with the given @p key + */ void archive(const Key& key, const void* data, size_t length); - /// Flushes all buffers and closes all data handles into a consistent DB state - /// @note always safe to call + /** @brief Flush all buffers and closes all data handles into a consistent DB state + * + * @note always safe to call + */ void flush(); + /** @brief Read binary data from an URI + * + * @param uri, eckit uri to the data source + * + * @return DataHandle for reading the requested data from + */ eckit::DataHandle* read(const eckit::URI& uri); + /** @brief Read binary data from an list of URI + * + * @param vector of uris, eckit uris to the data source + * @param sorted, bool whether the given uris should be sorted + * + * @return DataHandle for reading the requested data from + */ eckit::DataHandle* read(const std::vector& uris, bool sorted = false); + /** @brief Read binary from a ListIterator + * + * @param a list iterator, which resembles a set of fields, which should be read + * @param sorted, bool whether the given uris should be sorted + * + * @return DataHandle for reading the requested data from + */ eckit::DataHandle* read(ListIterator& it, bool sorted = false); + /** @brief Retrieve data which is specified by a MARS request + * + * @param request MarsRequest which describes the data which should be retrieved + * + * @return DataHandle for reading the requested data from + */ eckit::DataHandle* retrieve(const metkit::mars::MarsRequest& request); + /** + * @TODO: Comment me pls. + * + * @param request, a mars request which should be inspected + * + * @return ListIterator + */ ListIterator inspect(const metkit::mars::MarsRequest& request); + /** @brief List data present at the archive and which can be retrieved + * + * @param request FDBToolRequest stating which data should be queried + * @param deduplicate bool, whether the returned iterator should ignore duplicates + * @param length Size of the data to archive with the given @p key + * + * @return ListIterator for iterating over the set of found items + */ ListIterator list(const FDBToolRequest& request, bool deduplicate=false); + /** @brief Dump the structural content of the FDB + * + * In particular, in the TOC formulation, enumerate the different entries + * in the Table of Contents (including INIT and CLEAR entries). + * The dump will include information identifying the data files that are + * referenced, and the "Axes" which describe the maximum possible extent of + * the data that is contained in the database. + * + * @return DumpIterator for iterating over the set of found items + */ DumpIterator dump(const FDBToolRequest& request, bool simple=false); /// TODO: Is this function superfluous given the control() function? StatusIterator status(const FDBToolRequest& request); + /** @brief Wipe data from the database + * + * @param request FDBToolRequest stating which data should be queried + * @param doit flag for committing to the wipe (default is dry-run) + * @param porcelain flag print only a list of files to be deleted / that are deleted + * @param unsafeWipeAll flag for omitting all security checks and force a wipe + * + * @return WipeIterator for iterating over the set of wiped items + */ WipeIterator wipe(const FDBToolRequest& request, bool doit=false, bool porcelain=false, bool unsafeWipeAll=false); + /** @brief Move content of one FDB database. + * + * This locks the source database, make it possible to create a second + * database in another root, duplicates all data. Source data are not automatically removed. + * + * @param request, a fdb tool request for the data which should be move + * @param uri, destination to which the data should be moved + * + * @return MoveIterator for iterating over the set of found items + */ MoveIterator move(const FDBToolRequest& request, const eckit::URI& dest); + /** @brief Remove duplicate data from the database + * + * Purge duplicate entries from the database and remove the associated data + * (if the data is owned, not adopted). + * Data in the FDB5 is immutable. It is masked, but not damaged or deleted, + * when it is overwritten with new data using the same key. + * If an index or data file only contains masked data + * (i.e. no data that can be obtained using normal requests), + * then those indexes and data files may be removed. + * If an index refers to data that is not owned by the FDB + * (in particular data which has been adopted from an existing FDB4), + * this data will not be removed. + * + * @param request, a fdb tool request for the data which should be purged + * @param doit, bool if true the purge is triggered, otherwise a dry-run is executed + * @param porcelain, bool for printing only those files which are deleted + * + * @return PurgeIterator for iterating over the set of found items + */ PurgeIterator purge(const FDBToolRequest& request, bool doit=false, bool porcelain=false); + /** @brief Prints information about FDB databases, aggregating the information over all the databases visited into a final summary. + * + * @param request, FDB tool request for which the stats should be shown + * + * @return StatsIterator for iterating over the set of found items + */ StatsIterator stats(const FDBToolRequest& request); - + + /** @brief + * TODO: Comment me pls + * @param request, FDB tool request + * @param action, control action + * @param identifiers, identifiers + * + * @return ControlIterator for iterating over the set of found items + */ ControlIterator control(const FDBToolRequest& request, ControlAction action, ControlIdentifiers identifiers); + /** @brief + * TODO: Comment me pls + * + * @param request, FDB tool request + * @param level, maximum level the axis visitor should respect + * + * @return IndexAxis + */ IndexAxis axes(const FDBToolRequest& request, int level=3); + /** @brief + * TODO: Comment me pls + * @param request, FDB tool request + * @param level, maximum level the axis visitor should respect + * + * @return AxisIterator + */ AxesIterator axesIterator(const FDBToolRequest& request, int level=3); + /** @brief Check whether a specific control identifier is enabled + * + * @param controlIdentifier, a given control identifier + * + * @return bool, true or false, depending on the internal status of the FDB + */ bool enabled(const ControlIdentifier& controlIdentifier) const; + /** @brief Return whether a flush of the FDB is needed + * + * @return true, if an archive has happened and a flush is needed + */ bool dirty() const; + /** @brief Register an archive callback + * + * @param callback, an archive callback which should be triggered during archive + */ void registerArchiveCallback(ArchiveCallback callback); + + /** @brief Register a flush callback + * + * @param callback, an flush callback which should be triggered during flushing + */ void registerFlushCallback(FlushCallback callback); // -------------- API management ---------------------------- - /// ID used for hashing in the Rendezvous hash. Should be unique. + /** @brief ID used for hashing in the Rendezvous hash. Should be unique. + * + * @returns a string resembling the rendezvous hashing id + */ const std::string id() const; + /** @brief Return the stats + * + * TODO: What is the different to the internal stats + * @return FDBStats + */ FDBStats stats() const; + + /** @brief Return the internal stats + * + * TODO: What is the different to the stats + * @return FDBStats + */ FDBStats internalStats() const; + /** @brief Return the name of the FDB + * + * @return the string& containing the name of the FDB + */ const std::string& name() const; + + /** @brief Return the config of the FDB + * + * @return the Config& of the FDB + */ const Config& config() const; + /** @brief + * + * TODO: comment me pls + */ void disable(); + + /** @brief Check whether the FDB is disabled + * + * @return bool, true if the FDB is disabled, false otherwise + */ bool disabled() const; private: // methods