// ssl/stream.hpp
// ~~~~~~~~~~~~~~
//
-// Copyright (c) 2003-2020 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+// Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
core_(ctx.native_handle(), next_layer_.lowest_layer().get_executor())
{
}
+
+ /// Construct a stream from an existing native implementation.
+ /**
+ * This constructor creates a stream and initialises the underlying stream
+ * object. On success, ownership of the native implementation is transferred
+ * to the stream, and it will be cleaned up when the stream is destroyed.
+ *
+ * @param arg The argument to be passed to initialise the underlying stream.
+ *
+ * @param handle An existing native SSL implementation.
+ */
+ template <typename Arg>
+ stream(Arg&& arg, native_handle_type handle)
+ : next_layer_(BOOST_ASIO_MOVE_CAST(Arg)(arg)),
+ core_(handle, next_layer_.lowest_layer().get_executor())
+ {
+ }
#else // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
template <typename Arg>
stream(Arg& arg, context& ctx)
core_(ctx.native_handle(), next_layer_.lowest_layer().get_executor())
{
}
+
+ template <typename Arg>
+ stream(Arg& arg, native_handle_type handle)
+ : next_layer_(arg),
+ core_(handle, next_layer_.lowest_layer().get_executor())
+ {
+ }
#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
#if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
* @param other The other stream object from which the move will occur. Must
* have no outstanding asynchronous operations associated with it. Following
* the move, @c other has a valid but unspecified state where the only safe
- * operation is destruction.
+ * operation is destruction, or use as the target of a move assignment.
*/
stream(stream&& other)
: next_layer_(BOOST_ASIO_MOVE_CAST(Stream)(other.next_layer_)),
core_(BOOST_ASIO_MOVE_CAST(detail::stream_core)(other.core_))
{
}
+
+ /// Move-assign a stream from another.
+ /**
+ * @param other The other stream object from which the move will occur. Must
+ * have no outstanding asynchronous operations associated with it. Following
+ * the move, @c other has a valid but unspecified state where the only safe
+ * operation is destruction, or use as the target of a move assignment.
+ */
+ stream& operator=(stream&& other)
+ {
+ if (this != &other)
+ {
+ next_layer_ = BOOST_ASIO_MOVE_CAST(Stream)(other.next_layer_);
+ core_ = BOOST_ASIO_MOVE_CAST(detail::stream_core)(other.core_);
+ }
+ return *this;
+ }
#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
/// Destructor.
/// Start an asynchronous SSL handshake.
/**
* This function is used to asynchronously perform an SSL handshake on the
- * stream. This function call always returns immediately.
+ * stream. It is an initiating function for an @ref asynchronous_operation,
+ * and always returns immediately.
*
* @param type The type of handshaking to be performed, i.e. as a client or as
* a server.
*
- * @param handler The handler to be called when the handshake operation
- * completes. Copies will be made of the handler as required. The equivalent
- * function signature of the handler must be:
+ * @param token The @ref completion_token that will be used to produce a
+ * completion handler, which will be called when the handshake completes.
+ * Potential completion tokens include @ref use_future, @ref use_awaitable,
+ * @ref yield_context, or a function object with the correct completion
+ * signature. The function signature of the completion handler must be:
* @code void handler(
* const boost::system::error_code& error // Result of operation.
* ); @endcode
+ * Regardless of whether the asynchronous operation completes immediately or
+ * not, the completion handler will not be invoked from within this function.
+ * On immediate completion, invocation of the handler will be performed in a
+ * manner equivalent to using boost::asio::post().
+ *
+ * @par Completion Signature
+ * @code void(boost::system::error_code) @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c Stream type's @c async_read_some and
+ * @c async_write_some operations.
*/
template <
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code))
- HandshakeHandler
+ HandshakeToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(HandshakeHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(HandshakeToken,
void (boost::system::error_code))
async_handshake(handshake_type type,
- BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler
+ BOOST_ASIO_MOVE_ARG(HandshakeToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<HandshakeHandler,
+ return async_initiate<HandshakeToken,
void (boost::system::error_code)>(
- initiate_async_handshake(this), handler, type);
+ initiate_async_handshake(this), token, type);
}
/// Start an asynchronous SSL handshake.
/**
* This function is used to asynchronously perform an SSL handshake on the
- * stream. This function call always returns immediately.
+ * stream. It is an initiating function for an @ref asynchronous_operation,
+ * and always returns immediately.
*
* @param type The type of handshaking to be performed, i.e. as a client or as
* a server.
* @param buffers The buffered data to be reused for the handshake. Although
* the buffers object may be copied as necessary, ownership of the underlying
* buffers is retained by the caller, which must guarantee that they remain
- * valid until the handler is called.
+ * valid until the completion handler is called.
*
- * @param handler The handler to be called when the handshake operation
- * completes. Copies will be made of the handler as required. The equivalent
- * function signature of the handler must be:
+ * @param token The @ref completion_token that will be used to produce a
+ * completion handler, which will be called when the handshake completes.
+ * Potential completion tokens include @ref use_future, @ref use_awaitable,
+ * @ref yield_context, or a function object with the correct completion
+ * signature. The function signature of the completion handler must be:
* @code void handler(
* const boost::system::error_code& error, // Result of operation.
* std::size_t bytes_transferred // Amount of buffers used in handshake.
* ); @endcode
+ * Regardless of whether the asynchronous operation completes immediately or
+ * not, the completion handler will not be invoked from within this function.
+ * On immediate completion, invocation of the handler will be performed in a
+ * manner equivalent to using boost::asio::post().
+ *
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c Stream type's @c async_read_some and
+ * @c async_write_some operations.
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) BufferedHandshakeHandler
+ std::size_t)) BufferedHandshakeToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(BufferedHandshakeHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(BufferedHandshakeToken,
void (boost::system::error_code, std::size_t))
async_handshake(handshake_type type, const ConstBufferSequence& buffers,
- BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler
+ BOOST_ASIO_MOVE_ARG(BufferedHandshakeToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<BufferedHandshakeHandler,
+ return async_initiate<BufferedHandshakeToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_buffered_handshake(this), handler, type, buffers);
+ initiate_async_buffered_handshake(this), token, type, buffers);
}
/// Shut down SSL on the stream.
/// Asynchronously shut down SSL on the stream.
/**
- * This function is used to asynchronously shut down SSL on the stream. This
- * function call always returns immediately.
- *
- * @param handler The handler to be called when the handshake operation
- * completes. Copies will be made of the handler as required. The equivalent
- * function signature of the handler must be:
+ * This function is used to asynchronously shut down SSL on the stream. It is
+ * an initiating function for an @ref asynchronous_operation, and always
+ * returns immediately.
+ *
+ * @param token The @ref completion_token that will be used to produce a
+ * completion handler, which will be called when the shutdown completes.
+ * Potential completion tokens include @ref use_future, @ref use_awaitable,
+ * @ref yield_context, or a function object with the correct completion
+ * signature. The function signature of the completion handler must be:
* @code void handler(
* const boost::system::error_code& error // Result of operation.
* ); @endcode
+ * Regardless of whether the asynchronous operation completes immediately or
+ * not, the completion handler will not be invoked from within this function.
+ * On immediate completion, invocation of the handler will be performed in a
+ * manner equivalent to using boost::asio::post().
+ *
+ * @par Completion Signature
+ * @code void(boost::system::error_code) @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c Stream type's @c async_read_some and
+ * @c async_write_some operations.
*/
template <
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code))
- ShutdownHandler
+ ShutdownToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ShutdownHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ShutdownToken,
void (boost::system::error_code))
async_shutdown(
- BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler
+ BOOST_ASIO_MOVE_ARG(ShutdownToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ShutdownHandler,
+ return async_initiate<ShutdownToken,
void (boost::system::error_code)>(
- initiate_async_shutdown(this), handler);
+ initiate_async_shutdown(this), token);
}
/// Write some data to the stream.
/// Start an asynchronous write.
/**
* This function is used to asynchronously write one or more bytes of data to
- * the stream. The function call always returns immediately.
+ * the stream. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param buffers The data to be written to the stream. Although the buffers
* object may be copied as necessary, ownership of the underlying buffers is
* retained by the caller, which must guarantee that they remain valid until
- * the handler is called.
+ * the completion handler is called.
*
- * @param handler The handler to be called when the write operation completes.
- * Copies will be made of the handler as required. The equivalent function
- * signature of the handler must be:
+ * @param token The @ref completion_token that will be used to produce a
+ * completion handler, which will be called when the write completes.
+ * Potential completion tokens include @ref use_future, @ref use_awaitable,
+ * @ref yield_context, or a function object with the correct completion
+ * signature. The function signature of the completion handler must be:
* @code void handler(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes written.
+ * std::size_t bytes_transferred // Number of bytes written.
* ); @endcode
+ * Regardless of whether the asynchronous operation completes immediately or
+ * not, the completion handler will not be invoked from within this function.
+ * On immediate completion, invocation of the handler will be performed in a
+ * manner equivalent to using boost::asio::post().
+ *
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
*
* @note The async_write_some operation may not transmit all of the data to
* the peer. Consider using the @ref async_write function if you need to
* ensure that all data is written before the asynchronous operation
* completes.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c Stream type's @c async_read_some and
+ * @c async_write_some operations.
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) WriteHandler
+ std::size_t)) WriteToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken,
void (boost::system::error_code, std::size_t))
async_write_some(const ConstBufferSequence& buffers,
- BOOST_ASIO_MOVE_ARG(WriteHandler) handler
+ BOOST_ASIO_MOVE_ARG(WriteToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<WriteHandler,
+ return async_initiate<WriteToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_write_some(this), handler, buffers);
+ initiate_async_write_some(this), token, buffers);
}
/// Read some data from the stream.
/// Start an asynchronous read.
/**
* This function is used to asynchronously read one or more bytes of data from
- * the stream. The function call always returns immediately.
+ * the stream. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param buffers The buffers into which the data will be read. Although the
* buffers object may be copied as necessary, ownership of the underlying
* buffers is retained by the caller, which must guarantee that they remain
- * valid until the handler is called.
+ * valid until the completion handler is called.
*
- * @param handler The handler to be called when the read operation completes.
- * Copies will be made of the handler as required. The equivalent function
- * signature of the handler must be:
+ * @param token The @ref completion_token that will be used to produce a
+ * completion handler, which will be called when the read completes.
+ * Potential completion tokens include @ref use_future, @ref use_awaitable,
+ * @ref yield_context, or a function object with the correct completion
+ * signature. The function signature of the completion handler must be:
* @code void handler(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes read.
+ * std::size_t bytes_transferred // Number of bytes read.
* ); @endcode
+ * Regardless of whether the asynchronous operation completes immediately or
+ * not, the completion handler will not be invoked from within this function.
+ * On immediate completion, invocation of the handler will be performed in a
+ * manner equivalent to using boost::asio::post().
+ *
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
*
* @note The async_read_some operation may not read all of the requested
* number of bytes. Consider using the @ref async_read function if you need to
* ensure that the requested amount of data is read before the asynchronous
* operation completes.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c Stream type's @c async_read_some and
+ * @c async_write_some operations.
*/
template <typename MutableBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_some(const MutableBufferSequence& buffers,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ReadHandler,
+ return async_initiate<ReadToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_read_some(this), handler, buffers);
+ initiate_async_read_some(this), token, buffers);
}
private:
projects / ceph.git / blobdiff