Skip to content
Snippets Groups Projects
Commit a4f17994 authored by Ewan Barr's avatar Ewan Barr
Browse files

added docstrings throughout

parent 698f0c90
Branches
Tags
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 374 additions and 0 deletions
psrdada_cpp/cli_utils.hpp
+ 19
− 0
View file @ a4f17994
......@@ -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
......
psrdada_cpp/dada_client_base.hpp
+ 22
− 0
View file @ a4f17994
......@@ -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:
......
psrdada_cpp/dada_dbnull.hpp
+ 36
− 0
View file @ a4f17994
......@@ -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);
};
......
psrdada_cpp/dada_io_loop.hpp
+ 15
− 0
View file @ a4f17994
......@@ -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;
};
......
psrdada_cpp/dada_io_loop_reader.hpp
+ 10
− 0
View file @ a4f17994
......@@ -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
......
psrdada_cpp/dada_io_loop_writer.hpp
+ 10
− 0
View file @ a4f17994
......@@ -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
......
psrdada_cpp/dada_junkdb.hpp
+ 35
− 0
View file @ a4f17994
......@@ -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);
};
......
psrdada_cpp/dada_read_client.hpp
+ 76
− 0
View file @ a4f17994
......@@ -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:
......
psrdada_cpp/dada_write_client.hpp
+ 73
− 0
View file @ a4f17994
......@@ -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:
......
psrdada_cpp/examples/dbnull.cpp
+ 9
− 0
View file @ a4f17994
......@@ -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)
{
......
psrdada_cpp/examples/junkdb.cpp
+ 9
− 0
View file @ a4f17994
......@@ -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)
{
......
psrdada_cpp/multilog.hpp
+ 22
− 0
View file @ a4f17994
......@@ -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);
......
psrdada_cpp/raw_bytes.hpp
+ 38
− 0
View file @ a4f17994
......@@ -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();
};
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment