PROTON-1543: Another slate of doc improvements - Transition the message properties and annotations API from unsettled to settled - Cleanups for messaging_handler and the multithreading page - Fix doc warnings and add missing docs - Handle new macros in doxygen preprocessing - Hide the currently problematic work docs
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/55564c80 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/55564c80 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/55564c80 Branch: refs/heads/go1 Commit: 55564c80b2ea41b3fc4e7be4394a9b280b0cca89 Parents: 6b2e7dc Author: Justin Ross <jr...@apache.org> Authored: Fri Oct 13 16:02:28 2017 -0700 Committer: Justin Ross <jr...@apache.org> Committed: Fri Oct 13 16:02:28 2017 -0700 ---------------------------------------------------------------------- proton-c/bindings/cpp/docs/mt.md | 41 +++++---- proton-c/bindings/cpp/docs/user.doxygen.in | 2 +- .../bindings/cpp/include/proton/connection.hpp | 22 ++--- .../cpp/include/proton/default_container.hpp | 2 +- .../bindings/cpp/include/proton/function.hpp | 2 +- .../bindings/cpp/include/proton/listener.hpp | 5 ++ .../bindings/cpp/include/proton/message.hpp | 25 +++--- .../cpp/include/proton/messaging_handler.hpp | 94 +++++++++++--------- .../bindings/cpp/include/proton/thread_safe.hpp | 3 + proton-c/bindings/cpp/include/proton/url.hpp | 2 +- .../bindings/cpp/include/proton/work_queue.hpp | 42 +++++---- proton-c/include/proton/message.h | 10 +-- 12 files changed, 132 insertions(+), 118 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/docs/mt.md ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/docs/mt.md b/proton-c/bindings/cpp/docs/mt.md index 293290c..3be1bc2 100644 --- a/proton-c/bindings/cpp/docs/mt.md +++ b/proton-c/bindings/cpp/docs/mt.md @@ -4,38 +4,37 @@ Full multithreading support is available with C++11 and later. Limited multithreading is possible with older versions of C++. See the last section of this page for more information. -The `proton::container` handles multiple connections concurrently in a thread -pool, created using `proton::container::run()`. As AMQP events occur on a -connection the container calls `proton::messaging_handler` event callbacks. The -calls for each connection are *serialized* - callbacks for the same connection -are never made concurrently. - - -You assign a handler to a connection in `proton::container::connect()` or -`proton::listen_handler::on_accept()` with -`proton::connection_options::handler()`. We recommend you create a separate -handler for each connection. That means the handler doesn't need locks or other -synchronization to protect it against concurrent use by proton threads. -(If you use the handler concurrently from non-proton threads then you will need -synchronization.) +`proton::container` handles multiple connections concurrently in a +thread pool, created using `proton::container::run()`. As AMQP events +occur on a connection the container calls `proton::messaging_handler` +event callbacks. The calls for each connection are *serialized* - +callbacks for the same connection are never made concurrently. + +You assign a handler to a connection in `proton::container::connect()` +or `proton::listen_handler::on_accept()` with +`proton::connection_options::handler()`. We recommend you create a +separate handler for each connection. That means the handler doesn't +need locks or other synchronization to protect it against concurrent +use by Proton threads. If you use the handler concurrently from +non-Proton threads then you will need synchronization. The examples @ref multithreaded_client.cpp and @ref multithreaded_client_flow_control.cpp illustrate these points. - ## Thread-safety rules -The `proton::container` is thread-safe *with C++11 or greater*. An application -thread can open (or listen for) new connections at any time. The container uses -threads that call proton::container::run() to handle network IO, and call -user-defined `proton::messaging_handler` callbacks. +`proton::container` is thread-safe *with C++11 or greater*. An +application thread can open (or listen for) new connections at any +time. The container uses threads that call `proton::container::run()` +to handle network IO and call user-defined `proton::messaging_handler` +callbacks. -The `proton::container` ensures that calls to event callbacks for each +`proton::container` ensures that calls to event callbacks for each connection instance are *serialized* (not called concurrently), but callbacks for different connections can be safely executed in parallel. -The `proton::connection` and related objects (`proton::session`, +`proton::connection` and related objects (`proton::session`, `proton::sender`, `proton::receiver`, `proton::delivery`) are *not* thread-safe and are subject to the following rules. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/docs/user.doxygen.in ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/docs/user.doxygen.in b/proton-c/bindings/cpp/docs/user.doxygen.in index f829086..855be07 100644 --- a/proton-c/bindings/cpp/docs/user.doxygen.in +++ b/proton-c/bindings/cpp/docs/user.doxygen.in @@ -44,7 +44,7 @@ SORT_MEMBER_DOCS = NO ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES -PREDEFINED = protected=private PN_CPP_EXTERN= PN_CPP_OVERRIDE= PN_CPP_HAS_CPP11=1 PN_CPP_HAS_SHARED_PTR=1 PN_CPP_HAS_UNIQUE_PTR=1 PN_CPP_HAS_LONG_LONG=1 PN_CPP_HAS_NULLPTR=1 PN_CPP_HAS_RVALUE_REFERENCES=1 PN_CPP_HAS_OVERRIDE=override PN_CPP_HAS_EXPLICIT_CONVERSIONS=1 PN_CPP_HAS_DEFAULTED_FUNCTIONS=1 PN_CPP_HAS_DELETED_FUNCTIONS=1 PN_CPP_HAS_STD_FUNCTION=1 PN_CPP_HAS_CHRONO=1 PN_CPP_SUPPORTS_THREADS=1 +PREDEFINED = protected=private PN_CPP_DEPRECATED(x)= PN_CPP_EXTERN= PN_CPP_OVERRIDE= PN_CPP_HAS_CPP11=1 PN_CPP_HAS_SHARED_PTR=1 PN_CPP_HAS_UNIQUE_PTR=1 PN_CPP_HAS_LONG_LONG=1 PN_CPP_HAS_NULLPTR=1 PN_CPP_HAS_RVALUE_REFERENCES=1 PN_CPP_HAS_OVERRIDE=override PN_CPP_HAS_EXPLICIT_CONVERSIONS=1 PN_CPP_HAS_DEFAULTED_FUNCTIONS=1 PN_CPP_HAS_DELETED_FUNCTIONS=1 PN_CPP_HAS_STD_FUNCTION=1 PN_CPP_HAS_CHRONO=1 PN_CPP_SUPPORTS_THREADS=1 EXCLUDE_SYMBOLS = internal internal::* # Configuration options related to warning and progress messages http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/connection.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/connection.hpp b/proton-c/bindings/cpp/include/proton/connection.hpp index cc372be..603d5dd 100644 --- a/proton-c/bindings/cpp/include/proton/connection.hpp +++ b/proton-c/bindings/cpp/include/proton/connection.hpp @@ -145,22 +145,22 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi /// **Unsettled API** - Trigger an event from another thread. /// - /// `wake()` can be called from any thread. The Proton library + /// This method can be called from any thread. The Proton library /// will call `messaging_handler::on_connection_wake()` as soon as /// possible in the correct event-handling thread. /// - /// @note + /// **Thread-safety** - This is the *only* `proton::connection` + /// function that can be called from outside the handler thread. /// - /// * Thread-safe: This is the *only* @ref connection function - /// that can be called from outside the handler thread. - /// * Multiple calls to `wake()` may be coalesced into a single - /// call to `messaging_handler::on_connection_wake()` that - /// occurs after all of them. - /// * Spurious `messaging_handler::on_connection_wake()` calls can - /// occur even if the application does not call `wake()`. + /// @note Spurious `messaging_handler::on_connection_wake()` calls + /// can occur even if the application does not call `wake()`. /// - /// The @ref work_queue interface provides an easier way execute - /// code safely in the event-handler thread. + /// @note Multiple calls to `wake()` may be coalesced into a + /// single call to `messaging_handler::on_connection_wake()` that + /// occurs after all of them. + /// + /// The `proton::work_queue` interface provides an easier way + /// execute code safely in the event-handler thread. PN_CPP_EXTERN void wake() const; /// @cond INTERNAL http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/default_container.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/default_container.hpp b/proton-c/bindings/cpp/include/proton/default_container.hpp index b387ab4..ba49be9 100644 --- a/proton-c/bindings/cpp/include/proton/default_container.hpp +++ b/proton-c/bindings/cpp/include/proton/default_container.hpp @@ -25,7 +25,7 @@ #include "./internal/export.hpp" /// @file -/// @copybrief proton::default_container +/// **Deprecated** - Use the API in `container.hpp`. namespace proton { http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/function.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/function.hpp b/proton-c/bindings/cpp/include/proton/function.hpp index dd89760..2089717 100644 --- a/proton-c/bindings/cpp/include/proton/function.hpp +++ b/proton-c/bindings/cpp/include/proton/function.hpp @@ -21,7 +21,7 @@ */ /// @file -/// @copybrief void_function0 +/// **Deprecated** - Use the API in `work_queue.hpp`. /// @cond INTERNAL http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/listener.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/listener.hpp b/proton-c/bindings/cpp/include/proton/listener.hpp index d8421be..f344892 100644 --- a/proton-c/bindings/cpp/include/proton/listener.hpp +++ b/proton-c/bindings/cpp/include/proton/listener.hpp @@ -38,8 +38,13 @@ class PN_CPP_CLASS_EXTERN listener { public: /// Create an empty listener. PN_CPP_EXTERN listener(); + + /// Copy a listener. PN_CPP_EXTERN listener(const listener&); + PN_CPP_EXTERN ~listener(); + + /// Copy a listener. PN_CPP_EXTERN listener& operator=(const listener&); /// Stop listening on the address provided to the call to http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/message.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp index 07d4132..2273076 100644 --- a/proton-c/bindings/cpp/include/proton/message.hpp +++ b/proton-c/bindings/cpp/include/proton/message.hpp @@ -49,12 +49,10 @@ namespace proton { /// message. class message { public: - /// **Unsettled API** - A map of string keys and AMQP scalar - /// values. + /// A map of string keys and AMQP scalar values. typedef map<std::string, scalar> property_map; - /// **Unsettled API** - A map of AMQP annotation keys and AMQP - /// values. + /// A map of AMQP annotation keys and AMQP values. typedef map<annotation_key, value> annotation_map; /// Create an empty message. @@ -290,25 +288,30 @@ class message { /// @} - /// @name **Unsettled API** - Application properties + /// @name Extended attributes /// @{ - /// **Unsettled API** - Get the application properties map. It can + /// Get the application properties map. It can /// be modified in place. PN_CPP_EXTERN property_map& properties(); - /// **Unsettled API** - examine the application properties map. + /// Examine the application properties map. PN_CPP_EXTERN const property_map& properties() const; - /// @name **Unsettled API** - Annotations - /// - /// Normally used by messaging infrastructure, not applications. - /// @{ + /// Get the message annotations map. It can + /// be modified in place. PN_CPP_EXTERN annotation_map& message_annotations(); + + /// Examine the meessage annotations map. PN_CPP_EXTERN const annotation_map& message_annotations() const; + /// Get the delivery annotations map. It can + /// be modified in place. PN_CPP_EXTERN annotation_map& delivery_annotations(); + + /// Examine the delivery annotations map. PN_CPP_EXTERN const annotation_map& delivery_annotations() const; + /// @} /// Default priority assigned to new messages. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/messaging_handler.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp index 938d3ff..841de7b 100644 --- a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp +++ b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp @@ -41,13 +41,14 @@ namespace proton { /// /// - If `X` is closed cleanly, with no error status, then `on_X_close` /// is called. +/// /// - If `X` is closed with an error, then `on_X_error` is called, /// followed by `on_X_close`. The error condition is also available /// in `on_X_close` from `X::error()`. /// /// By default, if you do not implement `on_X_error`, it will call /// `on_error`. If you do not implement `on_error` it will throw a -/// @ref proton::error exception, which may not be what you want but +/// `proton::error` exception, which may not be what you want but /// does help to identify forgotten error handling quickly. /// /// #### Resource cleanup @@ -65,112 +66,117 @@ PN_CPP_CLASS_EXTERN messaging_handler { PN_CPP_EXTERN virtual ~messaging_handler(); /// The container event loop is starting. - /// This is the first event received after calling container::run - PN_CPP_EXTERN virtual void on_container_start(container &c); + /// + /// This is the first event received after calling + /// `container::run()`. + PN_CPP_EXTERN virtual void on_container_start(container&); /// The container event loop is stopping. - /// This is the last event received before the container event loop stops. - PN_CPP_EXTERN virtual void on_container_stop(container &c); + /// + /// This is the last event received before the container event + /// loop stops. + PN_CPP_EXTERN virtual void on_container_stop(container&); /// A message is received. - PN_CPP_EXTERN virtual void on_message(delivery &d, message &m); + PN_CPP_EXTERN virtual void on_message(delivery&, message&); /// A message can be sent. - PN_CPP_EXTERN virtual void on_sendable(sender &s); + PN_CPP_EXTERN virtual void on_sendable(sender&); /// The underlying network transport is open - PN_CPP_EXTERN virtual void on_transport_open(transport &t); + PN_CPP_EXTERN virtual void on_transport_open(transport&); /// The underlying network transport has closed. - PN_CPP_EXTERN virtual void on_transport_close(transport &t); + PN_CPP_EXTERN virtual void on_transport_close(transport&); /// The underlying network transport has closed with an error /// condition. - PN_CPP_EXTERN virtual void on_transport_error(transport &t); + PN_CPP_EXTERN virtual void on_transport_error(transport&); /// The remote peer opened the connection. - PN_CPP_EXTERN virtual void on_connection_open(connection &c); + PN_CPP_EXTERN virtual void on_connection_open(connection&); /// The remote peer closed the connection. - PN_CPP_EXTERN virtual void on_connection_close(connection &c); + PN_CPP_EXTERN virtual void on_connection_close(connection&); /// The remote peer closed the connection with an error condition. - PN_CPP_EXTERN virtual void on_connection_error(connection &c); + PN_CPP_EXTERN virtual void on_connection_error(connection&); /// The remote peer opened the session. - PN_CPP_EXTERN virtual void on_session_open(session &s); + PN_CPP_EXTERN virtual void on_session_open(session&); /// The remote peer closed the session. - PN_CPP_EXTERN virtual void on_session_close(session &s); + PN_CPP_EXTERN virtual void on_session_close(session&); /// The remote peer closed the session with an error condition. - PN_CPP_EXTERN virtual void on_session_error(session &s); + PN_CPP_EXTERN virtual void on_session_error(session&); /// The remote peer opened the link. - PN_CPP_EXTERN virtual void on_receiver_open(receiver& l); + PN_CPP_EXTERN virtual void on_receiver_open(receiver&); /// The remote peer detached the link. - PN_CPP_EXTERN virtual void on_receiver_detach(receiver& l); + PN_CPP_EXTERN virtual void on_receiver_detach(receiver&); /// The remote peer closed the link. - PN_CPP_EXTERN virtual void on_receiver_close(receiver& l); + PN_CPP_EXTERN virtual void on_receiver_close(receiver&); /// The remote peer closed the link with an error condition. - PN_CPP_EXTERN virtual void on_receiver_error(receiver& l); + PN_CPP_EXTERN virtual void on_receiver_error(receiver&); /// The remote peer opened the link. - PN_CPP_EXTERN virtual void on_sender_open(sender& l); + PN_CPP_EXTERN virtual void on_sender_open(sender&); /// The remote peer detached the link. - PN_CPP_EXTERN virtual void on_sender_detach(sender& l); + PN_CPP_EXTERN virtual void on_sender_detach(sender&); /// The remote peer closed the link. - PN_CPP_EXTERN virtual void on_sender_close(sender& l); + PN_CPP_EXTERN virtual void on_sender_close(sender&); /// The remote peer closed the link with an error condition. - PN_CPP_EXTERN virtual void on_sender_error(sender& l); + PN_CPP_EXTERN virtual void on_sender_error(sender&); /// The receiving peer accepted a transfer. - PN_CPP_EXTERN virtual void on_tracker_accept(tracker &d); + PN_CPP_EXTERN virtual void on_tracker_accept(tracker&); /// The receiving peer rejected a transfer. - PN_CPP_EXTERN virtual void on_tracker_reject(tracker &d); + PN_CPP_EXTERN virtual void on_tracker_reject(tracker&); /// The receiving peer released a transfer. - PN_CPP_EXTERN virtual void on_tracker_release(tracker &d); + PN_CPP_EXTERN virtual void on_tracker_release(tracker&); /// The receiving peer settled a transfer. - PN_CPP_EXTERN virtual void on_tracker_settle(tracker &d); + PN_CPP_EXTERN virtual void on_tracker_settle(tracker&); /// The sending peer settled a transfer. - PN_CPP_EXTERN virtual void on_delivery_settle(delivery &d); + PN_CPP_EXTERN virtual void on_delivery_settle(delivery&); /// **Unsettled API** - The receiving peer has requested a drain of /// remaining credit. - PN_CPP_EXTERN virtual void on_sender_drain_start(sender &s); + PN_CPP_EXTERN virtual void on_sender_drain_start(sender&); /// **Unsettled API** - The credit outstanding at the time of the - /// call to receiver::drain has been consumed or returned. - PN_CPP_EXTERN virtual void on_receiver_drain_finish(receiver &r); + /// drain request has been consumed or returned. + PN_CPP_EXTERN virtual void on_receiver_drain_finish(receiver&); - /// **Unsettled API** - an event that can be triggered from another thread. - /// - /// on_connection_wake() can be triggered by any thread calling connection::wake() - /// It is used to notify the application's @ref messaging_handler instance - /// that something needs attention. + /// **Unsettled API** - An event that can be triggered from + /// another thread. /// - /// The application handler and the triggering thread must use some form of - /// thread-safe state or communication to tell the handler what it needs to do. + /// This event is triggered by a call to `connection::wake()`. It + /// is used to notify the application that something needs + /// attention. /// - /// @note spurious calls to on_connection_wake() can occur without any - /// application call to connection::wake() + /// **Thread-safety** - The application handler and the triggering + /// thread must use some form of thread-safe state or + /// communication to tell the handler what it needs to do. See + /// `proton::work_queue` for an easier way to execute code safely + /// in the handler thread. /// - /// @see work_queue provides an easier way execute code safely in the - /// handler thread. + /// @note Spurious calls to `on_connection_wake()` can occur + /// without any application call to `connection::wake()`. PN_CPP_EXTERN virtual void on_connection_wake(connection&); /// Fallback error handling. - PN_CPP_EXTERN virtual void on_error(const error_condition &c); + PN_CPP_EXTERN virtual void on_error(const error_condition&); }; } // proton http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/thread_safe.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/thread_safe.hpp b/proton-c/bindings/cpp/include/proton/thread_safe.hpp index 81b10b1..dace332 100644 --- a/proton-c/bindings/cpp/include/proton/thread_safe.hpp +++ b/proton-c/bindings/cpp/include/proton/thread_safe.hpp @@ -20,6 +20,9 @@ * under the License. */ +/// @file +/// **Deprecated** - No longer used. + // Removed. Place-holder for for #include compatibility. #endif // PROTON_THREAD_SAFE_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/url.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/url.hpp b/proton-c/bindings/cpp/include/proton/url.hpp index c07f68a..e4c418f 100644 --- a/proton-c/bindings/cpp/include/proton/url.hpp +++ b/proton-c/bindings/cpp/include/proton/url.hpp @@ -31,7 +31,7 @@ #include <string> /// @file -/// @copybrief proton::url +/// **Deprecated** - Use a third-party URL library. namespace proton { http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/bindings/cpp/include/proton/work_queue.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/work_queue.hpp b/proton-c/bindings/cpp/include/proton/work_queue.hpp index 6caea6b..2576193 100644 --- a/proton-c/bindings/cpp/include/proton/work_queue.hpp +++ b/proton-c/bindings/cpp/include/proton/work_queue.hpp @@ -44,13 +44,10 @@ struct pn_link_t; namespace proton { -/// **Unsettled API** - A work item for a @ref work_queue "work queue". -/// -/// It can be created from a function that takes no parameters and -/// returns no value. +/// @cond INTERNAL + namespace v03 { -/// @cond INTERNAL struct invocable { invocable() {} virtual ~invocable() {} @@ -78,18 +75,19 @@ struct invocable_wrapper { invocable* wrapped_; }; -/// @endcond +/// **Unsettled API** - A work item for a @ref work_queue "work queue". +/// +/// It can be created from a function that takes no parameters and +/// returns no value. class work { public: - /// **Unsettled API** + /// Create a work item. work() {} - /// @cond INTERNAL work(const invocable& i): item_(i) {} - /// @endcond - /// **Unsettled API** + /// Invoke the work item. void operator()() { item_(); } ~work() {} @@ -98,9 +96,9 @@ class work { invocable_wrapper item_; }; -/// @cond INTERNAL // Utilities to make work from functions/member functions (C++03 version) // Lots of repetition to handle functions/member functions with up to 3 arguments + template <class R> struct work0 : public invocable_cloner<work0<R> > { R (* fn_)(); @@ -212,10 +210,9 @@ struct work_pmf3 : public invocable_cloner<work_pmf3<R,T,A,B,C> > { (holder_.*fn_)(a_, b_, c_); } }; -/// @endcond -/// make_work is the equivalent of C++11 std::bind for C++03 -/// It will bind both free functions and pointers to member functions +/// `make_work` is the equivalent of C++11 `std::bind` for C++03. It +/// will bind both free functions and pointers to member functions. template <class R, class T> work make_work(R (T::*f)(), T* t) { return work_pmf0<R, T>(f, *t); @@ -256,20 +253,22 @@ work make_work(R (*f)(A, B, C), A a, B b, C c) { return work3<R, A, B, C>(f, a, b, c); } -} +} // v03 #if PN_CPP_HAS_LAMBDAS && PN_CPP_HAS_VARIADIC_TEMPLATES + namespace v11 { + class work { public: /// **Unsettled API** work() {} /// **Unsettled API** + /// /// Construct a unit of work from anything /// function-like that takes no arguments and returns /// no result. - /// template <class T, // Make sure we don't match the copy or move constructors class = typename std::enable_if<!std::is_same<typename std::decay<T>::type,work>::value>::type @@ -277,6 +276,7 @@ class work { work(T&& f): item_(std::forward<T>(f)) {} /// **Unsettled API** + /// /// Execute the piece of work void operator()() { item_(); } @@ -286,17 +286,19 @@ class work { std::function<void()> item_; }; -/// **Unsettled API** +/// **Unsettled API** - Make a unit of work. +/// /// Make a unit of work from either a function or a member function /// and an object pointer. /// -/// This C++11 version is just a wrapper for std::bind +/// **C++ versions** - This C++11 version is just a wrapper for +/// `std::bind`. template <class... Rest> work make_work(Rest&&... r) { return std::bind(std::forward<Rest>(r)...); } -} +} // v11 using v11::work; using v11::make_work; @@ -308,6 +310,8 @@ using v03::make_work; #endif +/// @endcond + /// **Unsettled API** - A context for thread-safe execution of work. /// /// Event-handler functions associated with a single http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/55564c80/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h index 741f3ac..d379436 100644 --- a/proton-c/include/proton/message.h +++ b/proton-c/include/proton/message.h @@ -138,10 +138,6 @@ PN_EXTERN bool pn_message_is_inferred(pn_message_t *msg); */ PN_EXTERN int pn_message_set_inferred(pn_message_t *msg, bool inferred); -/**@group standard message headers and properties - *@{ - */ - /** * Get the durable flag for a message. * @@ -684,7 +680,7 @@ PN_EXTERN pn_data_t *pn_message_instructions(pn_message_t *msg); PN_EXTERN pn_data_t *pn_message_annotations(pn_message_t *msg); /** - * Get/set the properties for a message. + * Get and set the properties for a message. * * This operation returns a pointer to a ::pn_data_t representing the * content of the properties section of a message. The pointer is @@ -699,10 +695,8 @@ PN_EXTERN pn_data_t *pn_message_annotations(pn_message_t *msg); */ PN_EXTERN pn_data_t *pn_message_properties(pn_message_t *msg); -/**@}*/ - /** - * Get/set the body of a message. + * Get and set the body of a message. * * This operation returns a pointer to a ::pn_data_t representing the * body of a message. The pointer is valid until the message is freed --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
