Commit 47a6fd15 authored by Dominik Charousset's avatar Dominik Charousset

Improve documentation of `message_builder`

parent 086d5127
...@@ -17,8 +17,8 @@ ...@@ -17,8 +17,8 @@
* http://www.boost.org/LICENSE_1_0.txt. * * http://www.boost.org/LICENSE_1_0.txt. *
******************************************************************************/ ******************************************************************************/
#ifndef CAF_OBJECT_ARRAY_HPP #ifndef CAF_MESSAGE_BUILDER_HPP
#define CAF_OBJECT_ARRAY_HPP #define CAF_MESSAGE_BUILDER_HPP
#include <vector> #include <vector>
...@@ -26,19 +26,18 @@ ...@@ -26,19 +26,18 @@
#include "caf/message_handler.hpp" #include "caf/message_handler.hpp"
#include "caf/uniform_type_info.hpp" #include "caf/uniform_type_info.hpp"
#include "caf/detail/message_data.hpp"
namespace caf { namespace caf {
/** /**
* Provides a convenient interface to create a {@link message} * Provides a convenient interface for createing `message` objects
* from a series of values using the member function `append`. * from a series of values using the member function `append`.
*/ */
class message_builder { class message_builder {
public: public:
message_builder();
message_builder(const message_builder&) = delete; message_builder(const message_builder&) = delete;
message_builder& operator=(const message_builder&) = delete; message_builder& operator=(const message_builder&) = delete;
message_builder();
~message_builder(); ~message_builder();
/** /**
...@@ -51,7 +50,7 @@ class message_builder { ...@@ -51,7 +50,7 @@ class message_builder {
} }
/** /**
* Adds `what` to the elements of the internal buffer. * Adds `what` to the elements of the buffer.
*/ */
message_builder& append(uniform_value what); message_builder& append(uniform_value what);
...@@ -72,7 +71,7 @@ class message_builder { ...@@ -72,7 +71,7 @@ class message_builder {
} }
/** /**
* Adds `what` to the elements of the internal buffer. * Adds `what` to the elements of the buffer.
*/ */
template <class T> template <class T>
message_builder& append(T what) { message_builder& append(T what) {
...@@ -80,43 +79,50 @@ class message_builder { ...@@ -80,43 +79,50 @@ class message_builder {
} }
/** /**
* Converts the internal buffer to an actual message object. * Converts the buffer to an actual message object without
* * invalidating this message builder (nor clearing it).
* It is worth mentioning that a call to `to_message` does neither */
* invalidate the `message_builder` instance nor clears the internal message to_message() const;
* buffer. However, calling any non-const member function afterwards
* can cause the `message_builder` to detach its data, i.e., /**
* copy it if there is more than one reference to it. * Converts the buffer to an actual message object and transfers
* ownership of the data to it, leaving this object in an invalid state.
* @warning Calling *any* member function on this object afterwards
* is undefined behavior (dereferencing a `nullptr`)
*/ */
message to_message(); message move_to_message();
inline message filter(message_handler f) { /**
* @copydoc message::filter
*/
inline message filter(message_handler f) const {
return to_message().filter(f); return to_message().filter(f);
} }
inline message::cli_res filter_cli(std::vector<message::cli_arg> args) { /**
* @copydoc message::filter_cli
*/
inline message::cli_res filter_cli(std::vector<message::cli_arg> args) const {
return to_message().filter_cli(std::move(args)); return to_message().filter_cli(std::move(args));
} }
/** /**
* Convenience function for `to_message().apply(handler). * @copydoc message::apply
*/ */
inline optional<message> apply(message_handler handler) { optional<message> apply(message_handler handler);
return to_message().apply(std::move(handler));
}
/** /**
* Removes all elements from the internal buffer. * Removes all elements from the buffer.
*/ */
void clear(); void clear();
/** /**
* Returns whether the internal buffer is empty. * Returns whether the buffer is empty.
*/ */
bool empty() const; bool empty() const;
/** /**
* Returns the number of elements in the internal buffer. * Returns the number of elements in the buffer.
*/ */
size_t size() const; size_t size() const;
...@@ -146,4 +152,4 @@ class message_builder { ...@@ -146,4 +152,4 @@ class message_builder {
} // namespace caf } // namespace caf
#endif // CAF_OBJECT_ARRAY_HPP #endif // CAF_MESSAGE_BUILDER_HPP
...@@ -23,12 +23,12 @@ ...@@ -23,12 +23,12 @@
#include "caf/message_handler.hpp" #include "caf/message_handler.hpp"
#include "caf/uniform_type_info.hpp" #include "caf/uniform_type_info.hpp"
#include "caf/detail/message_data.hpp"
namespace caf { namespace caf {
class message_builder::dynamic_msg_data : public detail::message_data { class message_builder::dynamic_msg_data : public detail::message_data {
public: public:
using super = message_data;
dynamic_msg_data() : m_type_token(0xFFFFFFFF) { dynamic_msg_data() : m_type_token(0xFFFFFFFF) {
// nop // nop
} }
...@@ -144,8 +144,27 @@ message_builder& message_builder::append(uniform_value what) { ...@@ -144,8 +144,27 @@ message_builder& message_builder::append(uniform_value what) {
return *this; return *this;
} }
message message_builder::to_message() { message message_builder::to_message() const {
return message{data()}; // this const_cast is safe, because the message is
// guaranteed to detach its data before modifying it
return message{const_cast<dynamic_msg_data*>(data())};
}
message message_builder::move_to_message() {
message result;
result.vals().reset(static_cast<dynamic_msg_data*>(m_data.release()), false);
return result;
}
optional<message> message_builder::apply(message_handler handler) {
// avoid detaching of m_data by moving the data to a message object,
// calling message::apply and moving the data back
message::data_ptr ptr;
ptr.reset(static_cast<dynamic_msg_data*>(m_data.release()), false);
message msg{std::move(ptr)};
auto res = msg.apply(std::move(handler));
m_data.reset(msg.vals().release(), false);
return res;
} }
message_builder::dynamic_msg_data* message_builder::data() { message_builder::dynamic_msg_data* message_builder::data() {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment