From a4f1799470dac9e893acd3822eadb3162ff928f9 Mon Sep 17 00:00:00 2001 From: Ewan Barr <ewan.d.barr@googlemail.com> Date: Sun, 30 Jul 2017 20:02:26 +0200 Subject: [PATCH] added docstrings throughout --- psrdada_cpp/cli_utils.hpp | 19 ++++++++ psrdada_cpp/dada_client_base.hpp | 22 +++++++++ psrdada_cpp/dada_dbnull.hpp | 36 ++++++++++++++ psrdada_cpp/dada_io_loop.hpp | 15 ++++++ psrdada_cpp/dada_io_loop_reader.hpp | 10 ++++ psrdada_cpp/dada_io_loop_writer.hpp | 10 ++++ psrdada_cpp/dada_junkdb.hpp | 35 +++++++++++++ psrdada_cpp/dada_read_client.hpp | 76 +++++++++++++++++++++++++++++ psrdada_cpp/dada_write_client.hpp | 73 +++++++++++++++++++++++++++ psrdada_cpp/examples/dbnull.cpp | 9 ++++ psrdada_cpp/examples/junkdb.cpp | 9 ++++ psrdada_cpp/multilog.hpp | 22 +++++++++ psrdada_cpp/raw_bytes.hpp | 38 +++++++++++++++ 13 files changed, 374 insertions(+) diff --git a/psrdada_cpp/cli_utils.hpp b/psrdada_cpp/cli_utils.hpp index 5ac02413..5ac4c8ff 100644 --- a/psrdada_cpp/cli_utils.hpp +++ b/psrdada_cpp/cli_utils.hpp @@ -5,7 +5,26 @@ namespace psrdada_cpp { + /** + * @brief Convert a string into a shared memory key + * + * @param in A hexadecimal string (e.g. "dada") + * + * @note No error checking is performed on the conversion, meaning + * that non-hex valiues will still give an output (e.g. an input + * of "dag" will drop the non-hex "g" character giving an output + * of 0xda) + * + * @return A key_t representation of the hexadecimal string + */ key_t string_to_key(std::string const& in); + + /** + * @brief Sets the log level for boost logging. + * + * @param[in] level The desired log level as a string + * [debug, info, warning, error]. + */ void set_log_level(std::string level); } //namespace diff --git a/psrdada_cpp/dada_client_base.hpp b/psrdada_cpp/dada_client_base.hpp index e990ef74..1edf3f7d 100644 --- a/psrdada_cpp/dada_client_base.hpp +++ b/psrdada_cpp/dada_client_base.hpp @@ -17,12 +17,34 @@ namespace psrdada_cpp { MultiLog& _log; public: + /** + * @brief Create a new basic DADA client instance + * + * @param[in] key The hexidecimal shared memory key + * @param log A MultiLog instance for logging buffer transactions + */ DadaClientBase(key_t key, MultiLog& log); DadaClientBase(DadaClientBase const&) = delete; ~DadaClientBase(); + + /** + * @brief Get the sizes of each data block in the ring buffer + */ std::size_t data_buffer_size(); + + /** + * @brief Get the sizes of each header block in the ring buffer + */ std::size_t header_buffer_size(); + + /** + * @brief Get the number of data blocks in the ring buffer + */ std::size_t data_buffer_count(); + + /** + * @brief Get the number of header blocks in the ring buffer + */ std::size_t header_buffer_count(); private: diff --git a/psrdada_cpp/dada_dbnull.hpp b/psrdada_cpp/dada_dbnull.hpp index 80adf5e3..8529b60b 100644 --- a/psrdada_cpp/dada_dbnull.hpp +++ b/psrdada_cpp/dada_dbnull.hpp @@ -8,6 +8,14 @@ namespace psrdada_cpp { + /** + * @brief Class for reading from a DADA buffer + * and doing nothing with the data. + * + * @detail This class is intended as both an example + * for how to use CRTP with DadaIoLoopReader + * and as a tool for testing. + */ class DbNull : public DadaIoLoopReader<DbNull> { @@ -16,9 +24,37 @@ namespace psrdada_cpp bool _infinite; public: + /** + * @brief Create a new instance + * + * @param[in] key The shared memory key + * @param log A MultiLog instance + * @param[in] nbytes The number of bytes to read from the buffer. + * Setting this value to 0 will cause the instance + * to read forever. + */ DbNull(key_t key, MultiLog& log, std::size_t nbytes); ~DbNull(); + + /** + * @brief A callback to be called on connection + * to a ring buffer. + * + * @detail The first available header block in the + * in the ring buffer is provided as an argument. + * It is here that header parameters could be read + * if desired. + * + * @param block A RawBytes object wrapping a DADA header buffer + */ void on_connect(RawBytes& block); + + /** + * @brief A callback to be called on acqusition of a new + * data block. + * + * @param block A RawBytes object wrapping a DADA data buffer + */ void on_next(RawBytes& block); }; diff --git a/psrdada_cpp/dada_io_loop.hpp b/psrdada_cpp/dada_io_loop.hpp index ac08269b..307fcb82 100644 --- a/psrdada_cpp/dada_io_loop.hpp +++ b/psrdada_cpp/dada_io_loop.hpp @@ -16,10 +16,25 @@ namespace psrdada_cpp bool _running; public: + + /** + * @brief Create new instance + * + * @param[in] key A hexadecimal shared memory key + * @param log A MultiLog instance + */ DadaIoLoop(key_t key, MultiLog& log); DadaIoLoop(DadaIoLoop const&) = delete; ~DadaIoLoop(); + + /** + * @brief Stop the IO loop processing + */ void stop(); + + /** + * @brief Start the IO loop processing + */ virtual void run()=0; }; diff --git a/psrdada_cpp/dada_io_loop_reader.hpp b/psrdada_cpp/dada_io_loop_reader.hpp index ccfb6330..7f443dfb 100644 --- a/psrdada_cpp/dada_io_loop_reader.hpp +++ b/psrdada_cpp/dada_io_loop_reader.hpp @@ -11,8 +11,18 @@ namespace psrdada_cpp class DadaIoLoopReader: public DadaIoLoop { public: + /** + * @brief Create a IO loop for reading from a DADA buffer + * + * @param[in] key The hexidecimal shared memory key + * @param log A MultiLog instance for logging buffer transactions + */ DadaIoLoopReader(key_t key, MultiLog& log); ~DadaIoLoopReader(); + + /** + * @brief Start the IO loop processing + */ void run(); }; } //namespace psrdada_cpp diff --git a/psrdada_cpp/dada_io_loop_writer.hpp b/psrdada_cpp/dada_io_loop_writer.hpp index 905813c0..8673637b 100644 --- a/psrdada_cpp/dada_io_loop_writer.hpp +++ b/psrdada_cpp/dada_io_loop_writer.hpp @@ -11,8 +11,18 @@ namespace psrdada_cpp class DadaIoLoopWriter: public DadaIoLoop { public: + /** + * @brief Create a IO loop for writing to a DADA buffer + * + * @param[in] key The hexidecimal shared memory key + * @param log A MultiLog instance for logging buffer transactions + */ DadaIoLoopWriter(key_t key, MultiLog& log); ~DadaIoLoopWriter(); + + /** + * @brief Start the IO loop processing + */ void run(); }; } //namespace psrdada_cpp diff --git a/psrdada_cpp/dada_junkdb.hpp b/psrdada_cpp/dada_junkdb.hpp index 62ab8ba6..b665ce57 100644 --- a/psrdada_cpp/dada_junkdb.hpp +++ b/psrdada_cpp/dada_junkdb.hpp @@ -8,6 +8,13 @@ namespace psrdada_cpp { + /** + * @brief Class for writing junk to a dada buffer + * + * @detail This class is intended as both an example + * for how to use CRTP with DadaIoLoopWriter + * and as a tool for testing. + */ class JunkDb : public DadaIoLoopWriter<JunkDb> { @@ -16,9 +23,37 @@ namespace psrdada_cpp bool _infinite; public: + /** + * @brief Create a new instance + * + * @param[in] key The shared memory key + * @param log A MultiLog instance + * @param[in] nbytes The number of bytes to write to the buffer. + * Setting this value to 0 will cause the instance + * to write forever. + */ JunkDb(key_t key, MultiLog& log, std::size_t nbytes); ~JunkDb(); + + /** + * @brief A callback to be called on connection + * to a ring buffer. + * + * @detail The first available header block in the + * in the ring buffer is provided as an argument. + * It is here that header parameters could be written + * to if desired. + * + * @param block A RawBytes object wrapping a DADA header buffer + */ void on_connect(RawBytes& block); + + /** + * @brief A callback to be called on acqusition of a new + * data block. + * + * @param block A RawBytes object wrapping a DADA data buffer + */ bool on_next(RawBytes& block); }; diff --git a/psrdada_cpp/dada_read_client.hpp b/psrdada_cpp/dada_read_client.hpp index d17b329c..7bae5305 100644 --- a/psrdada_cpp/dada_read_client.hpp +++ b/psrdada_cpp/dada_read_client.hpp @@ -7,6 +7,10 @@ namespace psrdada_cpp { + /** + * @brief Class that provides means for reading from + * a DADA ring buffer + */ class DadaReadClient: public DadaClientBase { public: @@ -17,11 +21,36 @@ namespace psrdada_cpp { std::unique_ptr<RawBytes> _current_block; public: + /** + * @brief Create a new instance + * + * @param parent A reference to the parent reading client + */ HeaderStream(DadaReadClient& parent); HeaderStream(HeaderStream const&) = delete; ~HeaderStream(); + + /** + * @brief Get the next header block in the ring buffer + * + * @detail As only one block can be open at a time, release() must + * be called between subsequenct next() calls. + * + * @return A RawBytes instance wrapping a pointer to share memory + */ RawBytes& next(); + + /** + * @brief Release the current data block. + * + * @detail This will mark the block as cleared, making it + * writeable by writing client. + */ void release(); + + /** + * @brief Check if we have read the last header block in buffer. + */ bool at_end() const; }; @@ -33,12 +62,41 @@ namespace psrdada_cpp { std::size_t _block_idx; public: + /** + * @brief Create a new instance + * + * @param parent A reference to the parent reading client + */ DataStream(DadaReadClient& parent); DataStream(DataStream const&) = delete; ~DataStream(); + + /** + * @brief Get the next data block in the ring buffer + * + * @detail As only one block can be open at a time, release() must + * be called between subsequenct next() calls. + * + * @return A RawBytes instance wrapping a pointer to share memory + */ RawBytes& next(); + + /** + * @brief Release the current data block. + * + * @detail This will mark the block as cleared, making it + * writeable by writing client. + */ void release(); + + /** + * @brief Check if we have read the last data block in buffer. + */ bool at_end() const; + + /** + * @brief Return the index of the currently open block + */ std::size_t block_idx() const; }; @@ -48,10 +106,28 @@ namespace psrdada_cpp { DataStream _data_stream; public: + /** + * @brief Create a new client for reading from a DADA buffer + * + * @param[in] key The hexidecimal shared memory key + * @param log A MultiLog instance for logging buffer transactions + */ DadaReadClient(key_t key, MultiLog& log); DadaReadClient(DadaReadClient const&) = delete; ~DadaReadClient(); + + /** + * @brief Get a reference to a header stream manager + * + * @return A HeaderStream manager object for the current buffer + */ HeaderStream& header_stream(); + + /** + * @brief Get a reference to a data stream manager + * + * @return A DataStream manager object for the current buffer + */ DataStream& data_stream(); private: diff --git a/psrdada_cpp/dada_write_client.hpp b/psrdada_cpp/dada_write_client.hpp index ddfb61a0..a9ecdf39 100644 --- a/psrdada_cpp/dada_write_client.hpp +++ b/psrdada_cpp/dada_write_client.hpp @@ -7,9 +7,18 @@ namespace psrdada_cpp { + /** + * @brief Class that provides means for writing to + * a DADA ring buffer + */ class DadaWriteClient: public DadaClientBase { public: + + /** + * @brief A helper class for encapsulating + * the DADA buffer header blocks. + */ class HeaderStream { private: @@ -17,10 +26,31 @@ namespace psrdada_cpp { std::unique_ptr<RawBytes> _current_block; public: + /** + * @brief Create a new instance + * + * @param parent A reference to the parent writing client + */ HeaderStream(DadaWriteClient& parent); HeaderStream(HeaderStream const&) = delete; ~HeaderStream(); + + /** + * @brief Get the next header block in the ring buffer + * + * @detail As only one block can be open at a time, release() must + * be called between subsequenct next() calls. + * + * @return A RawBytes instance wrapping a pointer to share memory + */ RawBytes& next(); + + /** + * @brief Release the current header block. + * + * @detail This will mark the block as filled, making it + * readable by reading client. + */ void release(); }; @@ -32,19 +62,62 @@ namespace psrdada_cpp { std::size_t _block_idx; public: + /** + * @brief Create a new instance + * + * @param parent A reference to the parent writing client + */ DataStream(DadaWriteClient& parent); DataStream(DataStream const&) = delete; ~DataStream(); + + /** + * @brief Get the next data block in the ring buffer + * + * @detail As only one block can be open at a time, release() must + * be called between subsequenct next() calls. + * + * @return A RawBytes instance wrapping a pointer to share memory + */ RawBytes& next(); + + /** + * @brief Release the current data block. + * + * @detail This will mark the block as filled, making it + * readable by reading client. + */ void release(bool eod=false); + + /** + * @brief Return the index of the currently open block + */ std::size_t block_idx() const; }; public: + /** + * @brief Create a new client for writing to a DADA buffer + * + * @param[in] key The hexidecimal shared memory key + * @param log A MultiLog instance for logging buffer transactions + */ DadaWriteClient(key_t key, MultiLog& log); DadaWriteClient(DadaWriteClient const&) = delete; ~DadaWriteClient(); + + /** + * @brief Get a reference to a header stream manager + * + * @return A HeaderStream manager object for the current buffer + */ HeaderStream& header_stream(); + + /** + * @brief Get a reference to a data stream manager + * + * @return A DataStream manager object for the current buffer + */ DataStream& data_stream(); private: diff --git a/psrdada_cpp/examples/dbnull.cpp b/psrdada_cpp/examples/dbnull.cpp index 40bffb81..b438cbb3 100644 --- a/psrdada_cpp/examples/dbnull.cpp +++ b/psrdada_cpp/examples/dbnull.cpp @@ -70,9 +70,18 @@ int main(int argc, char** argv) std::cerr << desc << std::endl; return ERROR_IN_COMMAND_LINE; } + + /** + * All the application code goes here + */ + MultiLog log("dbnull"); DbNull proc(key, log, nbytes); proc.run(); + + /** + * End of application code + */ } catch(std::exception& e) { diff --git a/psrdada_cpp/examples/junkdb.cpp b/psrdada_cpp/examples/junkdb.cpp index 1d165690..f9f22743 100644 --- a/psrdada_cpp/examples/junkdb.cpp +++ b/psrdada_cpp/examples/junkdb.cpp @@ -69,9 +69,18 @@ int main(int argc, char** argv) std::cerr << desc << std::endl; return ERROR_IN_COMMAND_LINE; } + + /** + * All the application code goes here + */ + MultiLog log("junkdb"); JunkDb proc(key, log, nbytes); proc.run(); + + /** + * End of application code + */ } catch(std::exception& e) { diff --git a/psrdada_cpp/multilog.hpp b/psrdada_cpp/multilog.hpp index 707a78af..7fbece1f 100644 --- a/psrdada_cpp/multilog.hpp +++ b/psrdada_cpp/multilog.hpp @@ -6,6 +6,11 @@ namespace psrdada_cpp { + /** + * @brief A class for wrapping multilog_t instances + * required for logging with the underlying + * DADA API. + */ class MultiLog { private: @@ -14,12 +19,29 @@ namespace psrdada_cpp { bool _open; public: + /** + * @brief Create a new instance + * + * @param[in] name The name to give this logger + */ explicit MultiLog(std::string name); MultiLog(MultiLog const&) = delete; ~MultiLog(); + /** + * @brief Get a native handle to the wrapped multilog_t pointer + */ multilog_t* native_handle(); + /** + * @brief Write to the log + * + * @param[in] priority The priority (0, 1, 2...) + * @param[in] format The format string + * @param[in] ... Parameters for the format string + * + * @tparam Args The types of the parameters for the format string + */ template<class... Args> void write(int priority, const char* format, Args&&... args); diff --git a/psrdada_cpp/raw_bytes.hpp b/psrdada_cpp/raw_bytes.hpp index 3fed09bf..76bd32eb 100644 --- a/psrdada_cpp/raw_bytes.hpp +++ b/psrdada_cpp/raw_bytes.hpp @@ -5,6 +5,17 @@ namespace psrdada_cpp { + /** + * @brief Class for wrapping a raw pointer to a buffer of shared memory + * + * @detail This class is used to wrap pointers to shared memory + * returned by calls to the lower-level DADA API. + * + * This class is used to wrap buffers acquired by both reading + * and writing clients. For writing clients, it is necessary to + * set the number of bytes written using the used_bytes() method + * after writing. This value is used when releasing the buffer. + */ class RawBytes { private: @@ -13,12 +24,39 @@ namespace psrdada_cpp { std::size_t _used_bytes; public: + /** + * @brief Create a new RawBytes instance + * + * @param ptr The pointer to the buffer to wrap + * @param[in] total The total number of bytes in the buffer + * @param[in] used The number of bytes currently used in the buffer + */ RawBytes(char* ptr, std::size_t total, std::size_t used=0); RawBytes(RawBytes const&) = delete; ~RawBytes(); + + /** + * @brief Get the total number of bytes in the buffer + */ std::size_t total_bytes(); + + /** + * @brief Get the number of currently used bytes in the buffer + */ std::size_t used_bytes(); + + /** + * @brief Set the number of currently used bytes in the buffer + * + * @detail For writing clients, this method should be called after + * all writes are complete so that the number of used_bytes + * can be passed to reading clients. + */ void used_bytes(std::size_t); + + /** + * @brief Get a raw pointer to the start of the buffer + */ char* ptr(); }; -- GitLab