beast/core/saved_handler.hpp

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/beast
0008 //
0009
0010 #ifndef BOOST_BEAST_CORE_SAVED_HANDLER_HPP
0011 #define BOOST_BEAST_CORE_SAVED_HANDLER_HPP
0012
0013 #include <boost/beast/core/detail/config.hpp>
0014 #include <boost/asio/cancellation_type.hpp>
0015
0016 namespace boost {
0017 namespace beast {
0018
0019 /** An invocable, nullary function object which holds a completion handler.
0020
0021     This container can hold a type-erased instance of any completion
0022     handler, or it can be empty. When the container holds a value,
0023     the implementation maintains an instance of `net::executor_work_guard`
0024     for the handler's associated executor. Memory is dynamically allocated
0025     to store the completion handler, and the allocator may optionally
0026     be specified. Otherwise, the implementation uses the handler's
0027     associated allocator.
0028 */
0029 class saved_handler
0030 {
0031     class base;
0032
0033     template<class, class>
0034     class impl;
0035
0036     base* p_ = nullptr;
0037
0038 public:
0039     /// Default Constructor
0040     saved_handler() = default;
0041
0042     /// Copy Constructor (deleted)
0043     saved_handler(saved_handler const&) = delete;
0044
0045     /// Copy Assignment (deleted)
0046     saved_handler& operator=(saved_handler const&) = delete;
0047
0048     /// Destructor
0049     BOOST_BEAST_DECL
0050     ~saved_handler();
0051
0052     /// Move Constructor
0053     BOOST_BEAST_DECL
0054     saved_handler(saved_handler&& other) noexcept;
0055
0056     /// Move Assignment
0057     BOOST_BEAST_DECL
0058     saved_handler&
0059     operator=(saved_handler&& other) noexcept;
0060
0061     /// Returns `true` if `*this` contains a completion handler.
0062     bool
0063     has_value() const noexcept
0064     {
0065         return p_ != nullptr;
0066     }
0067
0068     /** Store a completion handler in the container.
0069
0070         Requires `this->has_value() == false`.
0071
0072         @param handler The completion handler to store.
0073         The implementation takes ownership of the handler by performing a decay-copy.
0074
0075         @param alloc The allocator to use.
0076
0077         @param cancel_type The type of cancellation allowed to complete this op.
0078     */
0079     template<class Handler, class Allocator>
0080     void
0081     emplace(Handler&& handler, Allocator const& alloc,
0082             net::cancellation_type cancel_type = net::cancellation_type::terminal);
0083
0084     /** Store a completion handler in the container.
0085
0086         Requires `this->has_value() == false`. The
0087         implementation will use the handler's associated
0088         allocator to obtian storage.
0089
0090         @param handler The completion handler to store.
0091         The implementation takes ownership of the handler by performing a decay-copy.
0092
0093         @param cancel_type The type of cancellation allowed to complete this op.
0094     */
0095     template<class Handler>
0096     void
0097     emplace(Handler&& handler,
0098             net::cancellation_type cancel_type = net::cancellation_type::terminal);
0099
0100     /** Discard the saved handler, if one exists.
0101
0102         If `*this` contains an object, it is destroyed.
0103
0104         @returns `true` if an object was destroyed.
0105     */
0106     BOOST_BEAST_DECL
0107     bool
0108     reset() noexcept;
0109
0110     /** Unconditionally invoke the stored completion handler.
0111
0112         Requires `this->has_value() == true`. Any dynamic memory
0113         used is deallocated before the stored completion handler
0114         is invoked. The executor work guard is also reset before
0115         the invocation.
0116     */
0117     BOOST_BEAST_DECL
0118     void
0119     invoke();
0120
0121     /** Conditionally invoke the stored completion handler.
0122
0123         Invokes the stored completion handler if
0124         `this->has_value() == true`, otherwise does nothing. Any
0125         dynamic memory used is deallocated before the stored completion
0126         handler is invoked. The executor work guard is also reset before
0127         the invocation.
0128
0129         @return `true` if the invocation took place.
0130     */
0131     BOOST_BEAST_DECL
0132     bool
0133     maybe_invoke();
0134 };
0135
0136 } // beast
0137 } // boost
0138
0139 #include <boost/beast/core/impl/saved_handler.hpp>
0140 #ifdef BOOST_BEAST_HEADER_ONLY
0141 #include <boost/beast/core/impl/saved_handler.ipp>
0142 #endif
0143
0144 #endif