diff --git a/ecaludp/include/ecaludp/owning_buffer.h b/ecaludp/include/ecaludp/owning_buffer.h index b97c50d..fe06346 100644 --- a/ecaludp/include/ecaludp/owning_buffer.h +++ b/ecaludp/include/ecaludp/owning_buffer.h @@ -20,36 +20,64 @@ namespace ecaludp { + /** + * @brief A buffer-view class that manages the ownership of the internal memory through a generic std::shared_ptr + * + * The OwningBuffer class is a buffer that can manage the ownership of its own + * memory. The memory is managed through a std::shared_ptr. + * + * - The buffer is represented by pointer + size. + * + * - The user creating this object must make sure that the the pointer and size is valid. + * + * - It is assumed that the pointer points to data that is owned by the shared_ptr. + * + * - The user must make sure that the pointer is valid as long as the OwningBuffer + * is used. This probably requires to stop writing to the internal buffer as + * soon as the OwningBuffer is created. It especially requires to make sure + * the internal data will never be re-allocated. + */ class OwningBuffer { public: - // Default constructor - OwningBuffer() - : data_ (nullptr) - , size_ (0) - , owning_container_(nullptr) - {} - - // Constructor + /** + * @brief Construct a new OwningBuffer object + * + * The OwningBuffer object is constructed with a pointer to the internal + * data and the size of the internal data. The owning_container is a shared + * pointer that must own the internal data. + * + * @param data A pointer to the internal data + * @param size The size of the internal data + * @param owning_container A shared pointer that owns the internal data + */ OwningBuffer(const void* data, size_t size, const std::shared_ptr& owning_container) : data_ (data) , size_ (size) , owning_container_(owning_container) {} + /** + * @brief Returns the pointer to the internal data + * @return the pointer to the internal data + */ const void* data() const { return data_; } + /** + * @brief Returns the size of the internal data + * @return the size of the internal data + */ size_t size() const { return size_; } private: - const void* data_; - const size_t size_; - const std::shared_ptr owning_container_; + const void* data_; ///< The pointer to the internal data + const size_t size_; ///< The size of the internal data + const std::shared_ptr owning_container_; ///< A shared pointer that owns the internal data }; }