From 342eda02a0ce9bf31045d89dc19cafdfe8835269 Mon Sep 17 00:00:00 2001 From: badaix Date: Thu, 4 Jul 2024 22:55:35 +0200 Subject: [PATCH] Add some documentation --- .github/workflows/ci.yml | 2 +- common/message/message.hpp | 52 +++++++++++++++++++++++++++++++++++--- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f9b07763..be786f08 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,7 +75,7 @@ jobs: mkdir -p build/doxygen doxygen 2>&1 | tee build/doxygen.log WARNINGS=$(cat build/doxygen.log | sort | uniq | grep -e ": warning: " | wc -l) - MAX_ALLOWED=840 + MAX_ALLOWED=775 echo "Doxygen finished with $WARNINGS warnings, max allowed: $MAX_ALLOWED" if [ "$WARNINGS" -gt "$MAX_ALLOWED" ]; then exit $WARNINGS; else exit 0; fi; diff --git a/common/message/message.hpp b/common/message/message.hpp index 4bb52e43..3b534a30 100644 --- a/common/message/message.hpp +++ b/common/message/message.hpp @@ -44,15 +44,18 @@ public: }; */ +// https://stackoverflow.com/questions/7781898/get-an-istream-from-a-char +/// Helper to convert char* to a stream buffer struct membuf : public std::basic_streambuf { + /// c'tor membuf(char* begin, char* end) { this->setg(begin, begin, end); } }; - +/// Message type enums enum class message_type : uint16_t { kBase = 0, @@ -68,6 +71,7 @@ enum class message_type : uint16_t kLast = kClientInfo }; +/// Message type to string static std::ostream& operator<<(std::ostream& os, const message_type& msg_type) { switch (msg_type) @@ -99,8 +103,10 @@ static std::ostream& operator<<(std::ostream& os, const message_type& msg_type) return os; } +/// Timeval like struct struct tv { + /// c'tor tv() { timeval t; @@ -108,12 +114,18 @@ struct tv sec = t.tv_sec; usec = t.tv_usec; } + + /// C'tor, construct from timeval @p tv tv(timeval tv) : sec(tv.tv_sec), usec(tv.tv_usec){}; + /// C'tor, construct from @p _sec and @p _usec tv(int32_t _sec, int32_t _usec) : sec(_sec), usec(_usec){}; + /// seconds int32_t sec; + /// micro seconds int32_t usec; + /// add another tv tv operator+(const tv& other) const { tv result(*this); @@ -127,6 +139,7 @@ struct tv return result; } + /// subtract another tv tv operator-(const tv& other) const { tv result(*this); @@ -144,24 +157,30 @@ struct tv namespace msg { +/// Max message size = 1mb const size_t max_size = 1000000; struct BaseMessage; using message_ptr = std::shared_ptr; +/// Base message with common message header for all messages struct BaseMessage { + /// c'tor BaseMessage() : BaseMessage(message_type::kBase) { } + /// c'tor with message type @p type_ BaseMessage(message_type type_) : type(type_), id(0), refersTo(0), size(0) { } + /// d'tor virtual ~BaseMessage() = default; + /// Deserialize message from @p stream virtual void read(std::istream& stream) { readVal(stream, type); @@ -174,6 +193,7 @@ struct BaseMessage readVal(stream, size); } + /// Deserialize message from @p payload buffer void deserialize(char* payload) { membuf databuf(payload, payload + BaseMessage::getSize()); @@ -181,6 +201,7 @@ struct BaseMessage read(is); } + /// Deserialize message from message header @p baseMessage and message @p payload void deserialize(const BaseMessage& baseMessage, char* payload) { type = baseMessage.type; @@ -194,6 +215,7 @@ struct BaseMessage read(is); } + /// Serialize message to @p stream virtual void serialize(std::ostream& stream) const { writeVal(stream, type); @@ -208,66 +230,82 @@ struct BaseMessage doserialize(stream); } + /// @return binary size of the base message virtual uint32_t getSize() const { return 3 * sizeof(uint16_t) + 2 * sizeof(tv) + sizeof(uint32_t); }; + /// the message type message_type type; + /// the message id, used to correlate request and response mutable uint16_t id; + /// a response message might refer to the message id of the request uint16_t refersTo; + /// timestamp when the message has been received tv received; + /// timestamp when the message was sent mutable tv sent; + /// the payload size mutable uint32_t size; protected: + /// serialize a bool @p val to @p stream void writeVal(std::ostream& stream, const bool& val) const { char c = val ? 1 : 0; writeVal(stream, c); } + /// serialize a const char* @p val to @p stream void writeVal(std::ostream& stream, const char& val) const { stream.write(reinterpret_cast(&val), sizeof(char)); } + /// serialize an uint16 @p val to @p stream void writeVal(std::ostream& stream, const uint16_t& val) const { uint16_t v = SWAP_16(val); stream.write(reinterpret_cast(&v), sizeof(uint16_t)); } + /// serialize the message type @p val to @p stream void writeVal(std::ostream& stream, const message_type& val) const { uint16_t v = SWAP_16(static_cast(val)); stream.write(reinterpret_cast(&v), sizeof(uint16_t)); } + /// serialize an int16 @p val to @p stream void writeVal(std::ostream& stream, const int16_t& val) const { uint16_t v = SWAP_16(val); stream.write(reinterpret_cast(&v), sizeof(int16_t)); } + /// serialize an uint32 @p val to @p stream void writeVal(std::ostream& stream, const uint32_t& val) const { uint32_t v = SWAP_32(val); stream.write(reinterpret_cast(&v), sizeof(uint32_t)); } + /// serialize an int32 @p val to @p stream void writeVal(std::ostream& stream, const int32_t& val) const { uint32_t v = SWAP_32(val); stream.write(reinterpret_cast(&v), sizeof(int32_t)); } + /// serialize a char* string @p payload of @p size to @p stream void writeVal(std::ostream& stream, const char* payload, const uint32_t& size) const { writeVal(stream, size); stream.write(payload, size); } + /// serialize an std::string @p val to @p stream void writeVal(std::ostream& stream, const std::string& val) const { auto len = static_cast(val.size()); @@ -275,7 +313,7 @@ protected: } - + /// Deserialize a bool @p val from @p stream void readVal(std::istream& stream, bool& val) const { char c; @@ -283,11 +321,13 @@ protected: val = (c != 0); } + /// Deserialize a char @p val from @p stream void readVal(std::istream& stream, char& val) const { stream.read(reinterpret_cast(&val), sizeof(char)); } + /// Deserialize an uint16 @p val from @p stream void readVal(std::istream& stream, uint16_t& val) const { stream.read(reinterpret_cast(&val), sizeof(uint16_t)); @@ -295,12 +335,14 @@ protected: val = SWAP_16(val); } + /// Deserialize a message_type @p val from @p stream void readVal(std::istream& stream, message_type& val) const { stream.read(reinterpret_cast(&val), sizeof(uint16_t)); val = static_cast(SWAP_16(static_cast(val))); } + /// Deserialize an int16 @p val from @p stream void readVal(std::istream& stream, int16_t& val) const { stream.read(reinterpret_cast(&val), sizeof(int16_t)); @@ -308,6 +350,7 @@ protected: val = SWAP_16(val); } + /// Deserialize an uint32 @p val from @p stream void readVal(std::istream& stream, uint32_t& val) const { stream.read(reinterpret_cast(&val), sizeof(uint32_t)); @@ -315,6 +358,7 @@ protected: val = SWAP_32(val); } + /// Deserialize an int32 @p val from @p stream void readVal(std::istream& stream, int32_t& val) const { stream.read(reinterpret_cast(&val), sizeof(int32_t)); @@ -322,6 +366,7 @@ protected: val = SWAP_32(val); } + /// Deserialize a char* string @p payload of @p size from @p stream void readVal(std::istream& stream, char** payload, uint32_t& size) const { readVal(stream, size); @@ -329,6 +374,7 @@ protected: stream.read(*payload, size); } + /// Deserialize a std::string @p val from @p stream void readVal(std::istream& stream, std::string& val) const { uint32_t len; @@ -337,7 +383,7 @@ protected: stream.read(&val[0], len); } - + /// Deserialize message to std::ostream virtual void doserialize(std::ostream& /*stream*/) const {}; };