mirror of
https://github.com/boostorg/asio.git
synced 2026-02-24 14:22:08 +00:00
Documentation updates.
[SVN r47503]
This commit is contained in:
Christopher Kohlhoff
@@ -24,14 +24,14 @@ install css
|
||||
|
||||
install images
|
||||
:
|
||||
design/proactor.png
|
||||
overview/proactor.png
|
||||
:
|
||||
<location>html/boost_asio
|
||||
;
|
||||
|
||||
local example-names = allocation buffers chat echo http/client http/server
|
||||
http/server2 http/server3 invocation iostreams multicast serialization
|
||||
services socks4 ssl timeouts timers ;
|
||||
http/server2 http/server3 invocation iostreams local multicast nonblocking
|
||||
porthopper serialization services socks4 ssl timeouts timers ;
|
||||
|
||||
for local l in $(example-names)
|
||||
{
|
||||
@@ -66,7 +66,7 @@ explicit asio_doc ;
|
||||
|
||||
install asio_doc_images
|
||||
:
|
||||
design/proactor.png
|
||||
overview/proactor.png
|
||||
:
|
||||
<location>$(BOOST_ROOT)/doc/html/boost_asio
|
||||
;
|
||||
|
||||
21
doc/asio.qbk
21
doc/asio.qbk
@@ -37,11 +37,19 @@
|
||||
|
||||
[/=============================================================================]
|
||||
|
||||
Boost.Asio is a cross-platform C++ library for network programming that
|
||||
provides developers with a consistent asynchronous I/O model using a modern C++
|
||||
approach.
|
||||
Boost.Asio is a cross-platform C++ library for network and low-level I/O
|
||||
programming that provides developers with a consistent asynchronous model using
|
||||
a modern C++ approach.
|
||||
|
||||
[variablelist
|
||||
[
|
||||
[
|
||||
[link boost_asio.overview Overview]
|
||||
]
|
||||
[
|
||||
An overview of the features included in Boost.Asio, plus rationale and design information.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.using Using Boost.Asio]
|
||||
@@ -80,16 +88,17 @@ approach.
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design Design]
|
||||
[link boost_asio.index Index]
|
||||
]
|
||||
[
|
||||
Rationale and design information for Boost.Asio.
|
||||
Book-style text index of Boost.Asio documentation.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[include overview.qbk]
|
||||
[include using.qbk]
|
||||
[include tutorial.qbk]
|
||||
[include examples.qbk]
|
||||
[include reference.qbk]
|
||||
[include design.qbk]
|
||||
[xinclude index.xml]
|
||||
|
||||
104
doc/design.qbk
104
doc/design.qbk
@@ -1,104 +0,0 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:design Design Notes]
|
||||
|
||||
[variablelist
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.rationale Rationale]
|
||||
]
|
||||
[
|
||||
Design rationale for the Boost.Asio library.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.async Asynchronous operations]
|
||||
]
|
||||
[
|
||||
Support for asynchronous operations in the Boost.Asio library is based on
|
||||
the Proactor pattern. This design note outlines the advantages and
|
||||
disadvantages of this approach.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.allocation Custom memory allocation]
|
||||
]
|
||||
[
|
||||
Describes the custom memory allocation support in Boost.Asio.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.buffers Buffers]
|
||||
]
|
||||
[
|
||||
Examines the buffer abstraction used by asio in order to support
|
||||
scatter-gather operations.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.eof Why EOF is an error]
|
||||
]
|
||||
[
|
||||
Discusses why the end-of-file condition should be an error code.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.line_based Line-based protocols]
|
||||
]
|
||||
[
|
||||
Outlines Boost.Asio's support for line-based protocols.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.threads Threads]
|
||||
]
|
||||
[
|
||||
An implementation of Boost.Asio for a particular platform may make use of
|
||||
one or more additional threads to emulate asynchronicity. This design
|
||||
note discusses design rules applied to the use of threads in this way.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.strands Strands]
|
||||
]
|
||||
[
|
||||
Describes the "strand" abstraction provided by Boost.Asio to ease
|
||||
concurrent programming and provide scalability across multiple
|
||||
processors.
|
||||
]
|
||||
]
|
||||
[
|
||||
[
|
||||
[link boost_asio.design.implementation Platform-specific implementation]
|
||||
]
|
||||
[
|
||||
This design note lists platform-specific implementation details, such as
|
||||
the default demultiplexing mechanism, the number of threads created
|
||||
internally, and when threads are created.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[include design/rationale.qbk]
|
||||
[include design/async.qbk]
|
||||
[include design/allocation.qbk]
|
||||
[include design/buffers.qbk]
|
||||
[include design/eof.qbk]
|
||||
[include design/line_based.qbk]
|
||||
[include design/threads.qbk]
|
||||
[include design/strands.qbk]
|
||||
[include design/implementation.qbk]
|
||||
|
||||
[endsect]
|
||||
@@ -1,58 +0,0 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:buffers Buffers]
|
||||
|
||||
To allow the development of efficient network applications, Boost.Asio includes
|
||||
support for scatter-gather operations. These operations involve one or more
|
||||
buffers (where each buffer is a contiguous region of memory):
|
||||
|
||||
* A scatter-read receives data into multiple buffers.
|
||||
* A gather-write transmits multiple buffers.
|
||||
|
||||
Therefore we require an abstraction to represent a collection of buffers. The
|
||||
approach used in Boost.Asio is to define a type (actually two types) to
|
||||
represent a single buffer. These can be stored in a container, which may be
|
||||
passed to the scatter-gather operations.
|
||||
|
||||
A buffer, as a contiguous region of memory, can be represented by an address
|
||||
and size in bytes. There is a distinction between modifiable memory (called
|
||||
mutable in Boost.Asio) and non-modifiable memory (where the latter is
|
||||
created from the storage for a const-qualified variable). These two types could
|
||||
therefore be defined as follows:
|
||||
|
||||
typedef std::pair<void*, std::size_t> mutable_buffer;
|
||||
typedef std::pair<const void*, std::size_t> const_buffer;
|
||||
|
||||
Here, a mutable_buffer would be convertible to a const_buffer, but conversion
|
||||
in the opposite direction is not valid.
|
||||
|
||||
However, Boost.Asio does not use the above definitions, but instead defines two
|
||||
classes: `mutable_buffer` and `const_buffer`. The goal of these is to provide
|
||||
an opaque representation of contiguous memory, where:
|
||||
|
||||
* Types behave as std::pair would in conversions. That is, a `mutable_buffer` is
|
||||
convertible to a `const_buffer`, but the opposite conversion is disallowed.
|
||||
|
||||
* There is protection against buffer overruns. Given a buffer instance, a user
|
||||
can only create another buffer representing the same range of memory or a
|
||||
sub-range of it. To provide further safety, the library also includes
|
||||
mechanisms for automatically determining the size of a buffer from an array,
|
||||
`boost::array` or `std::vector` of POD elements, or from a `std::string`.
|
||||
|
||||
* Type safety violations must be explicitly requested using the `buffer_cast`
|
||||
function. In general an application should never need to do this, but it is
|
||||
required by the library implementation to pass the raw memory to the
|
||||
underlying operating system functions.
|
||||
|
||||
Finally, multiple buffers can be passed to scatter-gather operations (such as
|
||||
`boost::asio::read` or `boost::asio::write`) by putting the buffer objects
|
||||
into a container. The `MutableBufferSequence` and `ConstBufferSequence`
|
||||
concepts have been defined so that containers such as `std::vector`,
|
||||
`std::list`, `std::vector` or `boost::array` can be used.
|
||||
|
||||
[endsect]
|
||||
@@ -1,17 +0,0 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:eof Why EOF is an error]
|
||||
|
||||
* The end of a stream can cause `read`, `async_read`, `read_until` or
|
||||
`async_read_until` functions to violate their contract. E.g.
|
||||
a read of N bytes may finish early due to EOF.
|
||||
|
||||
* An EOF error may be used to distinguish the end of a stream from a successful
|
||||
read of size 0.
|
||||
|
||||
[endsect]
|
||||
@@ -1,50 +0,0 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:line_based Line-Based Protocols]
|
||||
|
||||
Many commonly-used internet protocols are line-based, which means that they
|
||||
have protocol elements that are delimited by the character sequence `"\r\n"`.
|
||||
Examples include HTTP, SMTP and FTP.
|
||||
|
||||
To more easily permit the implementation of line-based protocols, as well as
|
||||
other protocols that use delimiters, Boost.Asio includes the functions
|
||||
`read_until()` and `async_read_until()`.
|
||||
|
||||
The following example illustrates the use of `async_read_until()` in an HTTP
|
||||
server, to receive the first line of an HTTP request from a client:
|
||||
|
||||
class http_connection
|
||||
{
|
||||
...
|
||||
|
||||
void start()
|
||||
{
|
||||
asio::async_read_until(socket_, data_, "\r\n",
|
||||
boost::bind(&http_connection::handle_request_line, this, _1));
|
||||
}
|
||||
|
||||
void handle_request_line(boost::system::error_code ec)
|
||||
{
|
||||
if (!ec)
|
||||
{
|
||||
std::string method, uri, version;
|
||||
char sp1, sp2, cr, lf;
|
||||
std::istream is(&data_);
|
||||
is.unsetf(std::ios_base::skipws);
|
||||
is >> method >> sp1 >> uri >> sp2 >> version >> cr >> lf;
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
...
|
||||
|
||||
asio::ip::tcp::socket socket_;
|
||||
asio::streambuf data_;
|
||||
};
|
||||
|
||||
[endsect]
|
||||
@@ -1,44 +0,0 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:rationale Rationale]
|
||||
|
||||
The Boost.Asio library is intended for programmers using C++ for systems
|
||||
programming, where access to operating system functionality such as networking
|
||||
is often required. In particular, Boost.Asio attempts to address the following
|
||||
goals:
|
||||
|
||||
* [*Portability.] The library should support, and provide consistent behaviour
|
||||
across, a range of commonly used operating systems.
|
||||
|
||||
* [*Scalability.] The library should allow, and indeed encourage, the
|
||||
development of network applications that scale to hundreds or thousands of
|
||||
concurrent connections. The library implementation for each operating system
|
||||
should use the mechanism that best enables this scalability.
|
||||
|
||||
* [*Efficiency.] The library should support techniques such as scatter-gather
|
||||
I/O, and allow protocol implementations that minimise data copying.
|
||||
|
||||
* [*Model Berkeley sockets.] The Berkeley sockets API is widely implemented and
|
||||
understood, as well as being covered in much literature. Other programming
|
||||
languages often use a similar interface for networking APIs.
|
||||
|
||||
* [*Ease of use.] Lower the entry barrier for new users by taking a toolkit,
|
||||
rather than framework, approach. That is, try to minimise the up-front
|
||||
investment in time to just learning a few basic rules and guidelines. After
|
||||
that, a library user should only need to understand the specific functions that
|
||||
are being used.
|
||||
|
||||
* [*Basis for further abstraction.] The library should permit the development
|
||||
of other libraries that provide higher levels of abstraction. For example,
|
||||
implementations of commonly used protocols such as HTTP.
|
||||
|
||||
Although the current incarnation of Boost.Asio focuses primarily on networking,
|
||||
its concepts of asynchronous I/O can be extended to include other operating
|
||||
system resources such as files.
|
||||
|
||||
[endsect]
|
||||
@@ -219,4 +219,31 @@ Examples showing how to customise deadline_timer using different time types.
|
||||
* [@boost_asio/example/timers/time_t_timer.cpp]
|
||||
|
||||
|
||||
[heading Porthopper]
|
||||
|
||||
Example illustrating mixed synchronous and asynchronous operations, and how to
|
||||
use Boost.Lambda with Boost.Asio.
|
||||
|
||||
* [@boost_asio/example/porthopper/protocol.hpp]
|
||||
* [@boost_asio/example/porthopper/client.cpp]
|
||||
* [@boost_asio/example/porthopper/server.cpp]
|
||||
|
||||
|
||||
[heading Nonblocking]
|
||||
|
||||
Example demonstrating reactor-style operations for integrating a third-party
|
||||
library that wants to perform the I/O operations itself.
|
||||
|
||||
* [@boost_asio/example/nonblocking/third_party_lib.cpp]
|
||||
|
||||
|
||||
[heading UNIX Domain Sockets]
|
||||
|
||||
Examples showing how to use UNIX domain (local) sockets.
|
||||
|
||||
* [@boost_asio/example/local/connect_pair.cpp]
|
||||
* [@boost_asio/example/local/stream_server.cpp]
|
||||
* [@boost_asio/example/local/stream_client.cpp]
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
13
doc/index.xml
Normal file
13
doc/index.xml
Normal file
@@ -0,0 +1,13 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../tools/boostbook/dtd/boostbook.dtd">
|
||||
|
||||
<!--
|
||||
Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
-->
|
||||
|
||||
<section id="boost_asio.index">
|
||||
<index/>
|
||||
</section>
|
||||
81
doc/overview.qbk
Normal file
81
doc/overview.qbk
Normal file
@@ -0,0 +1,81 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:overview Overview]
|
||||
|
||||
* [link boost_asio.overview.rationale Rationale]
|
||||
* [link boost_asio.overview.core Core Concepts and Functionality]
|
||||
* [link boost_asio.overview.core.async The Proactor Design Pattern: Concurrency Without Threads]
|
||||
* [link boost_asio.overview.core.threads Threads and Boost.Asio]
|
||||
* [link boost_asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
|
||||
* [link boost_asio.overview.core.buffers Buffers]
|
||||
* [link boost_asio.overview.core.streams Streams, Short Reads and Short Writes]
|
||||
* [link boost_asio.overview.core.reactor Reactor-Style Operations]
|
||||
* [link boost_asio.overview.core.line_based Line-Based Operations]
|
||||
* [link boost_asio.overview.core.allocation Custom Memory Allocation]
|
||||
* [link boost_asio.overview.networking Networking]
|
||||
* [link boost_asio.overview.networking.iostreams Socket Iostreams]
|
||||
* [link boost_asio.overview.networking.bsd_sockets The BSD Socket API and Boost.Asio]
|
||||
[/ * IPv4 and IPv6 independence
|
||||
* TCP
|
||||
* UDP
|
||||
* Multicast
|
||||
* Raw sockets
|
||||
* ICMP ]
|
||||
* [link boost_asio.overview.timers Timers]
|
||||
* [link boost_asio.overview.serial_ports Serial Ports]
|
||||
* [link boost_asio.overview.posix POSIX-Specific Functionality]
|
||||
* [link boost_asio.overview.posix.local UNIX Domain Sockets]
|
||||
* [link boost_asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors]
|
||||
* [link boost_asio.overview.windows Windows-Specific Functionality]
|
||||
* [link boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
|
||||
* [link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs]
|
||||
* [link boost_asio.overview.ssl SSL]
|
||||
* [link boost_asio.overview.implementation Platform-Specific Implementation Notes]
|
||||
|
||||
[include overview/rationale.qbk]
|
||||
|
||||
[section:core Core Concepts and Functionality]
|
||||
|
||||
* [link boost_asio.overview.core.async The Proactor Design Pattern: Concurrency Without Threads]
|
||||
* [link boost_asio.overview.core.threads Threads and Boost.Asio]
|
||||
* [link boost_asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
|
||||
* [link boost_asio.overview.core.buffers Buffers]
|
||||
* [link boost_asio.overview.core.streams Streams, Short Reads and Short Writes]
|
||||
* [link boost_asio.overview.core.reactor Reactor-Style Operations]
|
||||
* [link boost_asio.overview.core.line_based Line-Based Operations]
|
||||
* [link boost_asio.overview.core.allocation Custom Memory Allocation]
|
||||
|
||||
[include overview/async.qbk]
|
||||
[include overview/threads.qbk]
|
||||
[include overview/strands.qbk]
|
||||
[include overview/buffers.qbk]
|
||||
[include overview/streams.qbk]
|
||||
[include overview/reactor.qbk]
|
||||
[include overview/line_based.qbk]
|
||||
[include overview/allocation.qbk]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:networking Networking]
|
||||
|
||||
* [link boost_asio.overview.networking.iostreams Socket Iostreams]
|
||||
* [link boost_asio.overview.networking.bsd_sockets The BSD Socket API and Boost.Asio]
|
||||
|
||||
[include overview/iostreams.qbk]
|
||||
[include overview/bsd_sockets.qbk]
|
||||
|
||||
[endsect]
|
||||
|
||||
[include overview/timers.qbk]
|
||||
[include overview/serial_ports.qbk]
|
||||
[include overview/posix.qbk]
|
||||
[include overview/windows.qbk]
|
||||
[include overview/ssl.qbk]
|
||||
[include overview/implementation.qbk]
|
||||
|
||||
[endsect]
|
||||
@@ -48,4 +48,20 @@ The implementation will insert appropriate memory barriers to ensure correct
|
||||
memory visibility should allocation functions need to be called from different
|
||||
threads.
|
||||
|
||||
Custom memory allocation support is currently implemented for all asynchronous
|
||||
operations with the following exceptions:
|
||||
|
||||
* `ip::basic_resolver::async_resolve()` on all platforms.
|
||||
|
||||
* `basic_socket::async_connect()` on Windows.
|
||||
|
||||
* Any operation involving `null_buffers()` on Windows, other than an
|
||||
asynchronous read performed on a stream-oriented socket.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.asio_handler_allocate asio_handler_allocate],
|
||||
[link boost_asio.reference.asio_handler_deallocate asio_handler_deallocate],
|
||||
[link boost_asio.examples.allocation custom memory allocation example].
|
||||
|
||||
[endsect]
|
||||
@@ -5,13 +5,13 @@
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:async Asynchronous Operations]
|
||||
[section:async The Proactor Design Pattern: Concurrency Without Threads]
|
||||
|
||||
The proposed library offers side-by-side support for synchronous and
|
||||
asynchronous operations. The asynchronous support is based on the Proactor
|
||||
design pattern [link boost_asio.design.async.references \[POSA2\]], and the
|
||||
advantages and disadvantages of this approach, when compared to a
|
||||
synchronous-only or Reactor approach, are outlined below.
|
||||
The Boost.Asio library offers side-by-side support for synchronous and asynchronous
|
||||
operations. The asynchronous support is based on the Proactor design pattern
|
||||
[link boost_asio.overview.core.async.references \[POSA2\]]. The advantages and
|
||||
disadvantages of this approach, when compared to a synchronous-only or Reactor
|
||||
approach, are outlined below.
|
||||
|
||||
[heading Proactor and Boost.Asio]
|
||||
|
||||
@@ -31,7 +31,7 @@ read or write on a socket.]
|
||||
|
||||
[:Executes asynchronous operations and queues events on a completion event
|
||||
queue when operations complete. From a high-level point of view, services like
|
||||
asio::stream_socket_service are asynchronous operation processors.]
|
||||
`stream_socket_service` are asynchronous operation processors.]
|
||||
|
||||
[mdash] Completion Event Queue
|
||||
|
||||
@@ -52,14 +52,14 @@ a completed event to its caller.]
|
||||
|
||||
[:Calls the asynchronous event demultiplexer to dequeue events, and dispatches
|
||||
the completion handler (i.e. invokes the function object) associated with the
|
||||
event. This abstraction is represented by `boost::asio::io_service`.]
|
||||
event. This abstraction is represented by the `io_service` class.]
|
||||
|
||||
[mdash] Initiator
|
||||
|
||||
[:Application-specific code that starts asynchronous operations. The initiator
|
||||
interacts with an asynchronous operation processor via a high-level interface
|
||||
such as `asio::basic_stream_socket`, which in turn delegates to a service like
|
||||
`asio::stream_socket_service`.]
|
||||
such as `basic_stream_socket`, which in turn delegates to a service like
|
||||
`stream_socket_service`.]
|
||||
|
||||
[heading Implementation Using Reactor]
|
||||
|
||||
@@ -97,7 +97,7 @@ calling an overlapped function such as `AcceptEx`.]
|
||||
[mdash] Completion Event Queue
|
||||
|
||||
[:This is implemented by the operating system, and is associated with an I/O
|
||||
completion port. There is one I/O completion port for each asio::io_service
|
||||
completion port. There is one I/O completion port for each `io_service`
|
||||
instance.]
|
||||
|
||||
[mdash] Asynchronous Event Demultiplexer
|
||||
@@ -111,9 +111,9 @@ handlers.]
|
||||
|
||||
[:Many operating systems offer a native asynchronous I/O API (such as
|
||||
overlapped I/O on __Windows__) as the preferred option for developing high
|
||||
performance network applications. The proposed library may be implemented in
|
||||
terms of native asynchronous I/O. However, if native support is not available,
|
||||
the library may also be implemented using synchronous event demultiplexors that
|
||||
performance network applications. The library may be implemented in terms of
|
||||
native asynchronous I/O. However, if native support is not available, the
|
||||
library may also be implemented using synchronous event demultiplexors that
|
||||
typify the Reactor pattern, such as __POSIX__ `select()`.]
|
||||
|
||||
[mdash] Decoupling threading from concurrency.
|
||||
270
doc/overview/bsd_sockets.qbk
Normal file
270
doc/overview/bsd_sockets.qbk
Normal file
@@ -0,0 +1,270 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:bsd_sockets The BSD Socket API and Boost.Asio]
|
||||
|
||||
The Boost.Asio library includes a low-level socket interface based on the BSD socket
|
||||
API, which is widely implemented and supported by extensive literature. It is
|
||||
also used as the basis for networking APIs in other languages, like Java. This
|
||||
low-level interface is designed to support the development of efficient and
|
||||
scalable applications. For example, it permits programmers to exert finer
|
||||
control over the number of system calls, avoid redundant data copying, minimise
|
||||
the use of resources like threads, and so on.
|
||||
|
||||
Unsafe and error prone aspects of the BSD socket API not included. For example,
|
||||
the use of `int` to represent all sockets lacks type safety. The socket
|
||||
representation in Boost.Asio uses a distinct type for each protocol, e.g. for TCP one
|
||||
would use `ip::tcp::socket`, and for UDP one uses `ip::udp::socket`.
|
||||
|
||||
The following table shows the mapping between the BSD socket API and Boost.Asio:
|
||||
|
||||
[table
|
||||
[
|
||||
[BSD Socket API Elements]
|
||||
[Equivalents in Boost.Asio]
|
||||
]
|
||||
[
|
||||
[socket descriptor - `int` (POSIX) or `SOCKET` (Windows)]
|
||||
[ For TCP: [link boost_asio.reference.ip__tcp.socket ip::tcp::socket],
|
||||
[link boost_asio.reference.ip__tcp.acceptor ip::tcp::acceptor]
|
||||
|
||||
For UDP: [link boost_asio.reference.ip__udp.socket ip::udp::socket]
|
||||
|
||||
[link boost_asio.reference.basic_socket basic_socket],
|
||||
[link boost_asio.reference.basic_stream_socket basic_stream_socket],
|
||||
[link boost_asio.reference.basic_datagram_socket basic_datagram_socket],
|
||||
[link boost_asio.reference.basic_raw_socket basic_raw_socket] ]
|
||||
]
|
||||
[
|
||||
[`in_addr`,
|
||||
`in6_addr`]
|
||||
[ [link boost_asio.reference.ip__address ip::address],
|
||||
[link boost_asio.reference.ip__address ip::address_v4],
|
||||
[link boost_asio.reference.ip__address ip::address_v6] ]
|
||||
]
|
||||
[
|
||||
[`sockaddr_in`,
|
||||
`sockaddr_in6`]
|
||||
[ For TCP: [link boost_asio.reference.ip__tcp.endpoint ip::tcp::endpoint]
|
||||
|
||||
For UDP: [link boost_asio.reference.ip__udp.endpoint ip::udp::endpoint]
|
||||
|
||||
[link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] ]
|
||||
]
|
||||
[
|
||||
[`accept()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket_acceptor.accept ip::tcp::acceptor::accept()]
|
||||
|
||||
[link boost_asio.reference.basic_socket_acceptor.accept basic_socket_acceptor::accept()] ]
|
||||
]
|
||||
[
|
||||
[`bind()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.bind ip::tcp::acceptor::bind()],
|
||||
[link boost_asio.reference.basic_socket.bind ip::tcp::socket::bind()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.bind ip::udp::socket::bind()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.bind basic_socket::bind()] ]
|
||||
]
|
||||
[
|
||||
[`close()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.close ip::tcp::acceptor::close()],
|
||||
[link boost_asio.reference.basic_socket.close ip::tcp::socket::close()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.close ip::udp::socket::close()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.close basic_socket::close()] ]
|
||||
]
|
||||
[
|
||||
[`connect()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.connect ip::tcp::socket::connect()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.connect ip::udp::socket::connect()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.connect basic_socket::connect()] ]
|
||||
]
|
||||
[
|
||||
[`getaddrinfo()`,
|
||||
`gethostbyaddr()`,
|
||||
`gethostbyname()`,
|
||||
`getnameinfo()`,
|
||||
`getservbyname()`,
|
||||
`getservbyport()`]
|
||||
[ For TCP: [link boost_asio.reference.ip__basic_resolver.resolve ip::tcp::resolver::resolve()],
|
||||
[link boost_asio.reference.ip__basic_resolver.async_resolve ip::tcp::resolver::async_resolve()]
|
||||
|
||||
For UDP: [link boost_asio.reference.ip__basic_resolver.resolve ip::udp::resolver::resolve()],
|
||||
[link boost_asio.reference.ip__basic_resolver.async_resolve ip::udp::resolver::async_resolve()]
|
||||
|
||||
[link boost_asio.reference.ip__basic_resolver.resolve ip::basic_resolver::resolve()],
|
||||
[link boost_asio.reference.ip__basic_resolver.async_resolve ip::basic_resolver::async_resolve()] ]
|
||||
]
|
||||
[
|
||||
[`gethostname()`]
|
||||
[ [link boost_asio.reference.ip__host_name ip::host_name()] ]
|
||||
]
|
||||
[
|
||||
[`getpeername()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.remote_endpoint ip::tcp::socket::remote_endpoint()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.remote_endpoint ip::udp::socket::remote_endpoint()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.remote_endpoint basic_socket::remote_endpoint()] ]
|
||||
]
|
||||
[
|
||||
[`getsockname()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.local_endpoint ip::tcp::acceptor::local_endpoint()],
|
||||
[link boost_asio.reference.basic_socket.local_endpoint ip::tcp::socket::local_endpoint()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.local_endpoint ip::udp::socket::local_endpoint()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.local_endpoint basic_socket::local_endpoint()] ]
|
||||
]
|
||||
[
|
||||
[`getsockopt()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.get_option ip::tcp::acceptor::get_option()],
|
||||
[link boost_asio.reference.basic_socket.get_option ip::tcp::socket::get_option()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.get_option ip::udp::socket::get_option()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.get_option basic_socket::get_option()] ]
|
||||
]
|
||||
[
|
||||
[`inet_addr()`,
|
||||
`inet_aton()`,
|
||||
`inet_pton()`]
|
||||
[ [link boost_asio.reference.ip__address.from_string ip::address::from_string()],
|
||||
[link boost_asio.reference.ip__address.from_string ip::address_v4::from_string()],
|
||||
[link boost_asio.reference.ip__address.from_string ip_address_v6::from_string()] ]
|
||||
]
|
||||
[
|
||||
[`inet_ntoa()`,
|
||||
`inet_ntop()`]
|
||||
[ [link boost_asio.reference.ip__address.to_string ip::address::to_string()],
|
||||
[link boost_asio.reference.ip__address.to_string ip::address_v4::to_string()],
|
||||
[link boost_asio.reference.ip__address.to_string ip_address_v6::to_string()] ]
|
||||
]
|
||||
[
|
||||
[`ioctl()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.io_control ip::tcp::socket::io_control()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.io_control ip::udp::socket::io_control()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.io_control basic_socket::io_control()] ]
|
||||
]
|
||||
[
|
||||
[`listen()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket_acceptor.listen ip::tcp::acceptor::listen()]
|
||||
|
||||
[link boost_asio.reference.basic_socket_acceptor.listen basic_socket_acceptor::listen()] ]
|
||||
]
|
||||
[
|
||||
[`poll()`,
|
||||
`select()`,
|
||||
`pselect()`]
|
||||
[ [link boost_asio.reference.io_service.run io_service::run()],
|
||||
[link boost_asio.reference.io_service.run_one io_service::run_one()],
|
||||
[link boost_asio.reference.io_service.poll io_service::poll()],
|
||||
[link boost_asio.reference.io_service.poll_one io_service::poll_one()]
|
||||
|
||||
Note: in conjunction with asynchronous operations. ]
|
||||
]
|
||||
[
|
||||
[`readv()`,
|
||||
`recv()`,
|
||||
`read()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_stream_socket.read_some ip::tcp::socket::read_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_read_some ip::tcp::socket::async_read_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.receive ip::tcp::socket::receive()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_receive ip::tcp::socket::async_receive()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_datagram_socket.receive ip::udp::socket::receive()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_receive ip::udp::socket::async_receive()]
|
||||
|
||||
[link boost_asio.reference.basic_stream_socket.read_some basic_stream_socket::read_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_read_some basic_stream_socket::async_read_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.receive basic_stream_socket::receive()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_receive basic_stream_socket::async_receive()],
|
||||
[link boost_asio.reference.basic_datagram_socket.receive basic_datagram_socket::receive()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_receive basic_datagram_socket::async_receive()] ]
|
||||
]
|
||||
[
|
||||
[`recvfrom()`]
|
||||
[ For UDP: [link boost_asio.reference.basic_datagram_socket.receive_from ip::udp::socket::receive_from()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_receive_from ip::udp::socket::async_receive_from()]
|
||||
|
||||
[link boost_asio.reference.basic_datagram_socket.receive_from basic_datagram_socket::receive_from()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_receive_from basic_datagram_socket::async_receive_from()] ]
|
||||
]
|
||||
[
|
||||
[`send()`,
|
||||
`write()`,
|
||||
`writev()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_stream_socket.write_some ip::tcp::socket::write_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_write_some ip::tcp::socket::async_write_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.send ip::tcp::socket::send()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_send ip::tcp::socket::async_send()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_datagram_socket.send ip::udp::socket::send()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_send ip::udp::socket::async_send()]
|
||||
|
||||
[link boost_asio.reference.basic_stream_socket.write_some basic_stream_socket::write_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_write_some basic_stream_socket::async_write_some()],
|
||||
[link boost_asio.reference.basic_stream_socket.send basic_stream_socket::send()],
|
||||
[link boost_asio.reference.basic_stream_socket.async_send basic_stream_socket::async_send()],
|
||||
[link boost_asio.reference.basic_datagram_socket.send basic_datagram_socket::send()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_send basic_datagram_socket::async_send()] ]
|
||||
]
|
||||
[
|
||||
[`sendto()`]
|
||||
[ For UDP: [link boost_asio.reference.basic_datagram_socket.send_to ip::udp::socket::send_to()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_send_to ip::udp::socket::async_send_to()]
|
||||
|
||||
[link boost_asio.reference.basic_datagram_socket.send_to basic_datagram_socket::send_to()],
|
||||
[link boost_asio.reference.basic_datagram_socket.async_send_to basic_datagram_socket::async_send_to()] ]
|
||||
]
|
||||
[
|
||||
[`setsockopt()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.set_option ip::tcp::acceptor::set_option()],
|
||||
[link boost_asio.reference.basic_socket.set_option ip::tcp::socket::set_option()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.set_option ip::udp::socket::set_option()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.set_option basic_socket::set_option()] ]
|
||||
]
|
||||
[
|
||||
[`shutdown()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.shutdown ip::tcp::socket::shutdown()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.shutdown ip::udp::socket::shutdown()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.shutdown basic_socket::shutdown()] ]
|
||||
]
|
||||
[
|
||||
[`sockatmark()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.at_mark ip::tcp::socket::at_mark()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.at_mark basic_socket::at_mark()] ]
|
||||
]
|
||||
[
|
||||
[`socket()`]
|
||||
[ For TCP: [link boost_asio.reference.basic_socket.open ip::tcp::acceptor::open()],
|
||||
[link boost_asio.reference.basic_socket.open ip::tcp::socket::open()]
|
||||
|
||||
For UDP: [link boost_asio.reference.basic_socket.open ip::udp::socket::open()]
|
||||
|
||||
[link boost_asio.reference.basic_socket.open basic_socket::open()] ]
|
||||
]
|
||||
[
|
||||
[`socketpair()`]
|
||||
[ [link boost_asio.reference.local__connect_pair local::connect_pair()]
|
||||
|
||||
Note: POSIX operating systems only. ]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
162
doc/overview/buffers.qbk
Normal file
162
doc/overview/buffers.qbk
Normal file
@@ -0,0 +1,162 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:buffers Buffers]
|
||||
|
||||
Fundamentally, I/O involves the transfer of data to and from contiguous regions
|
||||
of memory, called buffers. These buffers can be simply expressed as a tuple
|
||||
consisting of a pointer and a size in bytes. However, to allow the development
|
||||
of efficient network applications, Boost.Asio includes support for scatter-gather
|
||||
operations. These operations involve one or more buffers:
|
||||
|
||||
* A scatter-read receives data into multiple buffers.
|
||||
* A gather-write transmits multiple buffers.
|
||||
|
||||
Therefore we require an abstraction to represent a collection of buffers. The
|
||||
approach used in Boost.Asio is to define a type (actually two types) to
|
||||
represent a single buffer. These can be stored in a container, which may be
|
||||
passed to the scatter-gather operations.
|
||||
|
||||
In addition to specifying buffers as a pointer and size in bytes, Boost.Asio makes a
|
||||
distinction between modifiable memory (called mutable) and non-modifiable
|
||||
memory (where the latter is created from the storage for a const-qualified
|
||||
variable). These two types could therefore be defined as follows:
|
||||
|
||||
typedef std::pair<void*, std::size_t> mutable_buffer;
|
||||
typedef std::pair<const void*, std::size_t> const_buffer;
|
||||
|
||||
Here, a mutable_buffer would be convertible to a const_buffer, but conversion
|
||||
in the opposite direction is not valid.
|
||||
|
||||
However, Boost.Asio does not use the above definitions as-is, but instead defines two
|
||||
classes: `mutable_buffer` and `const_buffer`. The goal of these is to provide
|
||||
an opaque representation of contiguous memory, where:
|
||||
|
||||
* Types behave as std::pair would in conversions. That is, a `mutable_buffer` is
|
||||
convertible to a `const_buffer`, but the opposite conversion is disallowed.
|
||||
|
||||
* There is protection against buffer overruns. Given a buffer instance, a user
|
||||
can only create another buffer representing the same range of memory or a
|
||||
sub-range of it. To provide further safety, the library also includes
|
||||
mechanisms for automatically determining the size of a buffer from an array,
|
||||
`boost::array` or `std::vector` of POD elements, or from a `std::string`.
|
||||
|
||||
* Type safety violations must be explicitly requested using the `buffer_cast`
|
||||
function. In general an application should never need to do this, but it is
|
||||
required by the library implementation to pass the raw memory to the
|
||||
underlying operating system functions.
|
||||
|
||||
Finally, multiple buffers can be passed to scatter-gather operations (such as
|
||||
[link boost_asio.reference.read read()] or [link boost_asio.reference.write write()]) by
|
||||
putting the buffer objects into a container. The `MutableBufferSequence` and
|
||||
`ConstBufferSequence` concepts have been defined so that containers such as
|
||||
`std::vector`, `std::list`, `std::vector` or `boost::array` can be used.
|
||||
|
||||
[heading Streambuf for Integration with Iostreams]
|
||||
|
||||
The class `boost::asio::basic_streambuf` is derived from `std::basic_streambuf` to
|
||||
associate the input sequence and output sequence with one or more objects of
|
||||
some character array type, whose elements store arbitrary values. These
|
||||
character array objects are internal to the streambuf object, but direct access
|
||||
to the array elements is provided to permit them to be used with I/O
|
||||
operations, such as the send or receive operations of a socket:
|
||||
|
||||
* The input sequence of the streambuf is accessible via the [link
|
||||
boost_asio.reference.basic_streambuf.data data()] member function. The return type
|
||||
of this function meets the `ConstBufferSequence` requirements.
|
||||
|
||||
* The output sequence of the streambuf is accessible via the [link
|
||||
boost_asio.reference.basic_streambuf.data prepare()] member function. The return
|
||||
type of this function meets the `MutableBufferSequence` requirements.
|
||||
|
||||
* Data is transferred from the front of the output sequence to the back of the
|
||||
input sequence by calling the [link boost_asio.reference.basic_streambuf.commit
|
||||
commit()] member function.
|
||||
|
||||
* Data is removed from the front of the input sequence by calling the [link
|
||||
boost_asio.reference.basic_streambuf.consume consume()] member function.
|
||||
|
||||
The streambuf constructor accepts a `size_t` argument specifying the maximum of
|
||||
the sum of the sizes of the input sequence and output sequence. Any operation
|
||||
that would, if successful, grow the internal data beyond this limit will throw
|
||||
a `std::length_error` exception.
|
||||
|
||||
[heading Bytewise Traversal of Buffer Sequences]
|
||||
|
||||
The `buffers_iterator<>` class template allows buffer sequences (i.e. types
|
||||
meeting `MutableBufferSequence` or `ConstBufferSequence` requirements) to be
|
||||
traversed as though they were a contiguous sequence of bytes. Helper functions
|
||||
called buffers_begin() and buffers_end() are also provided, where the
|
||||
buffers_iterator<> template parameter is automatically deduced.
|
||||
|
||||
As an example, to read a single line from a socket and into a `std::string`,
|
||||
you may write:
|
||||
|
||||
boost::asio::streambuf sb;
|
||||
...
|
||||
std::size_t n = boost::asio::read_until(sock, sb, '\n');
|
||||
boost::asio::streambuf::const_buffers_type bufs = sb.data();
|
||||
std::string line(
|
||||
boost::asio::buffers_begin(bufs),
|
||||
boost::asio::buffers_begin(bufs) + n);
|
||||
|
||||
[heading Buffer Debugging]
|
||||
|
||||
Some standard library implementations, such as the one that ships with
|
||||
Microsoft Visual C++ 8.0 and later, provide a feature called iterator
|
||||
debugging. What this means is that the validity of iterators is checked at
|
||||
runtime. If a program tries to use an iterator that has been invalidated, an
|
||||
assertion will be triggered. For example:
|
||||
|
||||
std::vector<int> v(1)
|
||||
std::vector<int>::iterator i = v.begin();
|
||||
v.clear(); // invalidates iterators
|
||||
*i = 0; // assertion!
|
||||
|
||||
Boost.Asio takes advantage of this feature to add buffer debugging. Consider the
|
||||
following code:
|
||||
|
||||
void dont_do_this()
|
||||
{
|
||||
std::string msg = "Hello, world!";
|
||||
boost::asio::async_write(sock, boost::asio::buffer(msg), my_handler);
|
||||
}
|
||||
|
||||
When you call an asynchronous read or write you need to ensure that the buffers
|
||||
for the operation are valid until the completion handler is called. In the
|
||||
above example, the buffer is the `std::string` variable `msg`. This variable is
|
||||
on the stack, and so it goes out of scope before the asynchronous operation
|
||||
completes. If you're lucky then the application will crash, but random failures
|
||||
are more likely.
|
||||
|
||||
When buffer debugging is enabled, Boost.Asio stores an iterator into the string until
|
||||
the asynchronous operation completes, and then dereferences it to check its
|
||||
validity. In the above example you would observe an assertion failure just
|
||||
before Boost.Asio tries to call the completion handler.
|
||||
|
||||
This feature is automatically made available for Microsoft Visual Studio 8.0 or
|
||||
later and for GCC when `_GLIBCXX_DEBUG` is defined. There is a performance cost
|
||||
to this checking, so buffer debugging is only enabled in debug builds. For
|
||||
other compilers it may be enabled by defining `BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`.
|
||||
It can also be explicitly disabled by defining `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING`.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.buffer buffer],
|
||||
[link boost_asio.reference.buffers_begin buffers_begin],
|
||||
[link boost_asio.reference.buffers_end buffers_end],
|
||||
[link boost_asio.reference.buffers_iterator buffers_iterator],
|
||||
[link boost_asio.reference.const_buffer const_buffer],
|
||||
[link boost_asio.reference.const_buffers_1 const_buffers_1],
|
||||
[link boost_asio.reference.mutable_buffer mutable_buffer],
|
||||
[link boost_asio.reference.mutable_buffers_1 mutable_buffers_1],
|
||||
[link boost_asio.reference.streambuf streambuf],
|
||||
[link boost_asio.reference.ConstBufferSequence ConstBufferSequence],
|
||||
[link boost_asio.reference.MutableBufferSequence MutableBufferSequence],
|
||||
[link boost_asio.examples.buffers buffers example].
|
||||
|
||||
[endsect]
|
||||
@@ -5,9 +5,9 @@
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:implementation Platform-Specific Implementation]
|
||||
[section:implementation Platform-Specific Implementation Notes]
|
||||
|
||||
This design note lists platform-specific implementation details, such as the
|
||||
This section lists platform-specific implementation details, such as the
|
||||
default demultiplexing mechanism, the number of threads created internally, and
|
||||
when threads are created.
|
||||
|
||||
46
doc/overview/iostreams.qbk
Normal file
46
doc/overview/iostreams.qbk
Normal file
@@ -0,0 +1,46 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:iostreams Socket Iostreams]
|
||||
|
||||
Boost.Asio includes classes that implement iostreams on top of sockets. These hide
|
||||
away the complexities associated with endpoint resolution, protocol
|
||||
independence, etc. To create a connection one might simply write:
|
||||
|
||||
ip::tcp::iostream stream("www.boost.org", "http");
|
||||
if (!stream)
|
||||
{
|
||||
// Can't connect.
|
||||
}
|
||||
|
||||
The iostream class can also be used in conjunction with an acceptor to create
|
||||
simple servers. For example:
|
||||
|
||||
io_service ios;
|
||||
|
||||
ip::tcp::endpoint endpoint(tcp::v4(), 80);
|
||||
ip::tcp::acceptor acceptor(ios, endpoint);
|
||||
|
||||
for (;;)
|
||||
{
|
||||
ip::tcp::iostream stream;
|
||||
acceptor.accept(*stream.rdbuf());
|
||||
...
|
||||
}
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.ip__tcp.iostream ip::tcp::iostream],
|
||||
[link boost_asio.reference.basic_socket_iostream basic_socket_iostream],
|
||||
[link boost_asio.examples.iostreams iostreams examples].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
These iostream templates only support `char`, not `wchar_t`, and do not perform
|
||||
any code conversion.
|
||||
|
||||
[endsect]
|
||||
118
doc/overview/line_based.qbk
Normal file
118
doc/overview/line_based.qbk
Normal file
@@ -0,0 +1,118 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:line_based Line-Based Operations]
|
||||
|
||||
Many commonly-used internet protocols are line-based, which means that they
|
||||
have protocol elements that are delimited by the character sequence `"\r\n"`.
|
||||
Examples include HTTP, SMTP and FTP. To more easily permit the implementation
|
||||
of line-based protocols, as well as other protocols that use delimiters, Boost.Asio
|
||||
includes the functions `read_until()` and `async_read_until()`.
|
||||
|
||||
The following example illustrates the use of `async_read_until()` in an HTTP
|
||||
server, to receive the first line of an HTTP request from a client:
|
||||
|
||||
class http_connection
|
||||
{
|
||||
...
|
||||
|
||||
void start()
|
||||
{
|
||||
boost::asio::async_read_until(socket_, data_, "\r\n",
|
||||
boost::bind(&http_connection::handle_request_line, this, _1));
|
||||
}
|
||||
|
||||
void handle_request_line(boost::system::error_code ec)
|
||||
{
|
||||
if (!ec)
|
||||
{
|
||||
std::string method, uri, version;
|
||||
char sp1, sp2, cr, lf;
|
||||
std::istream is(&data_);
|
||||
is.unsetf(std::ios_base::skipws);
|
||||
is >> method >> sp1 >> uri >> sp2 >> version >> cr >> lf;
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
...
|
||||
|
||||
boost::asio::ip::tcp::socket socket_;
|
||||
boost::asio::streambuf data_;
|
||||
};
|
||||
|
||||
The `streambuf` data member serves as a place to store the data that has been
|
||||
read from the socket before it is searched for the delimiter. It is important
|
||||
to remember that there may be additional data ['after] the delimiter. This
|
||||
surplus data should be left in the `streambuf` so that it may be inspected by a
|
||||
subsequent call to `read_until()` or `async_read_until()`.
|
||||
|
||||
The delimiters may be specified as a single `char`, a `std::string` or a
|
||||
`boost::regex`. The `read_until()` and `async_read_until()` functions also
|
||||
include overloads that accept a user-defined function object called a match
|
||||
condition. For example, to read data into a streambuf until whitespace is
|
||||
encountered:
|
||||
|
||||
typedef boost::asio::buffers_iterator<
|
||||
boost::asio::streambuf::const_buffers_type> iterator;
|
||||
|
||||
std::pair<iterator, bool>
|
||||
match_whitespace(iterator begin, iterator end)
|
||||
{
|
||||
iterator i = begin;
|
||||
while (i != end)
|
||||
if (std::isspace(*i++))
|
||||
return std::make_pair(i, true);
|
||||
return std::make_pair(i, false);
|
||||
}
|
||||
...
|
||||
boost::asio::streambuf b;
|
||||
boost::asio::read_until(s, b, match_whitespace);
|
||||
|
||||
To read data into a streambuf until a matching character is found:
|
||||
|
||||
class match_char
|
||||
{
|
||||
public:
|
||||
explicit match_char(char c) : c_(c) {}
|
||||
|
||||
template <typename Iterator>
|
||||
std::pair<Iterator, bool> operator()(
|
||||
Iterator begin, Iterator end) const
|
||||
{
|
||||
Iterator i = begin;
|
||||
while (i != end)
|
||||
if (c_ == *i++)
|
||||
return std::make_pair(i, true);
|
||||
return std::make_pair(i, false);
|
||||
}
|
||||
|
||||
private:
|
||||
char c_;
|
||||
};
|
||||
|
||||
namespace boost { namespace asio {
|
||||
template <> struct is_match_condition<match_char>
|
||||
: public boost::true_type {};
|
||||
} } // namespace boost::asio
|
||||
...
|
||||
boost::asio::streambuf b;
|
||||
boost::asio::read_until(s, b, match_char('a'));
|
||||
|
||||
The `is_match_condition<>` type trait automatically evaluates to true for
|
||||
functions, and for function objects with a nested `result_type` typedef. For
|
||||
other types the trait must be explicitly specialised, as shown above.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.async_read_until async_read_until()],
|
||||
[link boost_asio.reference.is_match_condition is_match_condition],
|
||||
[link boost_asio.reference.read_until read_until()],
|
||||
[link boost_asio.reference.streambuf streambuf],
|
||||
[link boost_asio.examples.http_client HTTP client example].
|
||||
|
||||
[endsect]
|
||||
105
doc/overview/posix.qbk
Normal file
105
doc/overview/posix.qbk
Normal file
@@ -0,0 +1,105 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:posix POSIX-Specific Functionality]
|
||||
|
||||
[link boost_asio.overview.posix.local UNIX Domain Sockets]
|
||||
|
||||
[link boost_asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors]
|
||||
|
||||
[section:local UNIX Domain Sockets]
|
||||
|
||||
Boost.Asio provides basic support UNIX domain sockets (also known as local sockets).
|
||||
The simplest use involves creating a pair of connected sockets. The following
|
||||
code:
|
||||
|
||||
local::stream_protocol::socket socket1(my_io_service);
|
||||
local::stream_protocol::socket socket2(my_io_service);
|
||||
local::connect_pair(socket1, socket2);
|
||||
|
||||
will create a pair of stream-oriented sockets. To do the same for
|
||||
datagram-oriented sockets, use:
|
||||
|
||||
local::datagram_protocol::socket socket1(my_io_service);
|
||||
local::datagram_protocol::socket socket2(my_io_service);
|
||||
local::connect_pair(socket1, socket2);
|
||||
|
||||
A UNIX domain socket server may be created by binding an acceptor to an
|
||||
endpoint, in much the same way as one does for a TCP server:
|
||||
|
||||
::unlink("/tmp/foobar"); // Remove previous binding.
|
||||
local::stream_protocol::endpoint ep("/tmp/foobar");
|
||||
local::stream_protocol::acceptor acceptor(my_io_service, ep);
|
||||
local::stream_protocol::socket socket(my_io_service);
|
||||
acceptor.accept(socket);
|
||||
|
||||
A client that connects to this server might look like:
|
||||
|
||||
local::stream_protocol::endpoint ep("/tmp/foobar");
|
||||
local::stream_protocol::socket socket(my_io_service);
|
||||
socket.connect(ep);
|
||||
|
||||
Transmission of file descriptors or credentials across UNIX domain sockets is
|
||||
not directly supported within Boost.Asio, but may be achieved by accessing the
|
||||
socket's underlying descriptor using the [link
|
||||
boost_asio.reference.basic_socket.native native()] member function.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.local__connect_pair local::connect_pair],
|
||||
[link boost_asio.reference.local__datagram_protocol local::datagram_protocol],
|
||||
[link boost_asio.reference.local__datagram_protocol.endpoint local::datagram_protocol::endpoint],
|
||||
[link boost_asio.reference.local__datagram_protocol.socket local::datagram_protocol::socket],
|
||||
[link boost_asio.reference.local__stream_protocol local::stream_protocol],
|
||||
[link boost_asio.reference.local__stream_protocol.acceptor local::stream_protocol::acceptor],
|
||||
[link boost_asio.reference.local__stream_protocol.endpoint local::stream_protocol::endpoint],
|
||||
[link boost_asio.reference.local__stream_protocol.iostream local::stream_protocol::iostream],
|
||||
[link boost_asio.reference.local__stream_protocol.socket local::stream_protocol::socket],
|
||||
[link boost_asio.examples.unix_domain_sockets UNIX domain sockets examples].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
UNIX domain sockets are only available at compile time if supported by the
|
||||
target operating system. A program may test for the macro
|
||||
`BOOST_ASIO_HAS_LOCAL_SOCKETS` to determine whether they are supported.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:stream_descriptor Stream-Oriented File Descriptors]
|
||||
|
||||
Boost.Asio includes classes added to permit synchronous and asynchronous read and
|
||||
write operations to be performed on POSIX file descriptors, such as pipes,
|
||||
standard input and output, and various devices (but /not/ regular files).
|
||||
|
||||
For example, to perform read and write operations on standard input
|
||||
and output, the following objects may be created:
|
||||
|
||||
posix::stream_descriptor in(my_io_service, ::dup(STDIN_FILENO));
|
||||
posix::stream_descriptor out(my_io_service, ::dup(STDOUT_FILENO));
|
||||
|
||||
These are then used as synchronous or asynchronous read and write streams. This
|
||||
means the objects can be used with any of the [link boost_asio.reference.read
|
||||
read()], [link boost_asio.reference.async_read async_read()], [link
|
||||
boost_asio.reference.write write()], [link boost_asio.reference.async_write async_write()],
|
||||
[link boost_asio.reference.read_until read_until()] or [link
|
||||
boost_asio.reference.async_read_until async_read_until()] free functions.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.posix__stream_descriptor posix::stream_descriptor],
|
||||
[link boost_asio.reference.posix__basic_stream_descriptor posix::basic_stream_descriptor],
|
||||
[link boost_asio.reference.posix__stream_descriptor_service posix::stream_descriptor_service].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
POSIX stream descriptors are only available at compile time if supported by the
|
||||
target operating system. A program may test for the macro
|
||||
`BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR` to determine whether they are supported.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 30 KiB |
54
doc/overview/rationale.qbk
Normal file
54
doc/overview/rationale.qbk
Normal file
@@ -0,0 +1,54 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:rationale Rationale]
|
||||
|
||||
Most programs interact with the outside world in some way, whether it be via a
|
||||
file, a network, a serial cable, or the console. Sometimes, as is the case with
|
||||
networking, individual I/O operations can take a long time to complete. This
|
||||
poses particular challenges to application development.
|
||||
|
||||
Boost.Asio provides the tools to manage these long running operations, without
|
||||
requiring programs to use concurrency models based on threads and explicit
|
||||
locking.
|
||||
|
||||
The Boost.Asio library is intended for programmers using C++ for systems programming,
|
||||
where access to operating system functionality such as networking is often
|
||||
required. In particular, Boost.Asio addresses the following goals:
|
||||
|
||||
* [*Portability.] The library should support a range of commonly used operating
|
||||
systems, and provide consistent behaviour across these operating systems.
|
||||
|
||||
* [*Scalability.] The library should facilitate the development of network
|
||||
applications that scale to thousands of concurrent connections. The library
|
||||
implementation for each operating system should use the mechanism that best
|
||||
enables this scalability.
|
||||
|
||||
* [*Efficiency.] The library should support techniques such as scatter-gather
|
||||
I/O, and allow programs to minimise data copying.
|
||||
|
||||
* [*Model concepts from established APIs, such as BSD sockets.] The
|
||||
BSD socket API is widely implemented and understood, and is covered in much
|
||||
literature. Other programming languages often use a similar interface for
|
||||
networking APIs. As far as is reasonable, Boost.Asio should leverage existing
|
||||
practice.
|
||||
|
||||
* [*Ease of use.] The library should provide a lower entry barrier for new
|
||||
users by taking a toolkit, rather than framework, approach. That is, it should
|
||||
try to minimise the up-front investment in time to just learning a few basic
|
||||
rules and guidelines. After that, a library user should only need to understand
|
||||
the specific functions that are being used.
|
||||
|
||||
* [*Basis for further abstraction.] The library should permit the development
|
||||
of other libraries that provide higher levels of abstraction. For example,
|
||||
implementations of commonly used protocols such as HTTP.
|
||||
|
||||
Although Boost.Asio started life focused primarily on networking, its concepts of
|
||||
asynchronous I/O have been extended to include other operating system resources
|
||||
such as serial ports, file descriptors, and so on.
|
||||
|
||||
[endsect]
|
||||
43
doc/overview/reactor.qbk
Normal file
43
doc/overview/reactor.qbk
Normal file
@@ -0,0 +1,43 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:reactor Reactor-Style Operations]
|
||||
|
||||
Sometimes a program must be integrated with a third-party library that wants to
|
||||
perform the I/O operations itself. To facilitate this, Boost.Asio includes a
|
||||
`null_buffers` type that can be used with both read and write operations. A
|
||||
`null_buffers` operation doesn't return until the I/O object is "ready" to
|
||||
perform the operation.
|
||||
|
||||
As an example, to perform a non-blocking read something like the
|
||||
following may be used:
|
||||
|
||||
ip::tcp::socket socket(my_io_service);
|
||||
...
|
||||
ip::tcp::socket::non_blocking nb(true);
|
||||
socket.io_control(nb);
|
||||
...
|
||||
socket.async_read_some(null_buffers(), read_handler);
|
||||
...
|
||||
void read_handler(boost::system::error_code ec)
|
||||
{
|
||||
if (!ec)
|
||||
{
|
||||
std::vector<char> buf(socket.available());
|
||||
socket.read_some(buffer(buf));
|
||||
}
|
||||
}
|
||||
|
||||
These operations are supported for sockets on all platforms, and for the POSIX
|
||||
stream-oriented descriptor classes.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.null_buffers null_buffers],
|
||||
[link boost_asio.examples.nonblocking nonblocking example].
|
||||
|
||||
[endsect]
|
||||
47
doc/overview/serial_ports.qbk
Normal file
47
doc/overview/serial_ports.qbk
Normal file
@@ -0,0 +1,47 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:serial_ports Serial Ports]
|
||||
|
||||
Boost.Asio includes classes for creating and manipulating serial ports in a portable
|
||||
manner. For example, a serial port may be opened using:
|
||||
|
||||
serial_port port(my_io_service, name);
|
||||
|
||||
where name is something like `"COM1"` on Windows, and `"/dev/ttyS0"` on POSIX
|
||||
platforms.
|
||||
|
||||
Once opened the serial port may be used as a stream. This means the objects can
|
||||
be used with any of the [link boost_asio.reference.read read()], [link
|
||||
boost_asio.reference.async_read async_read()], [link boost_asio.reference.write write()],
|
||||
[link boost_asio.reference.async_write async_write()], [link
|
||||
boost_asio.reference.read_until read_until()] or [link
|
||||
boost_asio.reference.async_read_until async_read_until()] free functions.
|
||||
|
||||
The serial port implementation also includes option classes for configuring the
|
||||
port's baud rate, flow control type, parity, stop bits and character size.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.serial_port serial_port],
|
||||
[link boost_asio.reference.serial_port_base serial_port_base],
|
||||
[link boost_asio.reference.basic_serial_port basic_serial_port],
|
||||
[link boost_asio.reference.serial_port_service serial_port_service],
|
||||
[link boost_asio.reference.serial_port_base__baud_rate serial_port_base::baud_rate],
|
||||
[link boost_asio.reference.serial_port_base__flow_control serial_port_base::flow_control],
|
||||
[link boost_asio.reference.serial_port_base__parity serial_port_base::parity],
|
||||
[link boost_asio.reference.serial_port_base__stop_bits serial_port_base::stop_bits],
|
||||
[link boost_asio.reference.serial_port_base__character_size serial_port_base::character_size].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
Serial ports are available on all POSIX platforms. For Windows, serial ports
|
||||
are only available at compile time when the I/O completion port backend is used
|
||||
(which is the default). A program may test for the macro
|
||||
`BOOST_ASIO_HAS_SERIAL_PORTS` to determine whether they are supported.
|
||||
|
||||
[endsect]
|
||||
68
doc/overview/ssl.qbk
Normal file
68
doc/overview/ssl.qbk
Normal file
@@ -0,0 +1,68 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:ssl SSL]
|
||||
|
||||
Boost.Asio contains classes and class templates for basic SSL support. These classes
|
||||
allow encrypted communication to be layered on top of an existing stream, such
|
||||
as a TCP socket.
|
||||
|
||||
Before creating an encrypted stream, an application must construct an SSL
|
||||
context object. This object is used to set SSL options such as verification
|
||||
mode, certificate files, and so on. As an illustration, client-side
|
||||
initialisation may look something like:
|
||||
|
||||
ssl::context ctx(io_service, ssl::context::sslv23);
|
||||
ctx.set_verify_mode(ssl::context::verify_peer);
|
||||
ctx.load_verify_file("ca.pem");
|
||||
|
||||
To use SSL with a TCP socket, one may write:
|
||||
|
||||
ssl::stream<ip::tcp::socket> ssl_sock(my_io_service, ctx);
|
||||
|
||||
To perform socket-specific operations, such as establishing an outbound
|
||||
connection or accepting an incoming one, the underlying socket must first be
|
||||
obtained using the `ssl::stream` template's [link
|
||||
boost_asio.reference.ssl__stream.lowest_layer `lowest_layer()`] member function:
|
||||
|
||||
ip::tcp::socket& sock = ssl_sock.lowest_layer();
|
||||
sock.connect(my_endpoint);
|
||||
|
||||
In some use cases the underlying stream object will need to have a longer
|
||||
lifetime than the SSL stream, in which case the template parameter should be a
|
||||
reference to the stream type:
|
||||
|
||||
ip::tcp::socket sock(my_io_service);
|
||||
ssl::stream<ip::tcp::socket&> ssl_sock(sock, ctx);
|
||||
|
||||
Once connected, SSL stream objects are used as synchronous or asynchronous read
|
||||
and write streams. This means the objects can be used with any of the [link
|
||||
boost_asio.reference.read read()], [link boost_asio.reference.async_read async_read()],
|
||||
[link boost_asio.reference.write write()], [link boost_asio.reference.async_write
|
||||
async_write()], [link boost_asio.reference.read_until read_until()] or [link
|
||||
boost_asio.reference.async_read_until async_read_until()] free functions.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.ssl__basic_context ssl::basic_context],
|
||||
[link boost_asio.reference.ssl__context ssl::context],
|
||||
[link boost_asio.reference.ssl__context_base ssl::context_base],
|
||||
[link boost_asio.reference.ssl__context_service ssl::context_service],
|
||||
[link boost_asio.reference.ssl__stream ssl::stream],
|
||||
[link boost_asio.reference.ssl__stream_base ssl::stream_base],
|
||||
[link boost_asio.reference.ssl__stream_service ssl::stream_service],
|
||||
[link boost_asio.examples.ssl SSL example].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
[@http://www.openssl.org OpenSSL] is required to make use of Boost.Asio's SSL
|
||||
support. When an application needs to use OpenSSL functionality that is not
|
||||
wrapped by Boost.Asio, the underlying OpenSSL types may be obtained by calling [link
|
||||
boost_asio.reference.ssl__basic_context.impl `ssl::context::impl()`] or [link
|
||||
boost_asio.reference.ssl__stream.impl `ssl::stream::impl()`].
|
||||
|
||||
[endsect]
|
||||
@@ -5,7 +5,7 @@
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:strands Strands]
|
||||
[section:strands Strands: Use Threads Without Explicit Locking]
|
||||
|
||||
A strand is defined as a strictly sequential invocation of event handlers (i.e.
|
||||
no concurrent invocation). Use of strands allows execution of code in a
|
||||
@@ -50,7 +50,13 @@ customisable hook associated with the final handler:
|
||||
}
|
||||
|
||||
The `io_service::strand::wrap()` function creates a new completion handler that
|
||||
defines `asio_handler_invoke` so that the function object is executed through the
|
||||
strand.
|
||||
defines `asio_handler_invoke` so that the function object is executed through
|
||||
the strand.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.io_service__strand io_service::strand],
|
||||
[link boost_asio.tutorial.tuttimer5 tutorial Timer.5],
|
||||
[link boost_asio.examples.http_server_3 HTTP server 3 example].
|
||||
|
||||
[endsect]
|
||||
62
doc/overview/streams.qbk
Normal file
62
doc/overview/streams.qbk
Normal file
@@ -0,0 +1,62 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:streams Streams, Short Reads and Short Writes]
|
||||
|
||||
Many I/O objects in Boost.Asio are stream-oriented. This means that:
|
||||
|
||||
* There are no message boundaries. The data being transferred is a continuous
|
||||
sequence of bytes.
|
||||
|
||||
* Read or write operations may transfer fewer bytes than requested. This is
|
||||
referred to as a short read or short write.
|
||||
|
||||
Objects that provide stream-oriented I/O model one or more of the following
|
||||
type requirements:
|
||||
|
||||
* `SyncReadStream`, where synchronous read operations are performed using a
|
||||
member function called `read_some()`.
|
||||
|
||||
* `AsyncReadStream`, where asynchronous read operations are performed using a
|
||||
member function called `async_read_some()`.
|
||||
|
||||
* `SyncWriteStream`, where synchronous write operations are performed using a
|
||||
member function called `write_some()`.
|
||||
|
||||
* `AsyncWriteStream`, where synchronous write operations are performed using a
|
||||
member function called `async_write_some()`.
|
||||
|
||||
Examples of stream-oriented I/O objects include `ip::tcp::socket`,
|
||||
`ssl::stream<>`, `posix::stream_descriptor`, `windows::stream_handle`, etc.
|
||||
|
||||
Programs typically want to transfer an exact number of bytes. When a short read
|
||||
or short write occurs the program must restart the operation, and continue to
|
||||
do so until the required number of bytes has been transferred. Boost.Asio provides
|
||||
generic functions that do this automatically: `read()`, `async_read()`,
|
||||
`write()` and `async_write()`.
|
||||
|
||||
[heading Why EOF is an Error]
|
||||
|
||||
* The end of a stream can cause `read`, `async_read`, `read_until` or
|
||||
`async_read_until` functions to violate their contract. E.g.
|
||||
a read of N bytes may finish early due to EOF.
|
||||
|
||||
* An EOF error may be used to distinguish the end of a stream from a successful
|
||||
read of size 0.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.async_read async_read()],
|
||||
[link boost_asio.reference.async_write async_write()],
|
||||
[link boost_asio.reference.read read()],
|
||||
[link boost_asio.reference.write write()],
|
||||
[link boost_asio.reference.AsyncReadStream AsyncReadStream],
|
||||
[link boost_asio.reference.AsyncWriteStream AsyncWriteStream],
|
||||
[link boost_asio.reference.SyncReadStream SyncReadStream],
|
||||
[link boost_asio.reference.SyncWriteStream SyncWriteStream].
|
||||
|
||||
[endsect]
|
||||
@@ -5,7 +5,7 @@
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:threads Threads]
|
||||
[section:threads Threads and Boost.Asio]
|
||||
|
||||
[heading Thread Safety]
|
||||
|
||||
@@ -14,6 +14,17 @@ to make concurrent use of a single object. However, types such as `io_service`
|
||||
provide a stronger guarantee that it is safe to use a single object
|
||||
concurrently.
|
||||
|
||||
[heading Thread Pools]
|
||||
|
||||
Multiple threads may call `io_service::run()` to set up a pool of threads from
|
||||
which completion handlers may be invoked. This approach may also be used with
|
||||
`io_service::post()` to use a means to perform any computational tasks across a
|
||||
thread pool.
|
||||
|
||||
Note that all threads that have joined an `io_service`'s pool are considered
|
||||
equivalent, and the `io_service` may distribute work across them in an
|
||||
arbitrary fashion.
|
||||
|
||||
[heading Internal Threads]
|
||||
|
||||
The implementation of this library for a particular platform may make use of
|
||||
@@ -24,6 +35,16 @@ these threads must be invisible to the library user. In particular, the threads:
|
||||
|
||||
* must block all signals.
|
||||
|
||||
[note The implementation currently violates the first of these rules for the
|
||||
following functions:
|
||||
|
||||
[mdash] `ip::basic_resolver::async_resolve()` on all platforms.
|
||||
|
||||
[mdash] `basic_socket::async_connect()` on Windows.
|
||||
|
||||
[mdash] Any operation involving `null_buffers()` on Windows, other than an
|
||||
asynchronous read performed on a stream-oriented socket.]
|
||||
|
||||
This approach is complemented by the following guarantee:
|
||||
|
||||
* Asynchronous completion handlers will only be called from threads that are
|
||||
@@ -48,4 +69,8 @@ The reasons for this approach include:
|
||||
management, and permits implementations on platforms where threads are not
|
||||
available.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.io_service io_service].
|
||||
|
||||
[endsect]
|
||||
53
doc/overview/timers.qbk
Normal file
53
doc/overview/timers.qbk
Normal file
@@ -0,0 +1,53 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:timers Timers]
|
||||
|
||||
Long running I/O operations will often have a deadline by which they must have
|
||||
completed. These deadlines may be expressed as absolute times, but are often
|
||||
calculated relative to the current time.
|
||||
|
||||
As a simple example, to perform a synchronous wait operation on a timer using a
|
||||
relative time one may write:
|
||||
|
||||
io_service i;
|
||||
...
|
||||
deadline_timer t(i);
|
||||
t.expires_from_now(boost::posix_time::seconds(5));
|
||||
t.wait();
|
||||
|
||||
More commonly, a program will perform an asynchronous wait operation on a
|
||||
timer:
|
||||
|
||||
void handler(boost::system::error_code ec) { ... }
|
||||
...
|
||||
io_service i;
|
||||
...
|
||||
deadline_timer t(i);
|
||||
t.expires_from_now(boost::posix_time::milliseconds(400));
|
||||
t.async_wait(handler);
|
||||
...
|
||||
i.run();
|
||||
|
||||
The deadline associated with a timer may be also be obtained as a relative time:
|
||||
|
||||
boost::posix_time::time_duration time_until_expiry
|
||||
= t.expires_from_now();
|
||||
|
||||
or as an absolute time to allow composition of timers:
|
||||
|
||||
deadline_timer t2(i);
|
||||
t2.expires_at(t.expires_at() + boost::posix_time::seconds(30));
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.basic_deadline_timer basic_deadline_timer],
|
||||
[link boost_asio.reference.deadline_timer deadline_timer],
|
||||
[link boost_asio.reference.deadline_timer_service deadline_timer_service],
|
||||
[link boost_asio.tutorial.tuttimer1 timer tutorials].
|
||||
|
||||
[endsect]
|
||||
91
doc/overview/windows.qbk
Normal file
91
doc/overview/windows.qbk
Normal file
@@ -0,0 +1,91 @@
|
||||
[/
|
||||
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
||||
/
|
||||
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
/]
|
||||
|
||||
[section:windows Windows-Specific Functionality]
|
||||
|
||||
[link boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
|
||||
|
||||
[link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs]
|
||||
|
||||
[section:stream_handle Stream-Oriented HANDLEs]
|
||||
|
||||
Boost.Asio contains classes to allow asynchronous read and write operations to be
|
||||
performed on Windows `HANDLE`s, such as named pipes.
|
||||
|
||||
For example, to perform asynchronous operations on a named pipe, the following
|
||||
object may be created:
|
||||
|
||||
HANDLE handle = ::CreateFile(...);
|
||||
windows::stream_handle pipe(my_io_service, handle);
|
||||
|
||||
These are then used as synchronous or asynchronous read and write streams. This
|
||||
means the objects can be used with any of the [link boost_asio.reference.read
|
||||
read()], [link boost_asio.reference.async_read async_read()], [link
|
||||
boost_asio.reference.write write()], [link boost_asio.reference.async_write
|
||||
async_write()], [link boost_asio.reference.read_until read_until()] or [link
|
||||
boost_asio.reference.async_read_until async_read_until()] free functions.
|
||||
|
||||
The kernel object referred to by the `HANDLE` must support use with I/O
|
||||
completion ports (which means that named pipes are supported, but anonymous
|
||||
pipes and console streams are not).
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.windows__stream_handle windows::stream_handle],
|
||||
[link boost_asio.reference.windows__basic_stream_handle windows::basic_stream_handle],
|
||||
[link boost_asio.reference.windows__stream_handle_service windows::stream_handle_service].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
Windows stream `HANDLE`s are only available at compile time when targeting
|
||||
Windows and only when the I/O completion port backend is used (which is the
|
||||
default). A program may test for the macro `BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE` to
|
||||
determine whether they are supported.
|
||||
|
||||
[endsect]
|
||||
|
||||
[/-----------------------------------------------------------------------------]
|
||||
|
||||
[section:random_access_handle Random-Access HANDLEs]
|
||||
|
||||
Boost.Asio provides Windows-specific classes that permit asynchronous read and write
|
||||
operations to be performed on HANDLEs that refer to regular files.
|
||||
|
||||
For example, to perform asynchronous operations on a file the following object
|
||||
may be created:
|
||||
|
||||
HANDLE handle = ::CreateFile(...);
|
||||
windows::random_access_handle file(my_io_service, handle);
|
||||
|
||||
Data may be read from or written to the handle using one of the
|
||||
`read_some_at()`, `async_read_some_at()`, `write_some_at()` or
|
||||
`async_write_some_at()` member functions. However, like the equivalent
|
||||
functions (`read_some()`, etc.) on streams, these functions are only required
|
||||
to transfer one or more bytes in a single operation. Therefore free functions
|
||||
called [link boost_asio.reference.read_at read_at()], [link
|
||||
boost_asio.reference.async_read_at async_read_at()], [link boost_asio.reference.write_at
|
||||
write_at()] and [link boost_asio.reference.async_write_at async_write_at()] have been
|
||||
created to repeatedly call the corresponding [^[**]_some_at()] function until
|
||||
all data has been transferred.
|
||||
|
||||
[heading See Also]
|
||||
|
||||
[link boost_asio.reference.windows__random_access_handle windows::random_access_handle],
|
||||
[link boost_asio.reference.windows__basic_random_access_handle windows::basic_random_access_handle],
|
||||
[link boost_asio.reference.windows__random_access_handle_service windows::random_access_handle_service].
|
||||
|
||||
[heading Notes]
|
||||
|
||||
Windows random-access `HANDLE`s are only available at compile time when
|
||||
targeting Windows and only when the I/O completion port backend is used (which
|
||||
is the default). A program may test for the macro
|
||||
`BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are
|
||||
supported.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
@@ -264,4 +264,11 @@ Boost.Asio.
|
||||
]
|
||||
]
|
||||
|
||||
[heading Mailing List]
|
||||
|
||||
A mailing list specifically for Boost.Asio may be found on
|
||||
[@http://sourceforge.net/mail/?group_id=122478 SourceForge.net]. Newsgroup
|
||||
access is provided via [@http://dir.gmane.org/gmane.comp.lib.boost.asio.user
|
||||
Gmane].
|
||||
|
||||
[endsect]
|
||||
|
||||
Reference in New Issue
Block a user