template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec);
This function is used to write data to the stream socket. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.
One or more data buffers to be written to the socket.
Set to indicate what error occurred, if any.
The number of bytes written. Returns 0 if an error occurred.
The write_some operation may not transmit all of the data to the peer.
Consider using the write
function if you need to
ensure that all data is written before the blocking operation completes.
Automatically resizable buffer class based on std::streambuf.
template< typename Allocator = std::allocator<char>> class basic_streambuf : noncopyable
|
Name |
Description |
|---|---|
|
The type used to represent the input sequence as a list of buffers. |
|
|
The type used to represent the output sequence as a list of buffers. |
|
Name |
Description |
|---|---|
|
Construct a basic_streambuf object. |
|
|
Move characters from the output sequence to the input sequence. |
|
|
Remove characters from the input sequence. |
|
|
Get a list of buffers that represents the input sequence. |
|
|
Get the maximum size of the basic_streambuf. |
|
|
Get a list of buffers that represents the output sequence, with the given size. |
|
|
Get the size of the input sequence. |
|
Name |
Description |
|---|---|
|
Override std::streambuf behaviour. |
|
|
Override std::streambuf behaviour. |
The basic_streambuf
class
is derived from std::streambuf
to associate the streambuf's
input and output sequences with one or more character arrays. These character
arrays are internal to the basic_streambuf
object, but direct access to the array elements is provided to permit them
to be used efficiently with I/O operations. Characters written to the output
sequence of a basic_streambuf
object are appended to the input sequence of the same object.
The basic_streambuf
class's
public interface is intended to permit the following implementation strategies:
The constructor for basic_streambuf
accepts a size_t
argument specifying the maximum
of the sum of the sizes of the input sequence and output sequence. During
the lifetime of the basic_streambuf
object, the following invariant holds:
size() <= max_size()
Any member function that would, if successful, cause the invariant to be
violated shall throw an exception of class std::length_error
.
The constructor for basic_streambuf
takes an Allocator argument. A copy of this argument is used for any memory
allocation performed, by the constructor and by all member functions, during
the lifetime of each basic_streambuf
object.
Writing directly from an streambuf to a socket:
boost::asio::streambuf b; std::ostream os(&b); os << "Hello, World!\n"; // try sending some data in input sequence size_t n = sock.send(b.data()); b.consume(n); // sent data is removed from input sequence
Reading from a socket directly into a streambuf:
boost::asio::streambuf b; // reserve 512 bytes in output sequence boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512); size_t n = sock.receive(bufs); // received data is "committed" from output sequence to input sequence b.commit(n); std::istream is(&b); std::string s; is >> s;
Header: boost/asio/basic_streambuf.hpp
Convenience header: boost/asio.hpp
Construct a basic_streambuf
object.
basic_streambuf( std::size_t maximum_size = (std::numeric_limits< std::size_t >::max)(), const Allocator & allocator = Allocator());
Constructs a streambuf with the specified maximum size. The initial size of the streambuf's input sequence is 0.
Move characters from the output sequence to the input sequence.
void commit( std::size_t n);
Appends n
characters from
the start of the output sequence to the input sequence. The beginning of
the output sequence is advanced by n
characters.
Requires a preceding call prepare(x)
where x >=
n
, and no intervening operations
that modify the input or output sequence.
If n
is greater than the
size of the output sequence, the entire output sequence is moved to the
input sequence and no error is issued.
The type used to represent the input sequence as a list of buffers.
typedef implementation_defined const_buffers_type;
Header: boost/asio/basic_streambuf.hpp
Convenience header: boost/asio.hpp
Remove characters from the input sequence.
void consume( std::size_t n);
Removes n
characters from
the beginning of the input sequence.
If n
is greater than the
size of the input sequence, the entire input sequence is consumed and no
error is issued.
Get a list of buffers that represents the input sequence.
const_buffers_type data() const;
An object of type const_buffers_type
that satisfies ConstBufferSequence requirements, representing all character
arrays in the input sequence.
The returned object is invalidated by any basic_streambuf
member function that modifies the input sequence or output sequence.
Get the maximum size of the basic_streambuf
.
std::size_t max_size() const;
The allowed maximum of the sum of the sizes of the input sequence and output sequence.
The type used to represent the output sequence as a list of buffers.
typedef implementation_defined mutable_buffers_type;
Header: boost/asio/basic_streambuf.hpp
Convenience header: boost/asio.hpp
Override std::streambuf behaviour.
int_type overflow( int_type c);
Behaves according to the specification of std::streambuf::overflow()
, with the specialisation that std::length_error
is thrown if appending the
character to the input sequence would require the condition size() > max_size()
to be true.
Get a list of buffers that represents the output sequence, with the given size.
mutable_buffers_type prepare( std::size_t n);
Ensures that the output sequence can accommodate n
characters, reallocating character array objects as necessary.
An object of type mutable_buffers_type
that satisfies MutableBufferSequence requirements, representing character
array objects at the start of the output sequence such that the sum of
the buffer sizes is n
.
If size()
+ n
> max_size()
.
The returned object is invalidated by any basic_streambuf
member function that modifies the input sequence or output sequence.
Get the size of the input sequence.
std::size_t size() const;
The size of the input sequence. The value is equal to that calculated for
s
in the following code:
size_t s = 0; const_buffers_type bufs = data(); const_buffers_type::const_iterator i = bufs.begin(); while (i != bufs.end()) { const_buffer buf(*i++); s += buffer_size(buf); }
Provides waitable timer functionality.
template< typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>, typename WaitableTimerService = waitable_timer_service<Clock, WaitTraits>> class basic_waitable_timer : public basic_io_object< WaitableTimerService >
|
Name |
Description |
|---|---|
|
The clock type. |
|
|
The duration type of the clock. |
|
|
The underlying implementation type of I/O object. |
|
|
The type of the service that will be used to provide I/O operations. |
|
|
The time point type of the clock. |
|
|
The wait traits type. |
|
Name |
Description |
|---|---|
|
Start an asynchronous wait on the timer. |
|
|
Constructor. Constructor to set a particular expiry time as an absolute time. Constructor to set a particular expiry time relative to now. |
|
|
Cancel any asynchronous operations that are waiting on the timer. |
|
|
Cancels one asynchronous operation that is waiting on the timer. |
|
|
Get the timer's expiry time as an absolute time. Set the timer's expiry time as an absolute time. |
|
|
Get the timer's expiry time relative to now. Set the timer's expiry time relative to now. |
|
|
Get the io_service associated with the object. |
|
|
Perform a blocking wait on the timer. |
|
Name |
Description |
|---|---|
|
Get the underlying implementation of the I/O object. |
|
|
Get the service associated with the I/O object. |
|
Name |
Description |
|---|---|
|
(Deprecated: Use get_implementation().) The underlying implementation of the I/O object. |
|
|
(Deprecated: Use get_service().) The service associated with the I/O object. |
The basic_waitable_timer
class template
provides the ability to perform a blocking or asynchronous wait for a timer
to expire.
A waitable timer is always in one of two states: "expired" or "not
expired". If the wait()
or async_wait()
function is called on an expired timer,
the wait operation will complete immediately.
Most applications will use one of the steady_timer
, system_timer
or high_resolution_timer
typedefs.
This waitable timer functionality is for use with the C++11 standard library's
<chrono>
facility, or with the Boost.Chrono library.
Distinct objects: Safe.
Shared objects: Unsafe.
Performing a blocking wait (C++11):
// Construct a timer without setting an expiry time. boost::asio::steady_timer timer(io_service); // Set an expiry time relative to now. timer.expires_from_now(std::chrono::seconds(5)); // Wait for the timer to expire. timer.wait();
Performing an asynchronous wait (C++11):
void handler(const boost::system::error_code& error) { if (!error) { // Timer expired. } } ... // Construct a timer with an absolute expiry time. boost::asio::steady_timer timer(io_service, std::chrono::steady_clock::now() + std::chrono::seconds(60)); // Start an asynchronous wait. timer.async_wait(handler);
Changing the expiry time of a timer while there are pending asynchronous waits causes those wait operations to be cancelled. To ensure that the action associated with the timer is performed only once, use something like this: used:
void on_some_event() { if (my_timer.expires_from_now(seconds(5)) > 0) { // We managed to cancel the timer. Start new asynchronous wait. my_timer.async_wait(on_timeout); } else { // Too late, timer has already expired! } } void on_timeout(const boost::system::error_code& e) { if (e != boost::asio::error::operation_aborted) { // Timer was not cancelled, take necessary action. } }
boost::asio::basic_waitable_timer::expires_from_now()
function cancels any pending asynchronous waits, and returns the number
of asynchronous waits that were cancelled. If it returns 0 then you were
too late and the wait handler has already been executed, or will soon
be executed. If it returns 1 then the wait handler was successfully cancelled.
boost::asio::error::operation_aborted
.
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
Start an asynchronous wait on the timer.
template< typename WaitHandler> void-or-deduced async_wait( WaitHandler handler);
This function may be used to initiate an asynchronous wait against the timer. It always returns immediately.
For each call to async_wait()
, the supplied handler will be called
exactly once. The handler will be called when:
boost::asio::error::operation_aborted
.
The handler to be called when the timer expires. Copies will be made of the handler as required. The function signature of the handler must be:
void handler( const boost::system::error_code& error // Result of operation. );
Regardless of whether the asynchronous operation completes immediately
or not, the handler will not be invoked from within this function.
Invocation of the handler will be performed in a manner equivalent
to using boost::asio::io_service::post()
.
explicit basic_waitable_timer( boost::asio::io_service & io_service); » more...
Constructor to set a particular expiry time as an absolute time.
basic_waitable_timer( boost::asio::io_service & io_service, const time_point & expiry_time); » more...
Constructor to set a particular expiry time relative to now.
basic_waitable_timer( boost::asio::io_service & io_service, const duration & expiry_time); » more...
Constructor.
basic_waitable_timer( boost::asio::io_service & io_service);
This constructor creates a timer without setting an expiry time. The
expires_at()
or expires_from_now()
functions must be called to set an expiry time before the timer can be
waited on.
The io_service
object that
the timer will use to dispatch handlers for any asynchronous operations
performed on the timer.
Constructor to set a particular expiry time as an absolute time.
basic_waitable_timer( boost::asio::io_service & io_service, const time_point & expiry_time);
This constructor creates a timer and sets the expiry time.
The io_service
object that
the timer will use to dispatch handlers for any asynchronous operations
performed on the timer.
The expiry time to be used for the timer, expressed as an absolute time.
Constructor to set a particular expiry time relative to now.
basic_waitable_timer( boost::asio::io_service & io_service, const duration & expiry_time);
This constructor creates a timer and sets the expiry time.
The io_service
object that
the timer will use to dispatch handlers for any asynchronous operations
performed on the timer.
The expiry time to be used for the timer, relative to now.
Cancel any asynchronous operations that are waiting on the timer.
std::size_t cancel(); » more... std::size_t cancel( boost::system::error_code & ec); » more...
Cancel any asynchronous operations that are waiting on the timer.
std::size_t cancel();
This function forces the completion of any pending asynchronous wait
operations against the timer. The handler for each cancelled operation
will be invoked with the boost::asio::error::operation_aborted
error code.
Cancelling the timer does not change the expiry time.
The number of asynchronous operations that were cancelled.
Thrown on failure.
If the timer has already expired when cancel()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Cancel any asynchronous operations that are waiting on the timer.
std::size_t cancel( boost::system::error_code & ec);
This function forces the completion of any pending asynchronous wait
operations against the timer. The handler for each cancelled operation
will be invoked with the boost::asio::error::operation_aborted
error code.
Cancelling the timer does not change the expiry time.
Set to indicate what error occurred, if any.
The number of asynchronous operations that were cancelled.
If the timer has already expired when cancel()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Cancels one asynchronous operation that is waiting on the timer.
std::size_t cancel_one(); » more... std::size_t cancel_one( boost::system::error_code & ec); » more...
Cancels one asynchronous operation that is waiting on the timer.
std::size_t cancel_one();
This function forces the completion of one pending asynchronous wait
operation against the timer. Handlers are cancelled in FIFO order. The
handler for the cancelled operation will be invoked with the boost::asio::error::operation_aborted
error code.
Cancelling the timer does not change the expiry time.
The number of asynchronous operations that were cancelled. That is, either 0 or 1.
Thrown on failure.
If the timer has already expired when cancel_one()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Cancels one asynchronous operation that is waiting on the timer.
std::size_t cancel_one( boost::system::error_code & ec);
This function forces the completion of one pending asynchronous wait
operation against the timer. Handlers are cancelled in FIFO order. The
handler for the cancelled operation will be invoked with the boost::asio::error::operation_aborted
error code.
Cancelling the timer does not change the expiry time.
Set to indicate what error occurred, if any.
The number of asynchronous operations that were cancelled. That is, either 0 or 1.
If the timer has already expired when cancel_one()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
typedef Clock clock_type;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
The duration type of the clock.
typedef clock_type::duration duration;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
Get the timer's expiry time as an absolute time.
time_point expires_at() const; » more...
Set the timer's expiry time as an absolute time.
std::size_t expires_at( const time_point & expiry_time); » more... std::size_t expires_at( const time_point & expiry_time, boost::system::error_code & ec); » more...
Get the timer's expiry time as an absolute time.
time_point expires_at() const;
This function may be used to obtain the timer's current expiry time. Whether the timer has expired or not does not affect this value.
Set the timer's expiry time as an absolute time.
std::size_t expires_at( const time_point & expiry_time);
This function sets the expiry time. Any pending asynchronous wait operations
will be cancelled. The handler for each cancelled operation will be invoked
with the boost::asio::error::operation_aborted
error code.
The expiry time to be used for the timer.
The number of asynchronous operations that were cancelled.
Thrown on failure.
If the timer has already expired when expires_at()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Set the timer's expiry time as an absolute time.
std::size_t expires_at( const time_point & expiry_time, boost::system::error_code & ec);
This function sets the expiry time. Any pending asynchronous wait operations
will be cancelled. The handler for each cancelled operation will be invoked
with the boost::asio::error::operation_aborted
error code.
The expiry time to be used for the timer.
Set to indicate what error occurred, if any.
The number of asynchronous operations that were cancelled.
If the timer has already expired when expires_at()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Get the timer's expiry time relative to now.
duration expires_from_now() const; » more...
Set the timer's expiry time relative to now.
std::size_t expires_from_now( const duration & expiry_time); » more... std::size_t expires_from_now( const duration & expiry_time, boost::system::error_code & ec); » more...
Get the timer's expiry time relative to now.
duration expires_from_now() const;
This function may be used to obtain the timer's current expiry time. Whether the timer has expired or not does not affect this value.
Set the timer's expiry time relative to now.
std::size_t expires_from_now( const duration & expiry_time);
This function sets the expiry time. Any pending asynchronous wait operations
will be cancelled. The handler for each cancelled operation will be invoked
with the boost::asio::error::operation_aborted
error code.
The expiry time to be used for the timer.
The number of asynchronous operations that were cancelled.
Thrown on failure.
If the timer has already expired when expires_from_now()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Set the timer's expiry time relative to now.
std::size_t expires_from_now( const duration & expiry_time, boost::system::error_code & ec);
This function sets the expiry time. Any pending asynchronous wait operations
will be cancelled. The handler for each cancelled operation will be invoked
with the boost::asio::error::operation_aborted
error code.
The expiry time to be used for the timer.
Set to indicate what error occurred, if any.
The number of asynchronous operations that were cancelled.
If the timer has already expired when expires_from_now()
is called, then the handlers for asynchronous
wait operations will:
These handlers can no longer be cancelled, and therefore are passed an error code that indicates the successful completion of the wait operation.
Get the underlying implementation of the I/O object.
implementation_type & get_implementation(); » more... const implementation_type & get_implementation() const; » more...
Inherited from basic_io_object.
Get the underlying implementation of the I/O object.
implementation_type & get_implementation();
Inherited from basic_io_object.
Get the underlying implementation of the I/O object.
const implementation_type & get_implementation() const;
Inherited from basic_io_object.
Get the io_service
associated with the
object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service
object that the I/O
object uses to dispatch handlers for asynchronous operations.
A reference to the io_service
object that the I/O
object will use to dispatch handlers. Ownership is not transferred to the
caller.
Get the service associated with the I/O object.
service_type & get_service(); » more... const service_type & get_service() const; » more...
Inherited from basic_io_object.
Get the service associated with the I/O object.
service_type & get_service();
Inherited from basic_io_object.
Get the service associated with the I/O object.
const service_type & get_service() const;
Inherited from basic_io_object.
(Deprecated: Use get_implementation()
.) The underlying implementation of the
I/O object.
implementation_type implementation;
Inherited from basic_io_object.
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
Inherited from basic_io_object.
(Deprecated: Use get_service()
.) The service associated with the I/O
object.
service_type & service;
Available only for services that do not support movability.
Inherited from basic_io_object.
The type of the service that will be used to provide I/O operations.
typedef WaitableTimerService service_type;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
The time point type of the clock.
typedef clock_type::time_point time_point;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
typedef WaitTraits traits_type;
Header: boost/asio/basic_waitable_timer.hpp
Convenience header: boost/asio.hpp
Perform a blocking wait on the timer.
void wait(); » more... void wait( boost::system::error_code & ec); » more...
Perform a blocking wait on the timer.
void wait();
This function is used to wait for the timer to expire. This function blocks and does not return until the timer has expired.
Thrown on failure.
Perform a blocking wait on the timer.
void wait( boost::system::error_code & ec);
This function is used to wait for the timer to expire. This function blocks and does not return until the timer has expired.
Set to indicate what error occurred, if any.
Context object the represents the currently executing coroutine.
template< typename Handler> class basic_yield_context
|
Name |
Description |
|---|---|
|
The coroutine callee type, used by the implementation. |
|
|
The coroutine caller type, used by the implementation. |
|
Name |
Description |
|---|---|
|
Construct a yield context to represent the specified coroutine. |
|
|
Return a yield context that sets the specified error_code. |
The basic_yield_context
class is used
to represent the currently executing stackful coroutine. A basic_yield_context
may be passed
as a handler to an asynchronous operation. For example:
template <typename Handler> void my_coroutine(basic_yield_context<Handler> yield) { ... std::size_t n = my_socket.async_read_some(buffer, yield); ... }
The initiating function (async_read_some in the above example) suspends the current coroutine. The coroutine is resumed when the asynchronous operation completes, and the result of the operation is returned.
Header: boost/asio/spawn.hpp
Convenience header: None
Construct a yield context to represent the specified coroutine.
basic_yield_context( const detail::weak_ptr< callee_type > & coro, caller_type & ca, Handler & handler);
Most applications do not need to use this constructor. Instead, the spawn()
function passes a yield context as an argument to the coroutine function.
The coroutine callee type, used by the implementation.
typedef implementation_defined callee_type;
When using Boost.Coroutine v1, this type is:
typename coroutine<void()>
When using Boost.Coroutine v2 (unidirectional coroutines), this type is:
push_coroutine<void>
Header: boost/asio/spawn.hpp
Convenience header: None
The coroutine caller type, used by the implementation.
typedef implementation_defined caller_type;
When using Boost.Coroutine v1, this type is:
typename coroutine<void()>::caller_type
When using Boost.Coroutine v2 (unidirectional coroutines), this type is:
pull_coroutine<void>
Header: boost/asio/spawn.hpp
Convenience header: None
Return a yield context that sets the specified error_code.
basic_yield_context operator[]( boost::system::error_code & ec) const;
By default, when a yield context is used with an asynchronous operation, a non-success error_code is converted to system_error and thrown. This operator may be used to specify an error_code object that should instead be set with the asynchronous operation's result. For example:
template <typename Handler> void my_coroutine(basic_yield_context<Handler> yield) { ... std::size_t n = my_socket.async_read_some(buffer, yield[ec]); if (ec) { // An error occurred. } ... }
The boost::asio::buffer
function is used to create a buffer
object to represent raw memory, an array of POD elements, a vector of POD
elements, or a std::string.
mutable_buffers_1 buffer( const mutable_buffer & b); » more... mutable_buffers_1 buffer( const mutable_buffer & b, std::size_t max_size_in_bytes); » more... const_buffers_1 buffer( const const_buffer & b); » more... const_buffers_1 buffer( const const_buffer & b, std::size_t max_size_in_bytes); » more... mutable_buffers_1 buffer( void * data, std::size_t size_in_bytes); » more... const_buffers_1 buffer( const void * data, std::size_t size_in_bytes); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType (&data)[N]); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType (&data)[N], std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType (&data)[N]); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType (&data)[N], std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( std::array< PodType, N > & data); » more... template< typename PodType, std::size_t N> mutable_buffers_1 buffer( std::array< PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( std::array< const PodType, N > & data); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( std::array< const PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const std::array< PodType, N > & data); » more... template< typename PodType, std::size_t N> const_buffers_1 buffer( const std::array< PodType, N > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data); » more... template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes); » more... template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data); » more... template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes); » more... template< typename Elem, typename Traits, typename Allocator> const_buffers_1 buffer( const std::basic_string< Elem, Traits, Allocator > & data); » more... template< typename Elem, typename Traits, typename Allocator> const_buffers_1 buffer( const std::basic_string< Elem, Traits, Allocator > & data, std::size_t max_size_in_bytes); » more...
A buffer object represents a contiguous region of memory as a 2-tuple consisting
of a pointer and size in bytes. A tuple of the form {void*, size_t}
specifies a mutable (modifiable) region
of memory. Similarly, a tuple of the form {const void*, size_t}
specifies a const (non-modifiable) region
of memory. These two forms correspond to the classes mutable_buffer
and const_buffer
, respectively. To mirror
C++'s conversion rules, a mutable_buffer
is implicitly convertible
to a const_buffer
,
and the opposite conversion is not permitted.
The simplest use case involves reading or writing a single buffer of a specified size:
sock.send(boost::asio::buffer(data, size));
In the above example, the return value of boost::asio::buffer
meets the requirements of the ConstBufferSequence concept so that it may
be directly passed to the socket's write function. A buffer created for modifiable
memory also meets the requirements of the MutableBufferSequence concept.
An individual buffer may be created from a builtin array, std::vector, std::array or boost::array of POD elements. This helps prevent buffer overruns by automatically determining the size of the buffer:
char d1[128]; size_t bytes_transferred = sock.receive(boost::asio::buffer(d1)); std::vector<char> d2(128); bytes_transferred = sock.receive(boost::asio::buffer(d2)); std::array<char, 128> d3; bytes_transferred = sock.receive(boost::asio::buffer(d3)); boost::array<char, 128> d4; bytes_transferred = sock.receive(boost::asio::buffer(d4));
In all three cases above, the buffers created are exactly 128 bytes long.
Note that a vector is never automatically resized when
creating or using a buffer. The buffer size is determined using the vector's
size()
member function, and not its capacity.
The contents of a buffer may be accessed using the buffer_size
and buffer_cast
functions:
boost::asio::mutable_buffer b1 = ...; std::size_t s1 = boost::asio::buffer_size(b1); unsigned char* p1 = boost::asio::buffer_cast<unsigned char*>(b1); boost::asio::const_buffer b2 = ...; std::size_t s2 = boost::asio::buffer_size(b2); const void* p2 = boost::asio::buffer_cast<const void*>(b2);
The boost::asio::buffer_cast
function permits violations
of type safety, so uses of it in application code should be carefully considered.
For convenience, the buffer_size
function also works
on buffer sequences (that is, types meeting the ConstBufferSequence or MutableBufferSequence
type requirements). In this case, the function returns the total size of
all buffers in the sequence.
The buffer_copy
function may be used to copy raw bytes between individual buffers and buffer
sequences.
In particular, when used with the buffer_size
, the buffer_copy
function can be used
to linearise a sequence of buffers. For example:
vector<const_buffer> buffers = ...; vector<unsigned char> data(boost::asio::buffer_size(buffers)); boost::asio::buffer_copy(boost::asio::buffer(data), buffers);
Note that buffer_copy
is implemented in terms
of memcpy
, and consequently
it cannot be used to copy between overlapping memory regions.
A buffer object does not have any ownership of the memory it refers to. It is the responsibility of the application to ensure the memory region remains valid until it is no longer required for an I/O operation. When the memory is no longer available, the buffer is said to have been invalidated.
For the boost::asio::buffer
overloads that accept an argument
of type std::vector, the buffer objects returned are invalidated by any vector
operation that also invalidates all references, pointers and iterators referring
to the elements in the sequence (C++ Std, 23.2.4)
For the boost::asio::buffer
overloads that accept an argument
of type std::basic_string, the buffer objects returned are invalidated according
to the rules defined for invalidation of references, pointers and iterators
referring to elements of the sequence (C++ Std, 21.3).
Buffer objects may be manipulated using simple arithmetic in a safe way which helps prevent buffer overruns. Consider an array initialised as follows:
boost::array<char, 6> a = { 'a', 'b', 'c', 'd', 'e' };
A buffer object b1
created
using:
b1 = boost::asio::buffer(a);
represents the entire array, { 'a', 'b', 'c',
'd', 'e' }
. An optional
second argument to the boost::asio::buffer
function may be used to limit the size, in bytes, of the buffer:
b2 = boost::asio::buffer(a, 3);
such that b2
represents the
data { 'a', 'b',
'c' }
.
Even if the size argument exceeds the actual size of the array, the size
of the buffer object created will be limited to the array size.
An offset may be applied to an existing buffer to create a new one:
b3 = b1 + 2;
where b3
will set to represent
{ 'c', 'd',
'e' }
.
If the offset exceeds the size of the existing buffer, the newly created
buffer will be empty.
Both an offset and size may be specified to create a buffer that corresponds to a specific range of bytes within an existing buffer:
b4 = boost::asio::buffer(b1 + 1, 3);
so that b4
will refer to
the bytes { 'b', 'c',
'd' }
.
To read or write using multiple buffers (i.e. scatter-gather I/O), multiple buffer objects may be assigned into a container that supports the MutableBufferSequence (for read) or ConstBufferSequence (for write) concepts:
char d1[128]; std::vector<char> d2(128); boost::array<char, 128> d3; boost::array<mutable_buffer, 3> bufs1 = { boost::asio::buffer(d1), boost::asio::buffer(d2), boost::asio::buffer(d3) }; bytes_transferred = sock.receive(bufs1); std::vector<const_buffer> bufs2; bufs2.push_back(boost::asio::buffer(d1)); bufs2.push_back(boost::asio::buffer(d2)); bufs2.push_back(boost::asio::buffer(d3)); bytes_transferred = sock.send(bufs2);
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 buffer( const mutable_buffer & b);
mutable_buffers_1(b)
.
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 buffer( const mutable_buffer & b, std::size_t max_size_in_bytes);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( buffer_cast<void*>(b), min(buffer_size(b), max_size_in_bytes));
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1 buffer( const const_buffer & b);
const_buffers_1(b)
.
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1 buffer( const const_buffer & b, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( buffer_cast<const void*>(b), min(buffer_size(b), max_size_in_bytes));
Create a new modifiable buffer that represents the given memory range.
mutable_buffers_1 buffer( void * data, std::size_t size_in_bytes);
mutable_buffers_1(data, size_in_bytes)
.
Create a new non-modifiable buffer that represents the given memory range.
const_buffers_1 buffer( const void * data, std::size_t size_in_bytes);
const_buffers_1(data, size_in_bytes)
.
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType (&data)[N]);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( static_cast<void*>(data), N * sizeof(PodType));
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType (&data)[N], std::size_t max_size_in_bytes);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( static_cast<void*>(data), min(N * sizeof(PodType), max_size_in_bytes));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType (&data)[N]);
A const_buffers_1
value equivalent to:
const_buffers_1( static_cast<const void*>(data), N * sizeof(PodType));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType (&data)[N], std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( static_cast<const void*>(data), min(N * sizeof(PodType), max_size_in_bytes));
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data, std::size_t max_size_in_bytes);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( std::array< PodType, N > & data);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> mutable_buffers_1 buffer( std::array< PodType, N > & data, std::size_t max_size_in_bytes);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( std::array< const PodType, N > & data);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( std::array< const PodType, N > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const std::array< PodType, N > & data);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), data.size() * sizeof(PodType));
Create a new non-modifiable buffer that represents the given POD array.
template< typename PodType, std::size_t N> const_buffers_1 buffer( const std::array< PodType, N > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), min(data.size() * sizeof(PodType), max_size_in_bytes));
Create a new modifiable buffer that represents the given POD vector.
template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.size() ? &data[0] : 0, data.size() * sizeof(PodType));
The buffer is invalidated by any vector operation that would also invalidate iterators.
Create a new modifiable buffer that represents the given POD vector.
template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes);
A mutable_buffers_1
value equivalent
to:
mutable_buffers_1( data.size() ? &data[0] : 0, min(data.size() * sizeof(PodType), max_size_in_bytes));
The buffer is invalidated by any vector operation that would also invalidate iterators.
Create a new non-modifiable buffer that represents the given POD vector.
template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data);
A const_buffers_1
value equivalent to:
const_buffers_1( data.size() ? &data[0] : 0, data.size() * sizeof(PodType));
The buffer is invalidated by any vector operation that would also invalidate iterators.
Create a new non-modifiable buffer that represents the given POD vector.
template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.size() ? &data[0] : 0, min(data.size() * sizeof(PodType), max_size_in_bytes));
The buffer is invalidated by any vector operation that would also invalidate iterators.
Create a new non-modifiable buffer that represents the given string.
template< typename Elem, typename Traits, typename Allocator> const_buffers_1 buffer( const std::basic_string< Elem, Traits, Allocator > & data);
const_buffers_1(data.data(), data.size() * sizeof(Elem))
.
The buffer is invalidated by any non-const operation called on the given string object.
Create a new non-modifiable buffer that represents the given string.
template< typename Elem, typename Traits, typename Allocator> const_buffers_1 buffer( const std::basic_string< Elem, Traits, Allocator > & data, std::size_t max_size_in_bytes);
A const_buffers_1
value equivalent to:
const_buffers_1( data.data(), min(data.size() * sizeof(Elem), max_size_in_bytes));
The buffer is invalidated by any non-const operation called on the given string object.
The boost::asio::buffer_cast
function is used to obtain
a pointer to the underlying memory region associated with a buffer.
template< typename PointerToPodType> PointerToPodType buffer_cast( const mutable_buffer & b); » more... template< typename PointerToPodType> PointerToPodType buffer_cast( const const_buffer & b); » more...
To access the memory of a non-modifiable buffer, use:
boost::asio::const_buffer b1 = ...; const unsigned char* p1 = boost::asio::buffer_cast<const unsigned char*>(b1);
To access the memory of a modifiable buffer, use:
boost::asio::mutable_buffer b2 = ...; unsigned char* p2 = boost::asio::buffer_cast<unsigned char*>(b2);
The boost::asio::buffer_cast
function permits violations
of type safety, so uses of it in application code should be carefully considered.
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Cast a non-modifiable buffer to a specified pointer to POD type.
template< typename PointerToPodType> PointerToPodType buffer_cast( const mutable_buffer & b);
Cast a non-modifiable buffer to a specified pointer to POD type.
template< typename PointerToPodType> PointerToPodType buffer_cast( const const_buffer & b);
The boost::asio::buffer_copy
function is used to copy bytes
from a source buffer (or buffer sequence) to a target buffer (or buffer sequence).
std::size_t buffer_copy( const mutable_buffer & target, const const_buffer & source); » more... std::size_t buffer_copy( const mutable_buffer & target, const const_buffers_1 & source); » more... std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffer & source); » more... std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffers_1 & source); » more... template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffer & target, const ConstBufferSequence & source); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffer & source); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffers_1 & source); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffer & source); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffers_1 & source); » more... template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffers_1 & target, const ConstBufferSequence & source); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffer & source); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffers_1 & source); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffer & source); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffers_1 & source); » more... template< typename MutableBufferSequence, typename ConstBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const ConstBufferSequence & source); » more... std::size_t buffer_copy( const mutable_buffer & target, const const_buffer & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffer & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffer & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy); » more... template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffer & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffer & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffer & source, std::size_t max_bytes_to_copy); » more... std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy); » more... template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffers_1 & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffer & source, std::size_t max_bytes_to_copy); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffer & source, std::size_t max_bytes_to_copy); » more... template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy); » more... template< typename MutableBufferSequence, typename ConstBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy); » more...
The buffer_copy
function
is available in two forms:
buffer_copy(target, source)
buffer_copy(target, source, max_bytes_to_copy)
Both forms return the number of bytes actually copied. The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
If
specified, max_bytes_to_copy
.
This prevents buffer overflow, regardless of the buffer sizes used in the copy operation.
Note that buffer_copy
is implemented in terms
of memcpy
, and consequently
it cannot be used to copy between overlapping memory regions.
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const const_buffer & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const const_buffers_1 & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffer & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffers_1 & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer sequence to a target buffer.
template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffer & target, const ConstBufferSequence & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffer & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffers_1 & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffer & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffers_1 & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer sequence to a target buffer.
template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffers_1 & target, const ConstBufferSequence & source);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffer & source);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffers_1 & source);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffer & source);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffers_1 & source);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies bytes from a source buffer sequence to a target buffer sequence.
template< typename MutableBufferSequence, typename ConstBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const ConstBufferSequence & source);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const const_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffer & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer sequence to a target buffer.
template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffer & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer.
std::size_t buffer_copy( const mutable_buffers_1 & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer sequence to a target buffer.
template< typename ConstBufferSequence> std::size_t buffer_copy( const mutable_buffers_1 & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy);
A modifiable buffer representing the memory region to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const const_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer representing the memory region from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffer & source, std::size_t max_bytes_to_copy);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer to a target buffer sequence.
template< typename MutableBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const mutable_buffers_1 & source, std::size_t max_bytes_to_copy);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A modifiable buffer representing the memory region from which the bytes will be copied. The contents of the source buffer will not be modified.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
Copies a limited number of bytes from a source buffer sequence to a target buffer sequence.
template< typename MutableBufferSequence, typename ConstBufferSequence> std::size_t buffer_copy( const MutableBufferSequence & target, const ConstBufferSequence & source, std::size_t max_bytes_to_copy);
A modifiable buffer sequence representing the memory regions to which the bytes will be copied.
A non-modifiable buffer sequence representing the memory regions from which the bytes will be copied.
The maximum number of bytes to be copied.
The number of bytes copied.
The number of bytes copied is the lesser of:
buffer_size(target)
buffer_size(source)
max_bytes_to_copy
This function is implemented in terms of memcpy
,
and consequently it cannot be used to copy between overlapping memory regions.
The boost::asio::buffer_size
function determines the total
number of bytes in a buffer or buffer sequence.
std::size_t buffer_size( const mutable_buffer & b); » more... std::size_t buffer_size( const mutable_buffers_1 & b); » more... std::size_t buffer_size( const const_buffer & b); » more... std::size_t buffer_size( const const_buffers_1 & b); » more... template< typename BufferSequence> std::size_t buffer_size( const BufferSequence & b); » more...
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Get the number of bytes in a modifiable buffer.
std::size_t buffer_size( const mutable_buffer & b);
Get the number of bytes in a modifiable buffer.
std::size_t buffer_size( const mutable_buffers_1 & b);
Get the number of bytes in a non-modifiable buffer.
std::size_t buffer_size( const const_buffer & b);
Get the number of bytes in a non-modifiable buffer.
std::size_t buffer_size( const const_buffers_1 & b);
Get the total number of bytes in a buffer sequence.
template< typename BufferSequence> std::size_t buffer_size( const BufferSequence & b);
The BufferSequence
template
parameter may meet either of the ConstBufferSequence
or MutableBufferSequence
type requirements.
Adds buffering to the read-related operations of a stream.
template< typename Stream> class buffered_read_stream : noncopyable
|
Name |
Description |
|---|---|
|
The type of the lowest layer. |
|
|
The type of the next layer. |
|
Name |
Description |
|---|---|
|
Start an asynchronous fill. |
|
|
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. |
|
|
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. |
|
|
Construct, passing the specified argument to initialise the next layer. |
|
|
Close the stream. |
|
|
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure. Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred. |
|
|
Get the io_service associated with the object. |
|
|
Determine the amount of data that may be read without blocking. |
|
|
Get a reference to the lowest layer. Get a const reference to the lowest layer. |
|
|
Get a reference to the next layer. |
|
|
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred. |
|
|
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. Read some data from the stream. Returns the number of bytes read or 0 if an error occurred. |
|
|
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred. |
|
Name |
Description |
|---|---|
|
The default buffer size. |
The buffered_read_stream
class template
can be used to add buffering to the synchronous and asynchronous read operations
of a stream.
Distinct objects: Safe.
Shared objects: Unsafe.
Header: boost/asio/buffered_read_stream.hpp
Convenience header: boost/asio.hpp
template< typename ReadHandler> void-or-deduced async_fill( ReadHandler handler);
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template< typename MutableBufferSequence, typename ReadHandler> void-or-deduced async_read_some( const MutableBufferSequence & buffers, ReadHandler handler);
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template< typename ConstBufferSequence, typename WriteHandler> void-or-deduced async_write_some( const ConstBufferSequence & buffers, WriteHandler handler);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> explicit buffered_read_stream( Arg & a); » more... template< typename Arg> buffered_read_stream( Arg & a, std::size_t buffer_size); » more...
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_read_stream( Arg & a);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_read_stream( Arg & a, std::size_t buffer_size);
void close(); » more... boost::system::error_code close( boost::system::error_code & ec); » more...
Close the stream.
boost::system::error_code close( boost::system::error_code & ec);
static const std::size_t default_buffer_size = implementation_defined;
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill(); » more...
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill( boost::system::error_code & ec); » more...
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill();
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill( boost::system::error_code & ec);
Get the io_service
associated with the
object.
boost::asio::io_service & get_io_service();
Determine the amount of data that may be read without blocking.
std::size_t in_avail(); » more... std::size_t in_avail( boost::system::error_code & ec); » more...
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
Determine the amount of data that may be read without blocking.
std::size_t in_avail( boost::system::error_code & ec);
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer(); » more...
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const; » more...
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const;
typedef next_layer_type::lowest_layer_type lowest_layer_type;
Header: boost/asio/buffered_read_stream.hpp
Convenience header: boost/asio.hpp
typedef remove_reference< Stream >::type next_layer_type;
Header: boost/asio/buffered_read_stream.hpp
Convenience header: boost/asio.hpp
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers); » more...
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers);
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers); » more...
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers);
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers); » more...
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec); » more...
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers);
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec);
Adds buffering to the read- and write-related operations of a stream.
template< typename Stream> class buffered_stream : noncopyable
|
Name |
Description |
|---|---|
|
The type of the lowest layer. |
|
|
The type of the next layer. |
|
Name |
Description |
|---|---|
|
Start an asynchronous fill. |
|
|
Start an asynchronous flush. |
|
|
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. |
|
|
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. |
|
|
Construct, passing the specified argument to initialise the next layer. |
|
|
Close the stream. |
|
|
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure. Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred. |
|
|
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure. Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred. |
|
|
Get the io_service associated with the object. |
|
|
Determine the amount of data that may be read without blocking. |
|
|
Get a reference to the lowest layer. Get a const reference to the lowest layer. |
|
|
Get a reference to the next layer. |
|
|
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred. |
|
|
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. Read some data from the stream. Returns the number of bytes read or 0 if an error occurred. |
|
|
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred. |
The buffered_stream
class template can be used to add buffering to the synchronous and asynchronous
read and write operations of a stream.
Distinct objects: Safe.
Shared objects: Unsafe.
Header: boost/asio/buffered_stream.hpp
Convenience header: boost/asio.hpp
template< typename ReadHandler> void-or-deduced async_fill( ReadHandler handler);
template< typename WriteHandler> void-or-deduced async_flush( WriteHandler handler);
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template< typename MutableBufferSequence, typename ReadHandler> void-or-deduced async_read_some( const MutableBufferSequence & buffers, ReadHandler handler);
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template< typename ConstBufferSequence, typename WriteHandler> void-or-deduced async_write_some( const ConstBufferSequence & buffers, WriteHandler handler);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> explicit buffered_stream( Arg & a); » more... template< typename Arg> explicit buffered_stream( Arg & a, std::size_t read_buffer_size, std::size_t write_buffer_size); » more...
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_stream( Arg & a);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_stream( Arg & a, std::size_t read_buffer_size, std::size_t write_buffer_size);
void close(); » more... boost::system::error_code close( boost::system::error_code & ec); » more...
Close the stream.
boost::system::error_code close( boost::system::error_code & ec);
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill(); » more...
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill( boost::system::error_code & ec); » more...
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill();
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill( boost::system::error_code & ec);
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush(); » more...
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush( boost::system::error_code & ec); » more...
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush();
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush( boost::system::error_code & ec);
Get the io_service
associated with the
object.
boost::asio::io_service & get_io_service();
Determine the amount of data that may be read without blocking.
std::size_t in_avail(); » more... std::size_t in_avail( boost::system::error_code & ec); » more...
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
Determine the amount of data that may be read without blocking.
std::size_t in_avail( boost::system::error_code & ec);
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer(); » more...
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const; » more...
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const;
typedef next_layer_type::lowest_layer_type lowest_layer_type;
Header: boost/asio/buffered_stream.hpp
Convenience header: boost/asio.hpp
typedef remove_reference< Stream >::type next_layer_type;
Header: boost/asio/buffered_stream.hpp
Convenience header: boost/asio.hpp
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers); » more...
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers);
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers); » more...
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers);
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers); » more...
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec); » more...
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers);
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec);
Adds buffering to the write-related operations of a stream.
template< typename Stream> class buffered_write_stream : noncopyable
|
Name |
Description |
|---|---|
|
The type of the lowest layer. |
|
|
The type of the next layer. |
|
Name |
Description |
|---|---|
|
Start an asynchronous flush. |
|
|
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. |
|
|
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. |
|
|
Construct, passing the specified argument to initialise the next layer. |
|
|
Close the stream. |
|
|
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure. Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred. |
|
|
Get the io_service associated with the object. |
|
|
Determine the amount of data that may be read without blocking. |
|
|
Get a reference to the lowest layer. Get a const reference to the lowest layer. |
|
|
Get a reference to the next layer. |
|
|
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred. |
|
|
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. Read some data from the stream. Returns the number of bytes read or 0 if an error occurred. |
|
|
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred and the error handler did not throw. |
|
Name |
Description |
|---|---|
|
The default buffer size. |
The buffered_write_stream
class template
can be used to add buffering to the synchronous and asynchronous write operations
of a stream.
Distinct objects: Safe.
Shared objects: Unsafe.
Header: boost/asio/buffered_write_stream.hpp
Convenience header: boost/asio.hpp
template< typename WriteHandler> void-or-deduced async_flush( WriteHandler handler);
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template< typename MutableBufferSequence, typename ReadHandler> void-or-deduced async_read_some( const MutableBufferSequence & buffers, ReadHandler handler);
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template< typename ConstBufferSequence, typename WriteHandler> void-or-deduced async_write_some( const ConstBufferSequence & buffers, WriteHandler handler);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> explicit buffered_write_stream( Arg & a); » more... template< typename Arg> buffered_write_stream( Arg & a, std::size_t buffer_size); » more...
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_write_stream( Arg & a);
Construct, passing the specified argument to initialise the next layer.
template< typename Arg> buffered_write_stream( Arg & a, std::size_t buffer_size);
void close(); » more... boost::system::error_code close( boost::system::error_code & ec); » more...
Close the stream.
boost::system::error_code close( boost::system::error_code & ec);
static const std::size_t default_buffer_size = implementation_defined;
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush(); » more...
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush( boost::system::error_code & ec); » more...
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush();
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush( boost::system::error_code & ec);
Get the io_service
associated with the
object.
boost::asio::io_service & get_io_service();
Determine the amount of data that may be read without blocking.
std::size_t in_avail(); » more... std::size_t in_avail( boost::system::error_code & ec); » more...
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
Determine the amount of data that may be read without blocking.
std::size_t in_avail( boost::system::error_code & ec);
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer(); » more...
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const; » more...
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
Get a const reference to the lowest layer.
const lowest_layer_type & lowest_layer() const;
typedef next_layer_type::lowest_layer_type lowest_layer_type;
Header: boost/asio/buffered_write_stream.hpp
Convenience header: boost/asio.hpp
typedef remove_reference< Stream >::type next_layer_type;
Header: boost/asio/buffered_write_stream.hpp
Convenience header: boost/asio.hpp
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers); » more...
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers);
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t peek( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers); » more...
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec); » more...
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers);
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template< typename MutableBufferSequence> std::size_t read_some( const MutableBufferSequence & buffers, boost::system::error_code & ec);
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers); » more...
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred and the error handler did not throw.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec); » more...
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers);
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred and the error handler did not throw.
template< typename ConstBufferSequence> std::size_t write_some( const ConstBufferSequence & buffers, boost::system::error_code & ec);
Construct an iterator representing the beginning of the buffers' data.
template< typename BufferSequence> buffers_iterator< BufferSequence > buffers_begin( const BufferSequence & buffers);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Construct an iterator representing the end of the buffers' data.
template< typename BufferSequence> buffers_iterator< BufferSequence > buffers_end( const BufferSequence & buffers);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
A random access iterator over the bytes in a buffer sequence.
template< typename BufferSequence, typename ByteType = char> class buffers_iterator
|
Name |
Description |
|---|---|
|
The type used for the distance between two iterators. |
|
|
The iterator category. |
|
|
The type of the result of applying operator->() to the iterator. |
|
|
The type of the result of applying operator*() to the iterator. |
|
|
The type of the value pointed to by the iterator. |
|
Name |
Description |
|---|---|
|
Construct an iterator representing the beginning of the buffers' data. |
|
|
Default constructor. Creates an iterator in an undefined state. |
|
|
Construct an iterator representing the end of the buffers' data. |
|
|
Dereference an iterator. |
|
|
Increment operator (prefix). Increment operator (postfix). |
|
|
Addition operator. |
|
|
Decrement operator (prefix). Decrement operator (postfix). |
|
|
Subtraction operator. |
|
|
Dereference an iterator. |
|
|
Access an individual element. |
|
Name |
Description |
|---|---|
|
Test two iterators for inequality. |
|
|
Addition operator. |
|
|
Subtraction operator. |
|
|
Compare two iterators. |
|
|
Compare two iterators. |
|
|
Test two iterators for equality. |
|
|
Compare two iterators. |
|
|
Compare two iterators. |
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Construct an iterator representing the beginning of the buffers' data.
static buffers_iterator begin( const BufferSequence & buffers);
The type used for the distance between two iterators.
typedef std::ptrdiff_t difference_type;
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Construct an iterator representing the end of the buffers' data.
static buffers_iterator end( const BufferSequence & buffers);
typedef std::random_access_iterator_tag iterator_category;
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Test two iterators for inequality.
friend bool operator!=( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
friend buffers_iterator operator+( const buffers_iterator & iter, std::ptrdiff_t difference); » more... friend buffers_iterator operator+( std::ptrdiff_t difference, const buffers_iterator & iter); » more...
Addition operator.
friend buffers_iterator operator+( const buffers_iterator & iter, std::ptrdiff_t difference);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Addition operator.
friend buffers_iterator operator+( std::ptrdiff_t difference, const buffers_iterator & iter);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
buffers_iterator & operator++(); » more...
Increment operator (postfix).
buffers_iterator operator++( int ); » more...
Increment operator (prefix).
buffers_iterator & operator++();
Increment operator (postfix).
buffers_iterator operator++( int );
buffers_iterator & operator+=( std::ptrdiff_t difference);
friend buffers_iterator operator-( const buffers_iterator & iter, std::ptrdiff_t difference); » more... friend std::ptrdiff_t operator-( const buffers_iterator & a, const buffers_iterator & b); » more...
Subtraction operator.
friend buffers_iterator operator-( const buffers_iterator & iter, std::ptrdiff_t difference);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Subtraction operator.
friend std::ptrdiff_t operator-( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
buffers_iterator & operator--(); » more...
Decrement operator (postfix).
buffers_iterator operator--( int ); » more...
Decrement operator (prefix).
buffers_iterator & operator--();
Decrement operator (postfix).
buffers_iterator operator--( int );
buffers_iterator & operator-=( std::ptrdiff_t difference);
friend bool operator<( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
friend bool operator<=( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Test two iterators for equality.
friend bool operator==( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
friend bool operator>( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
friend bool operator>=( const buffers_iterator & a, const buffers_iterator & b);
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
reference operator[]( std::ptrdiff_t difference) const;
The type of the result of applying operator->()
to the iterator.
typedef const_or_non_const_ByteType * pointer;
If the buffer sequence stores buffer objects that are convertible to mutable_buffer
,
this is a pointer to a non-const ByteType. Otherwise, a pointer to a const
ByteType.
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
The type of the result of applying operator*()
to the iterator.
typedef const_or_non_const_ByteType & reference;
If the buffer sequence stores buffer objects that are convertible to mutable_buffer
,
this is a reference to a non-const ByteType. Otherwise, a reference to
a const ByteType.
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
The type of the value pointed to by the iterator.
typedef ByteType value_type;
Header: boost/asio/buffers_iterator.hpp
Convenience header: boost/asio.hpp
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin); » more... template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, boost::system::error_code & ec); » more... template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end); » more... template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, boost::system::error_code & ec); » more... template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, ConnectCondition connect_condition); » more... template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, ConnectCondition connect_condition, boost::system::error_code & ec); » more... template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, ConnectCondition connect_condition); » more... template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, boost::system::error_code & ec); » more...
Header: boost/asio/connect.hpp
Convenience header: boost/asio.hpp
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
Thrown on failure. If the sequence is empty, the associated error_code
is boost::asio::error::not_found
.
Otherwise, contains the error from the last connection attempt.
This overload assumes that a default constructed object of type Iterator
represents the end of the sequence.
This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator
.
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::socket s(io_service); boost::asio::connect(s, r.resolve(q));
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, boost::system::error_code & ec);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
Set to indicate what error occurred, if any. If the sequence is empty,
set to boost::asio::error::not_found
. Otherwise, contains
the error from the last connection attempt.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
This overload assumes that a default constructed object of type Iterator
represents the end of the sequence.
This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator
.
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::socket s(io_service); boost::system::error_code ec; boost::asio::connect(s, r.resolve(q), ec); if (ec) { // An error occurred. }
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
Thrown on failure. If the sequence is empty, the associated error_code
is boost::asio::error::not_found
.
Otherwise, contains the error from the last connection attempt.
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::resolver::iterator i = r.resolve(q), end; tcp::socket s(io_service); boost::asio::connect(s, i, end);
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, boost::system::error_code & ec);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
Set to indicate what error occurred, if any. If the sequence is empty,
set to boost::asio::error::not_found
. Otherwise, contains
the error from the last connection attempt.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::resolver::iterator i = r.resolve(q), end; tcp::socket s(io_service); boost::system::error_code ec; boost::asio::connect(s, i, end, ec); if (ec) { // An error occurred. }
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, ConnectCondition connect_condition);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
A function object that is called prior to each connection attempt. The signature of the function object must be:
Iterator connect_condition( const boost::system::error_code& ec, Iterator next);
The ec
parameter
contains the result from the most recent connect operation. Before
the first connection attempt, ec
is always set to indicate success. The next
parameter is an iterator pointing to the next endpoint to be tried.
The function object should return the next iterator, but is permitted
to return a different iterator so that endpoints may be skipped.
The implementation guarantees that the function object will never
be called with the end iterator.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
Thrown on failure. If the sequence is empty, the associated error_code
is boost::asio::error::not_found
.
Otherwise, contains the error from the last connection attempt.
This overload assumes that a default constructed object of type Iterator
represents the end of the sequence.
This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator
.
The following connect condition function object can be used to output information about the individual connection attempts:
struct my_connect_condition { template <typename Iterator> Iterator operator()( const boost::system::error_code& ec, Iterator next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next->endpoint() << std::endl; return next; } };
It would be used with the boost::asio::connect
function as follows:
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::socket s(io_service); tcp::resolver::iterator i = boost::asio::connect( s, r.resolve(q), my_connect_condition()); std::cout << "Connected to: " << i->endpoint() << std::endl;
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, ConnectCondition connect_condition, boost::system::error_code & ec);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
A function object that is called prior to each connection attempt. The signature of the function object must be:
Iterator connect_condition( const boost::system::error_code& ec, Iterator next);
The ec
parameter
contains the result from the most recent connect operation. Before
the first connection attempt, ec
is always set to indicate success. The next
parameter is an iterator pointing to the next endpoint to be tried.
The function object should return the next iterator, but is permitted
to return a different iterator so that endpoints may be skipped.
The implementation guarantees that the function object will never
be called with the end iterator.
Set to indicate what error occurred, if any. If the sequence is empty,
set to boost::asio::error::not_found
. Otherwise, contains
the error from the last connection attempt.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
This overload assumes that a default constructed object of type Iterator
represents the end of the sequence.
This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator
.
The following connect condition function object can be used to output information about the individual connection attempts:
struct my_connect_condition { template <typename Iterator> Iterator operator()( const boost::system::error_code& ec, Iterator next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next->endpoint() << std::endl; return next; } };
It would be used with the boost::asio::connect
function as follows:
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::socket s(io_service); boost::system::error_code ec; tcp::resolver::iterator i = boost::asio::connect( s, r.resolve(q), my_connect_condition(), ec); if (ec) { // An error occurred. } else { std::cout << "Connected to: " << i->endpoint() << std::endl; }
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, ConnectCondition connect_condition);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
A function object that is called prior to each connection attempt. The signature of the function object must be:
Iterator connect_condition( const boost::system::error_code& ec, Iterator next);
The ec
parameter
contains the result from the most recent connect operation. Before
the first connection attempt, ec
is always set to indicate success. The next
parameter is an iterator pointing to the next endpoint to be tried.
The function object should return the next iterator, but is permitted
to return a different iterator so that endpoints may be skipped.
The implementation guarantees that the function object will never
be called with the end iterator.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
Thrown on failure. If the sequence is empty, the associated error_code
is boost::asio::error::not_found
.
Otherwise, contains the error from the last connection attempt.
The following connect condition function object can be used to output information about the individual connection attempts:
struct my_connect_condition { template <typename Iterator> Iterator operator()( const boost::system::error_code& ec, Iterator next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next->endpoint() << std::endl; return next; } };
It would be used with the boost::asio::connect
function as follows:
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::resolver::iterator i = r.resolve(q), end; tcp::socket s(io_service); i = boost::asio::connect(s, i, end, my_connect_condition()); std::cout << "Connected to: " << i->endpoint() << std::endl;
Establishes a socket connection by trying each endpoint in a sequence.
template< typename Protocol, typename SocketService, typename Iterator, typename ConnectCondition> Iterator connect( basic_socket< Protocol, SocketService > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, boost::system::error_code & ec);
This function attempts to connect a socket to one of a sequence of endpoints.
It does this by repeated calls to the socket's connect
member function, once for each endpoint in the sequence, until a connection
is successfully established.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
A function object that is called prior to each connection attempt. The signature of the function object must be:
Iterator connect_condition( const boost::system::error_code& ec, Iterator next);
The ec
parameter
contains the result from the most recent connect operation. Before
the first connection attempt, ec
is always set to indicate success. The next
parameter is an iterator pointing to the next endpoint to be tried.
The function object should return the next iterator, but is permitted
to return a different iterator so that endpoints may be skipped.
The implementation guarantees that the function object will never
be called with the end iterator.
Set to indicate what error occurred, if any. If the sequence is empty,
set to boost::asio::error::not_found
. Otherwise, contains
the error from the last connection attempt.
On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator.
The following connect condition function object can be used to output information about the individual connection attempts:
struct my_connect_condition { template <typename Iterator> Iterator operator()( const boost::system::error_code& ec, Iterator next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next->endpoint() << std::endl; return next; } };
It would be used with the boost::asio::connect
function as follows:
tcp::resolver r(io_service); tcp::resolver::query q("host", "service"); tcp::resolver::iterator i = r.resolve(q), end; tcp::socket s(io_service); boost::system::error_code ec; i = boost::asio::connect(s, i, end, my_connect_condition(), ec); if (ec) { // An error occurred. } else { std::cout << "Connected to: " << i->endpoint() << std::endl; }
Holds a buffer that cannot be modified.
class const_buffer
|
Name |
Description |
|---|---|
|
Construct an empty buffer. Construct a buffer to represent a given memory range. Construct a non-modifiable buffer from a modifiable one. |
|
Name |
Description |
|---|---|
|
Create a new non-modifiable buffer that is offset from the start of another. |
The const_buffer
class provides a safe representation of a buffer that cannot be modified.
It does not own the underlying data, and so is cheap to copy or assign.
The contents of a buffer may be accessed using the buffer_size
and buffer_cast
functions:
boost::asio::const_buffer b1 = ...; std::size_t s1 = boost::asio::buffer_size(b1); const unsigned char* p1 = boost::asio::buffer_cast<const unsigned char*>(b1);
The boost::asio::buffer_cast
function permits violations
of type safety, so uses of it in application code should be carefully considered.
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
const_buffer(); » more...
Construct a buffer to represent a given memory range.
const_buffer( const void * data, std::size_t size); » more...
Construct a non-modifiable buffer from a modifiable one.
const_buffer( const mutable_buffer & b); » more...
Construct a buffer to represent a given memory range.
const_buffer( const void * data, std::size_t size);
Construct a non-modifiable buffer from a modifiable one.
const_buffer( const mutable_buffer & b);
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( const const_buffer & b, std::size_t start); » more... const_buffer operator+( std::size_t start, const const_buffer & b); » more...
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( const const_buffer & b, std::size_t start);
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( std::size_t start, const const_buffer & b);
Adapts a single non-modifiable buffer so that it meets the requirements of the ConstBufferSequence concept.
class const_buffers_1 : public const_buffer
|
Name |
Description |
|---|---|
|
A random-access iterator type that may be used to read elements. |
|
|
The type for each element in the list of buffers. |
|
Name |
Description |
|---|---|
|
Get a random-access iterator to the first element. |
|
|
Construct to represent a given memory range. Construct to represent a single non-modifiable buffer. |
|
|
Get a random-access iterator for one past the last element. |
|
Name |
Description |
|---|---|
|
Create a new non-modifiable buffer that is offset from the start of another. |
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Construct to represent a given memory range.
const_buffers_1( const void * data, std::size_t size); » more...
Construct to represent a single non-modifiable buffer.
explicit const_buffers_1( const const_buffer & b); » more...
Construct to represent a given memory range.
const_buffers_1( const void * data, std::size_t size);
Construct to represent a single non-modifiable buffer.
const_buffers_1( const const_buffer & b);
A random-access iterator type that may be used to read elements.
typedef const const_buffer * const_iterator;
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( const const_buffer & b, std::size_t start); » more... const_buffer operator+( std::size_t start, const const_buffer & b); » more...
Inherited from const_buffer.
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( const const_buffer & b, std::size_t start);
Inherited from const_buffer.
Create a new non-modifiable buffer that is offset from the start of another.
const_buffer operator+( std::size_t start, const const_buffer & b);
The type for each element in the list of buffers.
typedef const_buffer value_type;
|
Name |
Description |
|---|---|
|
Construct an empty buffer. Construct a buffer to represent a given memory range. Construct a non-modifiable buffer from a modifiable one. |
|
Name |
Description |
|---|---|
|
Create a new non-modifiable buffer that is offset from the start of another. |
The const_buffer
class provides a safe representation of a buffer that cannot be modified.
It does not own the underlying data, and so is cheap to copy or assign.
The contents of a buffer may be accessed using the buffer_size
and buffer_cast
functions:
boost::asio::const_buffer b1 = ...; std::size_t s1 = boost::asio::buffer_size(b1); const unsigned char* p1 = boost::asio::buffer_cast<const unsigned char*>(b1);
The boost::asio::buffer_cast
function permits violations
of type safety, so uses of it in application code should be carefully considered.
Header: boost/asio/buffer.hpp
Convenience header: boost/asio.hpp
Provides support for implementing stackless coroutines.
class coroutine
|
Name |
Description |
|---|---|
|
Constructs a coroutine in its initial state. |
|
|
Returns true if the coroutine is the child of a fork. |
|
|
Returns true if the coroutine has reached its terminal state. |
|
|
Returns true if the coroutine is the parent of a fork. |
The coroutine
class may be
used to implement stackless coroutines. The class itself is used to store
the current state of the coroutine.
Coroutines are copy-constructible and assignable, and the space overhead is a single int. They can be used as a base class:
class session : coroutine { ... };
or as a data member:
class session { ... coroutine coro_; };
or even bound in as a function argument using lambdas or bind()
. The important thing is that as the application
maintains a copy of the object for as long as the coroutine must be kept
alive.
A coroutine is used in conjunction with certain "pseudo-keywords", which are implemented as macros. These macros are defined by a header file:
#include <boost/asio/yield.hpp>
and may conversely be undefined as follows:
#include <boost/asio/unyield.hpp>
reenter
The reenter
macro is used
to define the body of a coroutine. It takes a single argument: a pointer
or reference to a coroutine object. For example, if the base class is a coroutine
object you may write:
reenter (this) { ... coroutine body ... }
and if a data member or other variable you can write:
reenter (coro_) { ... coroutine body ... }
When reenter
is executed
at runtime, control jumps to the location of the last yield
or fork
.
The coroutine body may also be a single statement, such as:
reenter (this) for (;;) { ... }
Limitation: The reenter
macro is implemented using a switch. This means that you must take care when
using local variables within the coroutine body. The local variable is not
allowed in a position where reentering the coroutine could bypass the variable
definition.
yield statement
This form of the yield
keyword
is often used with asynchronous operations:
yield socket_->async_read_some(buffer(*buffer_), *this);
This divides into four logical steps:
yield
saves the current
state of the coroutine.
When the asynchronous operation completes, the function object is invoked
and reenter
causes control
to transfer to the resume point. It is important to remember to carry the
coroutine state forward with the asynchronous operation. In the above snippet,
the current class is a function object object with a coroutine object as
base class or data member.
The statement may also be a compound statement, and this permits us to define local variables with limited scope:
yield { mutable_buffers_1 b = buffer(*buffer_); socket_->async_read_some(b, *this); }
yield return expression ;
This form of yield
is often
used in generators or coroutine-based parsers. For example, the function
object:
struct interleave : coroutine { istream& is1; istream& is2; char operator()(char c) { reenter (this) for (;;) { yield return is1.get(); yield return is2.get(); } } };
defines a trivial coroutine that interleaves the characters from two input streams.
This type of yield
divides
into three logical steps:
yield
saves the current