From c2dedfe03b32b775e2f347e8bd838cd5df2eabbc Mon Sep 17 00:00:00 2001 From: Christopher Kohlhoff Date: Thu, 17 Jul 2008 15:05:24 +0000 Subject: [PATCH] Documentation updates. [SVN r47503] --- doc/Jamfile.v2 | 8 +- doc/asio.qbk | 21 +- doc/design.qbk | 104 -------- doc/design/buffers.qbk | 58 ----- doc/design/eof.qbk | 17 -- doc/design/line_based.qbk | 50 ---- doc/design/rationale.qbk | 44 ---- doc/examples.qbk | 27 ++ doc/index.xml | 13 + doc/overview.qbk | 81 ++++++ doc/{design => overview}/allocation.qbk | 16 ++ doc/{design => overview}/async.qbk | 28 +- doc/overview/bsd_sockets.qbk | 270 ++++++++++++++++++++ doc/overview/buffers.qbk | 162 ++++++++++++ doc/{design => overview}/implementation.qbk | 4 +- doc/overview/iostreams.qbk | 46 ++++ doc/overview/line_based.qbk | 118 +++++++++ doc/overview/posix.qbk | 105 ++++++++ doc/{design => overview}/proactor.dot | 0 doc/{design => overview}/proactor.png | Bin doc/overview/rationale.qbk | 54 ++++ doc/overview/reactor.qbk | 43 ++++ doc/overview/serial_ports.qbk | 47 ++++ doc/overview/ssl.qbk | 68 +++++ doc/{design => overview}/strands.qbk | 12 +- doc/overview/streams.qbk | 62 +++++ doc/{design => overview}/threads.qbk | 27 +- doc/overview/timers.qbk | 53 ++++ doc/overview/windows.qbk | 91 +++++++ doc/using.qbk | 7 + 30 files changed, 1333 insertions(+), 303 deletions(-) delete mode 100644 doc/design.qbk delete mode 100644 doc/design/buffers.qbk delete mode 100644 doc/design/eof.qbk delete mode 100644 doc/design/line_based.qbk delete mode 100644 doc/design/rationale.qbk create mode 100644 doc/index.xml create mode 100644 doc/overview.qbk rename doc/{design => overview}/allocation.qbk (79%) rename doc/{design => overview}/async.qbk (87%) create mode 100644 doc/overview/bsd_sockets.qbk create mode 100644 doc/overview/buffers.qbk rename doc/{design => overview}/implementation.qbk (98%) create mode 100644 doc/overview/iostreams.qbk create mode 100644 doc/overview/line_based.qbk create mode 100644 doc/overview/posix.qbk rename doc/{design => overview}/proactor.dot (100%) rename doc/{design => overview}/proactor.png (100%) create mode 100644 doc/overview/rationale.qbk create mode 100644 doc/overview/reactor.qbk create mode 100644 doc/overview/serial_ports.qbk create mode 100644 doc/overview/ssl.qbk rename doc/{design => overview}/strands.qbk (88%) create mode 100644 doc/overview/streams.qbk rename doc/{design => overview}/threads.qbk (68%) create mode 100644 doc/overview/timers.qbk create mode 100644 doc/overview/windows.qbk diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 865086b5..c8bc17e2 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -24,14 +24,14 @@ install css install images : - design/proactor.png + overview/proactor.png : 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 : $(BOOST_ROOT)/doc/html/boost_asio ; diff --git a/doc/asio.qbk b/doc/asio.qbk index 0d242a4e..c929f685 100644 --- a/doc/asio.qbk +++ b/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] diff --git a/doc/design.qbk b/doc/design.qbk deleted file mode 100644 index ecc2a196..00000000 --- a/doc/design.qbk +++ /dev/null @@ -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] diff --git a/doc/design/buffers.qbk b/doc/design/buffers.qbk deleted file mode 100644 index 85645104..00000000 --- a/doc/design/buffers.qbk +++ /dev/null @@ -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 mutable_buffer; - typedef std::pair 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] diff --git a/doc/design/eof.qbk b/doc/design/eof.qbk deleted file mode 100644 index 26afdd45..00000000 --- a/doc/design/eof.qbk +++ /dev/null @@ -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] diff --git a/doc/design/line_based.qbk b/doc/design/line_based.qbk deleted file mode 100644 index 9828881e..00000000 --- a/doc/design/line_based.qbk +++ /dev/null @@ -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] diff --git a/doc/design/rationale.qbk b/doc/design/rationale.qbk deleted file mode 100644 index d10d70d7..00000000 --- a/doc/design/rationale.qbk +++ /dev/null @@ -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] diff --git a/doc/examples.qbk b/doc/examples.qbk index dbbb2be3..c7965338 100644 --- a/doc/examples.qbk +++ b/doc/examples.qbk @@ -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] diff --git a/doc/index.xml b/doc/index.xml new file mode 100644 index 00000000..0cac31fd --- /dev/null +++ b/doc/index.xml @@ -0,0 +1,13 @@ + + + + + +
+ +
diff --git a/doc/overview.qbk b/doc/overview.qbk new file mode 100644 index 00000000..8839eca6 --- /dev/null +++ b/doc/overview.qbk @@ -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] diff --git a/doc/design/allocation.qbk b/doc/overview/allocation.qbk similarity index 79% rename from doc/design/allocation.qbk rename to doc/overview/allocation.qbk index c741b147..06d1b42f 100644 --- a/doc/design/allocation.qbk +++ b/doc/overview/allocation.qbk @@ -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] diff --git a/doc/design/async.qbk b/doc/overview/async.qbk similarity index 87% rename from doc/design/async.qbk rename to doc/overview/async.qbk index c630772a..3b8412e8 100644 --- a/doc/design/async.qbk +++ b/doc/overview/async.qbk @@ -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. diff --git a/doc/overview/bsd_sockets.qbk b/doc/overview/bsd_sockets.qbk new file mode 100644 index 00000000..5197486f --- /dev/null +++ b/doc/overview/bsd_sockets.qbk @@ -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] diff --git a/doc/overview/buffers.qbk b/doc/overview/buffers.qbk new file mode 100644 index 00000000..54573162 --- /dev/null +++ b/doc/overview/buffers.qbk @@ -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 mutable_buffer; + typedef std::pair 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 v(1) + std::vector::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] diff --git a/doc/design/implementation.qbk b/doc/overview/implementation.qbk similarity index 98% rename from doc/design/implementation.qbk rename to doc/overview/implementation.qbk index a9422feb..3b7cd06d 100644 --- a/doc/design/implementation.qbk +++ b/doc/overview/implementation.qbk @@ -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. diff --git a/doc/overview/iostreams.qbk b/doc/overview/iostreams.qbk new file mode 100644 index 00000000..ef0ba98d --- /dev/null +++ b/doc/overview/iostreams.qbk @@ -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] diff --git a/doc/overview/line_based.qbk b/doc/overview/line_based.qbk new file mode 100644 index 00000000..45086000 --- /dev/null +++ b/doc/overview/line_based.qbk @@ -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 + 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 + std::pair 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 + : 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] diff --git a/doc/overview/posix.qbk b/doc/overview/posix.qbk new file mode 100644 index 00000000..2603f94e --- /dev/null +++ b/doc/overview/posix.qbk @@ -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] diff --git a/doc/design/proactor.dot b/doc/overview/proactor.dot similarity index 100% rename from doc/design/proactor.dot rename to doc/overview/proactor.dot diff --git a/doc/design/proactor.png b/doc/overview/proactor.png similarity index 100% rename from doc/design/proactor.png rename to doc/overview/proactor.png diff --git a/doc/overview/rationale.qbk b/doc/overview/rationale.qbk new file mode 100644 index 00000000..223ea463 --- /dev/null +++ b/doc/overview/rationale.qbk @@ -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] diff --git a/doc/overview/reactor.qbk b/doc/overview/reactor.qbk new file mode 100644 index 00000000..ec4d0ab0 --- /dev/null +++ b/doc/overview/reactor.qbk @@ -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 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] diff --git a/doc/overview/serial_ports.qbk b/doc/overview/serial_ports.qbk new file mode 100644 index 00000000..e9a37fbc --- /dev/null +++ b/doc/overview/serial_ports.qbk @@ -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] diff --git a/doc/overview/ssl.qbk b/doc/overview/ssl.qbk new file mode 100644 index 00000000..391e1ea3 --- /dev/null +++ b/doc/overview/ssl.qbk @@ -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 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 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] diff --git a/doc/design/strands.qbk b/doc/overview/strands.qbk similarity index 88% rename from doc/design/strands.qbk rename to doc/overview/strands.qbk index f0a13e26..d0b34521 100644 --- a/doc/design/strands.qbk +++ b/doc/overview/strands.qbk @@ -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] diff --git a/doc/overview/streams.qbk b/doc/overview/streams.qbk new file mode 100644 index 00000000..c6fde34b --- /dev/null +++ b/doc/overview/streams.qbk @@ -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] diff --git a/doc/design/threads.qbk b/doc/overview/threads.qbk similarity index 68% rename from doc/design/threads.qbk rename to doc/overview/threads.qbk index 5b0f872c..dd26f6ee 100644 --- a/doc/design/threads.qbk +++ b/doc/overview/threads.qbk @@ -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] diff --git a/doc/overview/timers.qbk b/doc/overview/timers.qbk new file mode 100644 index 00000000..18d41273 --- /dev/null +++ b/doc/overview/timers.qbk @@ -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] diff --git a/doc/overview/windows.qbk b/doc/overview/windows.qbk new file mode 100644 index 00000000..92b96c60 --- /dev/null +++ b/doc/overview/windows.qbk @@ -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] diff --git a/doc/using.qbk b/doc/using.qbk index 8266df4f..78addbd8 100644 --- a/doc/using.qbk +++ b/doc/using.qbk @@ -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]