diff options
Diffstat (limited to 'doc/html/boost_asio/overview')
37 files changed, 4828 insertions, 0 deletions
diff --git a/doc/html/boost_asio/overview/core.html b/doc/html/boost_asio/overview/core.html new file mode 100755 index 0000000000..ace28cfb33 --- /dev/null +++ b/doc/html/boost_asio/overview/core.html @@ -0,0 +1,78 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Core Concepts and Functionality</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="rationale.html" title="Rationale"> +<link rel="next" href="core/basics.html" title="Basic Boost.Asio Anatomy"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="rationale.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="core/basics.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.core"></a><a class="link" href="core.html" title="Core Concepts and Functionality">Core Concepts and Functionality</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a class="link" href="core/basics.html" title="Basic Boost.Asio Anatomy">Basic Boost.Asio Anatomy</a> + </li> +<li class="listitem"> + <a class="link" href="core/async.html" title="The Proactor Design Pattern: Concurrency Without Threads">The Proactor Design Pattern: + Concurrency Without Threads</a> + </li> +<li class="listitem"> + <a class="link" href="core/threads.html" title="Threads and Boost.Asio">Threads and Boost.Asio</a> + </li> +<li class="listitem"> + <a class="link" href="core/strands.html" title="Strands: Use Threads Without Explicit Locking">Strands: Use Threads + Without Explicit Locking</a> + </li> +<li class="listitem"> + <a class="link" href="core/buffers.html" title="Buffers">Buffers</a> + </li> +<li class="listitem"> + <a class="link" href="core/streams.html" title="Streams, Short Reads and Short Writes">Streams, Short Reads + and Short Writes</a> + </li> +<li class="listitem"> + <a class="link" href="core/reactor.html" title="Reactor-Style Operations">Reactor-Style Operations</a> + </li> +<li class="listitem"> + <a class="link" href="core/line_based.html" title="Line-Based Operations">Line-Based Operations</a> + </li> +<li class="listitem"> + <a class="link" href="core/allocation.html" title="Custom Memory Allocation">Custom Memory Allocation</a> + </li> +<li class="listitem"> + <a class="link" href="core/handler_tracking.html" title="Handler Tracking">Handler Tracking</a> + </li> +</ul></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="rationale.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="core/basics.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/allocation.html b/doc/html/boost_asio/overview/core/allocation.html new file mode 100755 index 0000000000..06504eadcb --- /dev/null +++ b/doc/html/boost_asio/overview/core/allocation.html @@ -0,0 +1,106 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Custom Memory Allocation</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="line_based.html" title="Line-Based Operations"> +<link rel="next" href="handler_tracking.html" title="Handler Tracking"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="line_based.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="handler_tracking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.allocation"></a><a class="link" href="allocation.html" title="Custom Memory Allocation">Custom Memory + Allocation</a> +</h4></div></div></div> +<p> + Many asynchronous operations need to allocate an object to store state + associated with the operation. For example, a Win32 implementation needs + <code class="computeroutput"><span class="identifier">OVERLAPPED</span></code>-derived objects + to pass to Win32 API functions. + </p> +<p> + Furthermore, programs typically contain easily identifiable chains of asynchronous + operations. A half duplex protocol implementation (e.g. an HTTP server) + would have a single chain of operations per client (receives followed by + sends). A full duplex protocol implementation would have two chains executing + in parallel. Programs should be able to leverage this knowledge to reuse + memory for all asynchronous operations in a chain. + </p> +<p> + Given a copy of a user-defined <code class="computeroutput"><span class="identifier">Handler</span></code> + object <code class="computeroutput"><span class="identifier">h</span></code>, if the implementation + needs to allocate memory associated with that handler it will execute the + code: + </p> +<pre class="programlisting"><span class="keyword">void</span><span class="special">*</span> <span class="identifier">pointer</span> <span class="special">=</span> <span class="identifier">asio_handler_allocate</span><span class="special">(</span><span class="identifier">size</span><span class="special">,</span> <span class="special">&</span><span class="identifier">h</span><span class="special">);</span> +</pre> +<p> + Similarly, to deallocate the memory it will execute: + </p> +<pre class="programlisting"><span class="identifier">asio_handler_deallocate</span><span class="special">(</span><span class="identifier">pointer</span><span class="special">,</span> <span class="identifier">size</span><span class="special">,</span> <span class="special">&</span><span class="identifier">h</span><span class="special">);</span> +</pre> +<p> + These functions are located using argument-dependent lookup. The implementation + provides default implementations of the above functions in the <code class="computeroutput"><span class="identifier">asio</span></code> namespace: + </p> +<pre class="programlisting"><span class="keyword">void</span><span class="special">*</span> <span class="identifier">asio_handler_allocate</span><span class="special">(</span><span class="identifier">size_t</span><span class="special">,</span> <span class="special">...);</span> +<span class="keyword">void</span> <span class="identifier">asio_handler_deallocate</span><span class="special">(</span><span class="keyword">void</span><span class="special">*,</span> <span class="identifier">size_t</span><span class="special">,</span> <span class="special">...);</span> +</pre> +<p> + which are implemented in terms of <code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span> <span class="keyword">new</span><span class="special">()</span></code> and <code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span> <span class="keyword">delete</span><span class="special">()</span></code> respectively. + </p> +<p> + The implementation guarantees that the deallocation will occur before the + associated handler is invoked, which means the memory is ready to be reused + for any new asynchronous operations started by the handler. + </p> +<p> + The custom memory allocation functions may be called from any user-created + thread that is calling a library function. The implementation guarantees + that, for the asynchronous operations included the library, the implementation + will not make concurrent calls to the memory allocation functions for that + handler. The implementation will insert appropriate memory barriers to + ensure correct memory visibility should allocation functions need to be + called from different threads. + </p> +<h6> +<a name="boost_asio.overview.core.allocation.h0"></a> + <span><a name="boost_asio.overview.core.allocation.see_also"></a></span><a class="link" href="allocation.html#boost_asio.overview.core.allocation.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/asio_handler_allocate.html" title="asio_handler_allocate">asio_handler_allocate</a>, + <a class="link" href="../../reference/asio_handler_deallocate.html" title="asio_handler_deallocate">asio_handler_deallocate</a>, + <a class="link" href="../../examples.html#boost_asio.examples.allocation">custom memory allocation + example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="line_based.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="handler_tracking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/async.html b/doc/html/boost_asio/overview/core/async.html new file mode 100755 index 0000000000..ac4cba040a --- /dev/null +++ b/doc/html/boost_asio/overview/core/async.html @@ -0,0 +1,288 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>The Proactor Design Pattern: Concurrency Without Threads</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="basics.html" title="Basic Boost.Asio Anatomy"> +<link rel="next" href="threads.html" title="Threads and Boost.Asio"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="basics.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="threads.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.async"></a><a class="link" href="async.html" title="The Proactor Design Pattern: Concurrency Without Threads">The Proactor Design + Pattern: Concurrency Without Threads</a> +</h4></div></div></div> +<p> + The Boost.Asio library offers side-by-side support for synchronous and + asynchronous operations. The asynchronous support is based on the Proactor + design pattern <a class="link" href="async.html#boost_asio.overview.core.async.references">[POSA2]</a>. + The advantages and disadvantages of this approach, when compared to a synchronous-only + or Reactor approach, are outlined below. + </p> +<h6> +<a name="boost_asio.overview.core.async.h0"></a> + <span><a name="boost_asio.overview.core.async.proactor_and_boost_asio"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.proactor_and_boost_asio">Proactor + and Boost.Asio</a> + </h6> +<p> + Let us examine how the Proactor design pattern is implemented in Boost.Asio, + without reference to platform-specific details. + </p> +<p> + <span class="inlinemediaobject"><img src="../../proactor.png" alt="proactor"></span> + </p> +<p> + <span class="bold"><strong>Proactor design pattern (adapted from [POSA2])</strong></span> + </p> +<p> + — Asynchronous Operation + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Defines an operation that is executed asynchronously, such as an asynchronous + read or write on a socket. + </p></blockquote></div> +<p> + — Asynchronous Operation Processor + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Executes asynchronous operations and queues events on a completion event + queue when operations complete. From a high-level point of view, services + like <code class="computeroutput"><span class="identifier">stream_socket_service</span></code> + are asynchronous operation processors. + </p></blockquote></div> +<p> + — Completion Event Queue + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Buffers completion events until they are dequeued by an asynchronous + event demultiplexer. + </p></blockquote></div> +<p> + — Completion Handler + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Processes the result of an asynchronous operation. These are function + objects, often created using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>. + </p></blockquote></div> +<p> + — Asynchronous Event Demultiplexer + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Blocks waiting for events to occur on the completion event queue, and + returns a completed event to its caller. + </p></blockquote></div> +<p> + — Proactor + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + 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 the <code class="computeroutput"><span class="identifier">io_service</span></code> class. + </p></blockquote></div> +<p> + — Initiator + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Application-specific code that starts asynchronous operations. The initiator + interacts with an asynchronous operation processor via a high-level interface + such as <code class="computeroutput"><span class="identifier">basic_stream_socket</span></code>, + which in turn delegates to a service like <code class="computeroutput"><span class="identifier">stream_socket_service</span></code>. + </p></blockquote></div> +<h6> +<a name="boost_asio.overview.core.async.h1"></a> + <span><a name="boost_asio.overview.core.async.implementation_using_reactor"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.implementation_using_reactor">Implementation + Using Reactor</a> + </h6> +<p> + On many platforms, Boost.Asio implements the Proactor design pattern in + terms of a Reactor, such as <code class="computeroutput"><span class="identifier">select</span></code>, + <code class="computeroutput"><span class="identifier">epoll</span></code> or <code class="computeroutput"><span class="identifier">kqueue</span></code>. This implementation approach + corresponds to the Proactor design pattern as follows: + </p> +<p> + — Asynchronous Operation Processor + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + A reactor implemented using <code class="computeroutput"><span class="identifier">select</span></code>, + <code class="computeroutput"><span class="identifier">epoll</span></code> or <code class="computeroutput"><span class="identifier">kqueue</span></code>. When the reactor indicates + that the resource is ready to perform the operation, the processor executes + the asynchronous operation and enqueues the associated completion handler + on the completion event queue. + </p></blockquote></div> +<p> + — Completion Event Queue + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + A linked list of completion handlers (i.e. function objects). + </p></blockquote></div> +<p> + — Asynchronous Event Demultiplexer + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + This is implemented by waiting on an event or condition variable until + a completion handler is available in the completion event queue. + </p></blockquote></div> +<h6> +<a name="boost_asio.overview.core.async.h2"></a> + <span><a name="boost_asio.overview.core.async.implementation_using_windows_overlapped_i_o"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.implementation_using_windows_overlapped_i_o">Implementation + Using Windows Overlapped I/O</a> + </h6> +<p> + On Windows NT, 2000 and XP, Boost.Asio takes advantage of overlapped I/O + to provide an efficient implementation of the Proactor design pattern. + This implementation approach corresponds to the Proactor design pattern + as follows: + </p> +<p> + — Asynchronous Operation Processor + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + This is implemented by the operating system. Operations are initiated + by calling an overlapped function such as <code class="computeroutput"><span class="identifier">AcceptEx</span></code>. + </p></blockquote></div> +<p> + — Completion Event Queue + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + 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 <code class="computeroutput"><span class="identifier">io_service</span></code> instance. + </p></blockquote></div> +<p> + — Asynchronous Event Demultiplexer + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Called by Boost.Asio to dequeue events and their associated completion + handlers. + </p></blockquote></div> +<h6> +<a name="boost_asio.overview.core.async.h3"></a> + <span><a name="boost_asio.overview.core.async.advantages"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.advantages">Advantages</a> + </h6> +<p> + — Portability. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Many operating systems offer a native asynchronous I/O API (such as overlapped + I/O on <span class="emphasis"><em>Windows</em></span>) as the preferred option for developing + high 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 <span class="emphasis"><em>POSIX</em></span> + <code class="computeroutput"><span class="identifier">select</span><span class="special">()</span></code>. + </p></blockquote></div> +<p> + — Decoupling threading from concurrency. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Long-duration operations are performed asynchronously by the implementation + on behalf of the application. Consequently applications do not need to + spawn many threads in order to increase concurrency. + </p></blockquote></div> +<p> + — Performance and scalability. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Implementation strategies such as thread-per-connection (which a synchronous-only + approach would require) can degrade system performance, due to increased + context switching, synchronisation and data movement among CPUs. With + asynchronous operations it is possible to avoid the cost of context switching + by minimising the number of operating system threads — typically a limited + resource — and only activating the logical threads of control that have + events to process. + </p></blockquote></div> +<p> + — Simplified application synchronisation. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Asynchronous operation completion handlers can be written as though they + exist in a single-threaded environment, and so application logic can + be developed with little or no concern for synchronisation issues. + </p></blockquote></div> +<p> + — Function composition. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Function composition refers to the implementation of functions to provide + a higher-level operation, such as sending a message in a particular format. + Each function is implemented in terms of multiple calls to lower-level + read or write operations. + </p></blockquote></div> +<div class="blockquote"><blockquote class="blockquote"><p> + For example, consider a protocol where each message consists of a fixed-length + header followed by a variable length body, where the length of the body + is specified in the header. A hypothetical read_message operation could + be implemented using two lower-level reads, the first to receive the + header and, once the length is known, the second to receive the body. + </p></blockquote></div> +<div class="blockquote"><blockquote class="blockquote"><p> + To compose functions in an asynchronous model, asynchronous operations + can be chained together. That is, a completion handler for one operation + can initiate the next. Starting the first call in the chain can be encapsulated + so that the caller need not be aware that the higher-level operation + is implemented as a chain of asynchronous operations. + </p></blockquote></div> +<div class="blockquote"><blockquote class="blockquote"><p> + The ability to compose new operations in this way simplifies the development + of higher levels of abstraction above a networking library, such as functions + to support a specific protocol. + </p></blockquote></div> +<h6> +<a name="boost_asio.overview.core.async.h4"></a> + <span><a name="boost_asio.overview.core.async.disadvantages"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.disadvantages">Disadvantages</a> + </h6> +<p> + — Program complexity. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + It is more difficult to develop applications using asynchronous mechanisms + due to the separation in time and space between operation initiation + and completion. Applications may also be harder to debug due to the inverted + flow of control. + </p></blockquote></div> +<p> + — Memory usage. + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + Buffer space must be committed for the duration of a read or write operation, + which may continue indefinitely, and a separate buffer is required for + each concurrent operation. The Reactor pattern, on the other hand, does + not require buffer space until a socket is ready for reading or writing. + </p></blockquote></div> +<h6> +<a name="boost_asio.overview.core.async.h5"></a> + <span><a name="boost_asio.overview.core.async.references"></a></span><a class="link" href="async.html#boost_asio.overview.core.async.references">References</a> + </h6> +<p> + [POSA2] D. Schmidt et al, <span class="emphasis"><em>Pattern Oriented Software Architecture, + Volume 2</em></span>. Wiley, 2000. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="basics.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="threads.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/basics.html b/doc/html/boost_asio/overview/core/basics.html new file mode 100755 index 0000000000..3cf5cd840f --- /dev/null +++ b/doc/html/boost_asio/overview/core/basics.html @@ -0,0 +1,173 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Basic Boost.Asio Anatomy</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="../core.html" title="Core Concepts and Functionality"> +<link rel="next" href="async.html" title="The Proactor Design Pattern: Concurrency Without Threads"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../core.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="async.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.basics"></a><a class="link" href="basics.html" title="Basic Boost.Asio Anatomy">Basic Boost.Asio Anatomy</a> +</h4></div></div></div> +<p> + Boost.Asio may be used to perform both synchronous and asynchronous operations + on I/O objects such as sockets. Before using Boost.Asio it may be useful + to get a conceptual picture of the various parts of Boost.Asio, your program, + and how they work together. + </p> +<p> + As an introductory example, let's consider what happens when you perform + a connect operation on a socket. We shall start by examining synchronous + operations. + </p> +<p> + <span class="inlinemediaobject"><img src="../../sync_op.png" alt="sync_op"></span> + </p> +<p> + <span class="bold"><strong>Your program</strong></span> will have at least one <span class="bold"><strong>io_service</strong></span> object. The <span class="bold"><strong>io_service</strong></span> + represents <span class="bold"><strong>your program</strong></span>'s link to the + <span class="bold"><strong>operating system</strong></span>'s I/O services. + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span> <span class="identifier">io_service</span><span class="special">;</span> +</pre> +<p> + To perform I/O operations <span class="bold"><strong>your program</strong></span> + will need an <span class="bold"><strong>I/O object</strong></span> such as a TCP + socket: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">);</span> +</pre> +<p> + When a synchronous connect operation is performed, the following sequence + of events occurs: + </p> +<p> + 1. <span class="bold"><strong>Your program</strong></span> initiates the connect + operation by calling the <span class="bold"><strong>I/O object</strong></span>: + </p> +<pre class="programlisting"><span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">);</span> +</pre> +<p> + 2. The <span class="bold"><strong>I/O object</strong></span> forwards the request + to the <span class="bold"><strong>io_service</strong></span>. + </p> +<p> + 3. The <span class="bold"><strong>io_service</strong></span> calls on the <span class="bold"><strong>operating system</strong></span> to perform the connect operation. + </p> +<p> + 4. The <span class="bold"><strong>operating system</strong></span> returns the result + of the operation to the <span class="bold"><strong>io_service</strong></span>. + </p> +<p> + 5. The <span class="bold"><strong>io_service</strong></span> translates any error + resulting from the operation into an object of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span></code>. + An <code class="computeroutput"><span class="identifier">error_code</span></code> may be compared + with specific values, or tested as a boolean (where a <code class="computeroutput"><span class="keyword">false</span></code> + result means that no error occurred). The result is then forwarded back + up to the <span class="bold"><strong>I/O object</strong></span>. + </p> +<p> + 6. The <span class="bold"><strong>I/O object</strong></span> throws an exception + of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">system_error</span></code> if the operation failed. + If the code to initiate the operation had instead been written as: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span> +<span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span> +</pre> +<p> + then the <code class="computeroutput"><span class="identifier">error_code</span></code> variable + <code class="computeroutput"><span class="identifier">ec</span></code> would be set to the + result of the operation, and no exception would be thrown. + </p> +<p> + When an asynchronous operation is used, a different sequence of events + occurs. + </p> +<p> + <span class="inlinemediaobject"><img src="../../async_op1.png" alt="async_op1"></span> + </p> +<p> + 1. <span class="bold"><strong>Your program</strong></span> initiates the connect + operation by calling the <span class="bold"><strong>I/O object</strong></span>: + </p> +<pre class="programlisting"><span class="identifier">socket</span><span class="special">.</span><span class="identifier">async_connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">,</span> <span class="identifier">your_completion_handler</span><span class="special">);</span> +</pre> +<p> + where <code class="computeroutput"><span class="identifier">your_completion_handler</span></code> + is a function or function object with the signature: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">your_completion_handler</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">);</span> +</pre> +<p> + The exact signature required depends on the asynchronous operation being + performed. The reference documentation indicates the appropriate form for + each operation. + </p> +<p> + 2. The <span class="bold"><strong>I/O object</strong></span> forwards the request + to the <span class="bold"><strong>io_service</strong></span>. + </p> +<p> + 3. The <span class="bold"><strong>io_service</strong></span> signals to the <span class="bold"><strong>operating system</strong></span> that it should start an asynchronous + connect. + </p> +<p> + Time passes. (In the synchronous case this wait would have been contained + entirely within the duration of the connect operation.) + </p> +<p> + <span class="inlinemediaobject"><img src="../../async_op2.png" alt="async_op2"></span> + </p> +<p> + 4. The <span class="bold"><strong>operating system</strong></span> indicates that + the connect operation has completed by placing the result on a queue, ready + to be picked up by the <span class="bold"><strong>io_service</strong></span>. + </p> +<p> + 5. <span class="bold"><strong>Your program</strong></span> must make a call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> + (or to one of the similar <span class="bold"><strong>io_service</strong></span> member + functions) in order for the result to be retrieved. A call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> + blocks while there are unfinished asynchronous operations, so you would + typically call it as soon as you have started your first asynchronous operation. + </p> +<p> + 6. While inside the call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, the <span class="bold"><strong>io_service</strong></span> + dequeues the result of the operation, translates it into an <code class="computeroutput"><span class="identifier">error_code</span></code>, and then passes it to <span class="bold"><strong>your completion handler</strong></span>. + </p> +<p> + This is a simplified picture of how Boost.Asio operates. You will want + to delve further into the documentation if your needs are more advanced, + such as extending Boost.Asio to perform other types of asynchronous operations. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../core.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="async.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/buffers.html b/doc/html/boost_asio/overview/core/buffers.html new file mode 100755 index 0000000000..64e4ff712a --- /dev/null +++ b/doc/html/boost_asio/overview/core/buffers.html @@ -0,0 +1,244 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Buffers</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="strands.html" title="Strands: Use Threads Without Explicit Locking"> +<link rel="next" href="streams.html" title="Streams, Short Reads and Short Writes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="strands.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="streams.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.buffers"></a><a class="link" href="buffers.html" title="Buffers">Buffers</a> +</h4></div></div></div> +<p> + 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: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + A scatter-read receives data into multiple buffers. + </li> +<li class="listitem"> + A gather-write transmits multiple buffers. + </li> +</ul></div> +<p> + 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. + </p> +<p> + 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: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="keyword">void</span><span class="special">*,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">></span> <span class="identifier">mutable_buffer</span><span class="special">;</span> +<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">></span> <span class="identifier">const_buffer</span><span class="special">;</span> +</pre> +<p> + Here, a mutable_buffer would be convertible to a const_buffer, but conversion + in the opposite direction is not valid. + </p> +<p> + However, Boost.Asio does not use the above definitions as-is, but instead + defines two classes: <code class="computeroutput"><span class="identifier">mutable_buffer</span></code> + and <code class="computeroutput"><span class="identifier">const_buffer</span></code>. The goal + of these is to provide an opaque representation of contiguous memory, where: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Types behave as std::pair would in conversions. That is, a <code class="computeroutput"><span class="identifier">mutable_buffer</span></code> is convertible to + a <code class="computeroutput"><span class="identifier">const_buffer</span></code>, but + the opposite conversion is disallowed. + </li> +<li class="listitem"> + 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, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span></code> + or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> of POD elements, or from a + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>. + </li> +<li class="listitem"> + Type safety violations must be explicitly requested using the <code class="computeroutput"><span class="identifier">buffer_cast</span></code> 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. + </li> +</ul></div> +<p> + Finally, multiple buffers can be passed to scatter-gather operations (such + as <a class="link" href="../../reference/read.html" title="read">read()</a> or <a class="link" href="../../reference/write.html" title="write">write()</a>) + by putting the buffer objects into a container. The <code class="computeroutput"><span class="identifier">MutableBufferSequence</span></code> + and <code class="computeroutput"><span class="identifier">ConstBufferSequence</span></code> + concepts have been defined so that containers such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>, + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span></code>, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> + or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span></code> can be used. + </p> +<h6> +<a name="boost_asio.overview.core.buffers.h0"></a> + <span><a name="boost_asio.overview.core.buffers.streambuf_for_integration_with_iostreams"></a></span><a class="link" href="buffers.html#boost_asio.overview.core.buffers.streambuf_for_integration_with_iostreams">Streambuf + for Integration with Iostreams</a> + </h6> +<p> + The class <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">basic_streambuf</span></code> is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_streambuf</span></code> 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: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + The input sequence of the streambuf is accessible via the <a class="link" href="../../reference/basic_streambuf/data.html" title="basic_streambuf::data">data()</a> + member function. The return type of this function meets the <code class="computeroutput"><span class="identifier">ConstBufferSequence</span></code> requirements. + </li> +<li class="listitem"> + The output sequence of the streambuf is accessible via the <a class="link" href="../../reference/basic_streambuf/data.html" title="basic_streambuf::data">prepare()</a> + member function. The return type of this function meets the <code class="computeroutput"><span class="identifier">MutableBufferSequence</span></code> requirements. + </li> +<li class="listitem"> + Data is transferred from the front of the output sequence to the back + of the input sequence by calling the <a class="link" href="../../reference/basic_streambuf/commit.html" title="basic_streambuf::commit">commit()</a> + member function. + </li> +<li class="listitem"> + Data is removed from the front of the input sequence by calling the + <a class="link" href="../../reference/basic_streambuf/consume.html" title="basic_streambuf::consume">consume()</a> + member function. + </li> +</ul></div> +<p> + The streambuf constructor accepts a <code class="computeroutput"><span class="identifier">size_t</span></code> + 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 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">length_error</span></code> + exception. + </p> +<h6> +<a name="boost_asio.overview.core.buffers.h1"></a> + <span><a name="boost_asio.overview.core.buffers.bytewise_traversal_of_buffer_sequences"></a></span><a class="link" href="buffers.html#boost_asio.overview.core.buffers.bytewise_traversal_of_buffer_sequences">Bytewise + Traversal of Buffer Sequences</a> + </h6> +<p> + The <code class="computeroutput"><span class="identifier">buffers_iterator</span><span class="special"><></span></code> + class template allows buffer sequences (i.e. types meeting <code class="computeroutput"><span class="identifier">MutableBufferSequence</span></code> or <code class="computeroutput"><span class="identifier">ConstBufferSequence</span></code> 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. + </p> +<p> + As an example, to read a single line from a socket and into a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>, you may write: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">sb</span><span class="special">;</span> +<span class="special">...</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read_until</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">sb</span><span class="special">,</span> <span class="char">'\n'</span><span class="special">);</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span><span class="special">::</span><span class="identifier">const_buffers_type</span> <span class="identifier">bufs</span> <span class="special">=</span> <span class="identifier">sb</span><span class="special">.</span><span class="identifier">data</span><span class="special">();</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">line</span><span class="special">(</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffers_begin</span><span class="special">(</span><span class="identifier">bufs</span><span class="special">),</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffers_begin</span><span class="special">(</span><span class="identifier">bufs</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">n</span><span class="special">);</span> +</pre> +<h6> +<a name="boost_asio.overview.core.buffers.h2"></a> + <span><a name="boost_asio.overview.core.buffers.buffer_debugging"></a></span><a class="link" href="buffers.html#boost_asio.overview.core.buffers.buffer_debugging">Buffer + Debugging</a> + </h6> +<p> + 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: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">v</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">>::</span><span class="identifier">iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> +<span class="identifier">v</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span> <span class="comment">// invalidates iterators</span> +<span class="special">*</span><span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// assertion!</span> +</pre> +<p> + Boost.Asio takes advantage of this feature to add buffer debugging. Consider + the following code: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">dont_do_this</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span> <span class="special">=</span> <span class="string">"Hello, world!"</span><span class="special">;</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_write</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffer</span><span class="special">(</span><span class="identifier">msg</span><span class="special">),</span> <span class="identifier">my_handler</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + 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 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> + variable <code class="computeroutput"><span class="identifier">msg</span></code>. 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. + </p> +<p> + 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. + </p> +<p> + This feature is automatically made available for Microsoft Visual Studio + 8.0 or later and for GCC when <code class="computeroutput"><span class="identifier">_GLIBCXX_DEBUG</span></code> + 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 <code class="computeroutput"><span class="identifier">BOOST_ASIO_ENABLE_BUFFER_DEBUGGING</span></code>. + It can also be explicitly disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_BUFFER_DEBUGGING</span></code>. + </p> +<h6> +<a name="boost_asio.overview.core.buffers.h3"></a> + <span><a name="boost_asio.overview.core.buffers.see_also"></a></span><a class="link" href="buffers.html#boost_asio.overview.core.buffers.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/buffer.html" title="buffer">buffer</a>, <a class="link" href="../../reference/buffers_begin.html" title="buffers_begin">buffers_begin</a>, + <a class="link" href="../../reference/buffers_end.html" title="buffers_end">buffers_end</a>, <a class="link" href="../../reference/buffers_iterator.html" title="buffers_iterator">buffers_iterator</a>, + <a class="link" href="../../reference/const_buffer.html" title="const_buffer">const_buffer</a>, + <a class="link" href="../../reference/const_buffers_1.html" title="const_buffers_1">const_buffers_1</a>, + <a class="link" href="../../reference/mutable_buffer.html" title="mutable_buffer">mutable_buffer</a>, + <a class="link" href="../../reference/mutable_buffers_1.html" title="mutable_buffers_1">mutable_buffers_1</a>, + <a class="link" href="../../reference/streambuf.html" title="streambuf">streambuf</a>, <a class="link" href="../../reference/ConstBufferSequence.html" title="Constant buffer sequence requirements">ConstBufferSequence</a>, + <a class="link" href="../../reference/MutableBufferSequence.html" title="Mutable buffer sequence requirements">MutableBufferSequence</a>, + <a class="link" href="../../examples.html#boost_asio.examples.buffers">buffers example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="strands.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="streams.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/handler_tracking.html b/doc/html/boost_asio/overview/core/handler_tracking.html new file mode 100755 index 0000000000..fa95ed83a1 --- /dev/null +++ b/doc/html/boost_asio/overview/core/handler_tracking.html @@ -0,0 +1,151 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Handler Tracking</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="allocation.html" title="Custom Memory Allocation"> +<link rel="next" href="../networking.html" title="Networking"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="allocation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../networking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.handler_tracking"></a><a class="link" href="handler_tracking.html" title="Handler Tracking">Handler + Tracking</a> +</h4></div></div></div> +<p> + To aid in debugging asynchronous programs, Boost.Asio provides support + for handler tracking. When enabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_ENABLE_HANDLER_TRACKING</span></code>, + Boost.Asio writes debugging output to the standard error stream. The output + records asynchronous operations and the relationships between their handlers. + </p> +<p> + This feature is useful when debugging and you need to know how your asynchronous + operations are chained together, or what the pending asynchronous operations + are. As an illustration, here is the output when you run the HTTP Server + example, handle a single request, then shut down via Ctrl+C: + </p> +<pre class="programlisting">@asio|1298160085.070638|0*1|signal_set@0x7fff50528f40.async_wait +@asio|1298160085.070888|0*2|socket@0x7fff50528f60.async_accept +@asio|1298160085.070913|0|resolver@0x7fff50528e28.cancel +@asio|1298160118.075438|>2|ec=asio.system:0 +@asio|1298160118.075472|2*3|socket@0xb39048.async_receive +@asio|1298160118.075507|2*4|socket@0x7fff50528f60.async_accept +@asio|1298160118.075527|<2| +@asio|1298160118.075540|>3|ec=asio.system:0,bytes_transferred=122 +@asio|1298160118.075731|3*5|socket@0xb39048.async_send +@asio|1298160118.075778|<3| +@asio|1298160118.075793|>5|ec=asio.system:0,bytes_transferred=156 +@asio|1298160118.075831|5|socket@0xb39048.close +@asio|1298160118.075855|<5| +@asio|1298160122.827317|>1|ec=asio.system:0,signal_number=2 +@asio|1298160122.827333|1|socket@0x7fff50528f60.close +@asio|1298160122.827359|<1| +@asio|1298160122.827370|>4|ec=asio.system:125 +@asio|1298160122.827378|<4| +@asio|1298160122.827394|0|signal_set@0x7fff50528f40.cancel +</pre> +<p> + Each line is of the form: + </p> +<pre class="programlisting"><tag>|<timestamp>|<action>|<description> +</pre> +<p> + The <code class="computeroutput"><tag></code> is always <code class="computeroutput">@asio</code>, and is used + to identify and extract the handler tracking messages from the program + output. + </p> +<p> + The <code class="computeroutput"><timestamp></code> is seconds and microseconds from 1 Jan + 1970 UTC. + </p> +<p> + The <code class="computeroutput"><action></code> takes one of the following forms: + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl> +<dt><span class="term">>n</span></dt> +<dd><p> + The program entered the handler number <code class="computeroutput">n</code>. The <code class="computeroutput"><description></code> + shows the arguments to the handler. + </p></dd> +<dt><span class="term"><n</span></dt> +<dd><p> + The program left handler number <code class="computeroutput">n</code>. + </p></dd> +<dt><span class="term">!n</span></dt> +<dd><p> + The program left handler number n due to an exception. + </p></dd> +<dt><span class="term">~n</span></dt> +<dd><p> + The handler number <code class="computeroutput">n</code> was destroyed without having been + invoked. This is usually the case for any unfinished asynchronous + operations when the <code class="computeroutput">io_service</code> is destroyed. + </p></dd> +<dt><span class="term">n*m</span></dt> +<dd><p> + The handler number <code class="computeroutput">n</code> created a new asynchronous operation + with completion handler number <code class="computeroutput">m</code>. The <code class="computeroutput"><description></code> + shows what asynchronous operation was started. + </p></dd> +<dt><span class="term">n</span></dt> +<dd><p> + The handler number n performed some other operation. The <code class="computeroutput"><description></code> + shows what function was called. Currently only <code class="computeroutput">close()</code> + and <code class="computeroutput">cancel()</code> operations are logged, as these may affect + the state of pending asynchronous operations. + </p></dd> +</dl> +</div> +<p> + Where the <code class="computeroutput"><description></code> shows a synchronous or asynchronous + operation, the format is <code class="computeroutput"><object-type>@<pointer>.<operation></code>. + For handler entry, it shows a comma-separated list of arguments and their + values. + </p> +<p> + As shown above, Each handler is assigned a numeric identifier. Where the + handler tracking output shows a handler number of 0, it means that the + action was performed outside of any handler. + </p> +<h6> +<a name="boost_asio.overview.core.handler_tracking.h0"></a> + <span><a name="boost_asio.overview.core.handler_tracking.visual_representations"></a></span><a class="link" href="handler_tracking.html#boost_asio.overview.core.handler_tracking.visual_representations">Visual + Representations</a> + </h6> +<p> + The handler tracking output may be post-processed using the included <code class="literal">handlerviz.pl</code> + tool to create a visual representation of the handlers (requires the GraphViz + tool <code class="literal">dot</code>). + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="allocation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../networking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/line_based.html b/doc/html/boost_asio/overview/core/line_based.html new file mode 100755 index 0000000000..4f222ba44b --- /dev/null +++ b/doc/html/boost_asio/overview/core/line_based.html @@ -0,0 +1,164 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Line-Based Operations</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="reactor.html" title="Reactor-Style Operations"> +<link rel="next" href="allocation.html" title="Custom Memory Allocation"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="reactor.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="allocation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.line_based"></a><a class="link" href="line_based.html" title="Line-Based Operations">Line-Based Operations</a> +</h4></div></div></div> +<p> + Many commonly-used internet protocols are line-based, which means that + they have protocol elements that are delimited by the character sequence + <code class="computeroutput"><span class="string">"\r\n"</span></code>. 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 <code class="computeroutput"><span class="identifier">read_until</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">async_read_until</span><span class="special">()</span></code>. + </p> +<p> + The following example illustrates the use of <code class="computeroutput"><span class="identifier">async_read_until</span><span class="special">()</span></code> in an HTTP server, to receive the first + line of an HTTP request from a client: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">http_connection</span> +<span class="special">{</span> + <span class="special">...</span> + + <span class="keyword">void</span> <span class="identifier">start</span><span class="special">()</span> + <span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_read_until</span><span class="special">(</span><span class="identifier">socket_</span><span class="special">,</span> <span class="identifier">data_</span><span class="special">,</span> <span class="string">"\r\n"</span><span class="special">,</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">http_connection</span><span class="special">::</span><span class="identifier">handle_request_line</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">));</span> + <span class="special">}</span> + + <span class="keyword">void</span> <span class="identifier">handle_request_line</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ec</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">method</span><span class="special">,</span> <span class="identifier">uri</span><span class="special">,</span> <span class="identifier">version</span><span class="special">;</span> + <span class="keyword">char</span> <span class="identifier">sp1</span><span class="special">,</span> <span class="identifier">sp2</span><span class="special">,</span> <span class="identifier">cr</span><span class="special">,</span> <span class="identifier">lf</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span> <span class="identifier">is</span><span class="special">(&</span><span class="identifier">data_</span><span class="special">);</span> + <span class="identifier">is</span><span class="special">.</span><span class="identifier">unsetf</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">skipws</span><span class="special">);</span> + <span class="identifier">is</span> <span class="special">>></span> <span class="identifier">method</span> <span class="special">>></span> <span class="identifier">sp1</span> <span class="special">>></span> <span class="identifier">uri</span> <span class="special">>></span> <span class="identifier">sp2</span> <span class="special">>></span> <span class="identifier">version</span> <span class="special">>></span> <span class="identifier">cr</span> <span class="special">>></span> <span class="identifier">lf</span><span class="special">;</span> + <span class="special">...</span> + <span class="special">}</span> + <span class="special">}</span> + + <span class="special">...</span> + + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket_</span><span class="special">;</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">data_</span><span class="special">;</span> +<span class="special">};</span> +</pre> +<p> + The <code class="computeroutput"><span class="identifier">streambuf</span></code> 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 <span class="emphasis"><em>after</em></span> the delimiter. + This surplus data should be left in the <code class="computeroutput"><span class="identifier">streambuf</span></code> + so that it may be inspected by a subsequent call to <code class="computeroutput"><span class="identifier">read_until</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">async_read_until</span><span class="special">()</span></code>. + </p> +<p> + The delimiters may be specified as a single <code class="computeroutput"><span class="keyword">char</span></code>, + a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> or a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">regex</span></code>. + The <code class="computeroutput"><span class="identifier">read_until</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">async_read_until</span><span class="special">()</span></code> + 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: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffers_iterator</span><span class="special"><</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span><span class="special">::</span><span class="identifier">const_buffers_type</span><span class="special">></span> <span class="identifier">iterator</span><span class="special">;</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">iterator</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">></span> +<span class="identifier">match_whitespace</span><span class="special">(</span><span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">begin</span><span class="special">;</span> + <span class="keyword">while</span> <span class="special">(</span><span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">)</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">isspace</span><span class="special">(*</span><span class="identifier">i</span><span class="special">++))</span> + <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="keyword">true</span><span class="special">);</span> + <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span> +<span class="special">}</span> +<span class="special">...</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">b</span><span class="special">;</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read_until</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">match_whitespace</span><span class="special">);</span> +</pre> +<p> + To read data into a streambuf until a matching character is found: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">match_char</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">explicit</span> <span class="identifier">match_char</span><span class="special">(</span><span class="keyword">char</span> <span class="identifier">c</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">c_</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">{}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">></span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">></span> <span class="keyword">operator</span><span class="special">()(</span> + <span class="identifier">Iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span> + <span class="special">{</span> + <span class="identifier">Iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">begin</span><span class="special">;</span> + <span class="keyword">while</span> <span class="special">(</span><span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">)</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">c_</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">i</span><span class="special">++)</span> + <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="keyword">true</span><span class="special">);</span> + <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span> + <span class="special">}</span> + +<span class="keyword">private</span><span class="special">:</span> + <span class="keyword">char</span> <span class="identifier">c_</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">asio</span> <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><></span> <span class="keyword">struct</span> <span class="identifier">is_match_condition</span><span class="special"><</span><span class="identifier">match_char</span><span class="special">></span> + <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">true_type</span> <span class="special">{};</span> +<span class="special">}</span> <span class="special">}</span> <span class="comment">// namespace boost::asio</span> +<span class="special">...</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">b</span><span class="special">;</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read_until</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">match_char</span><span class="special">(</span><span class="char">'a'</span><span class="special">));</span> +</pre> +<p> + The <code class="computeroutput"><span class="identifier">is_match_condition</span><span class="special"><></span></code> type trait automatically evaluates + to true for functions, and for function objects with a nested <code class="computeroutput"><span class="identifier">result_type</span></code> typedef. For other types + the trait must be explicitly specialised, as shown above. + </p> +<h6> +<a name="boost_asio.overview.core.line_based.h0"></a> + <span><a name="boost_asio.overview.core.line_based.see_also"></a></span><a class="link" href="line_based.html#boost_asio.overview.core.line_based.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/async_read_until.html" title="async_read_until">async_read_until()</a>, + <a class="link" href="../../reference/is_match_condition.html" title="is_match_condition">is_match_condition</a>, + <a class="link" href="../../reference/read_until.html" title="read_until">read_until()</a>, <a class="link" href="../../reference/streambuf.html" title="streambuf">streambuf</a>, <a class="link" href="../../examples.html#boost_asio.examples.http_client">HTTP + client example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="reactor.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="allocation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/reactor.html b/doc/html/boost_asio/overview/core/reactor.html new file mode 100755 index 0000000000..29ee39a98d --- /dev/null +++ b/doc/html/boost_asio/overview/core/reactor.html @@ -0,0 +1,84 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Reactor-Style Operations</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="streams.html" title="Streams, Short Reads and Short Writes"> +<link rel="next" href="line_based.html" title="Line-Based Operations"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="streams.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="line_based.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.reactor"></a><a class="link" href="reactor.html" title="Reactor-Style Operations">Reactor-Style Operations</a> +</h4></div></div></div> +<p> + 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 <code class="computeroutput"><span class="identifier">null_buffers</span></code> + type that can be used with both read and write operations. A <code class="computeroutput"><span class="identifier">null_buffers</span></code> operation doesn't return + until the I/O object is "ready" to perform the operation. + </p> +<p> + As an example, to perform a non-blocking read something like the following + may be used: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="special">...</span> +<span class="identifier">socket</span><span class="special">.</span><span class="identifier">non_blocking</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span> +<span class="special">...</span> +<span class="identifier">socket</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">null_buffers</span><span class="special">(),</span> <span class="identifier">read_handler</span><span class="special">);</span> +<span class="special">...</span> +<span class="keyword">void</span> <span class="identifier">read_handler</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ec</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">char</span><span class="special">></span> <span class="identifier">buf</span><span class="special">(</span><span class="identifier">socket</span><span class="special">.</span><span class="identifier">available</span><span class="special">());</span> + <span class="identifier">socket</span><span class="special">.</span><span class="identifier">read_some</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">(</span><span class="identifier">buf</span><span class="special">));</span> + <span class="special">}</span> +<span class="special">}</span> +</pre> +<p> + These operations are supported for sockets on all platforms, and for the + POSIX stream-oriented descriptor classes. + </p> +<h6> +<a name="boost_asio.overview.core.reactor.h0"></a> + <span><a name="boost_asio.overview.core.reactor.see_also"></a></span><a class="link" href="reactor.html#boost_asio.overview.core.reactor.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/null_buffers.html" title="null_buffers">null_buffers</a>, + <a class="link" href="../../reference/basic_socket/non_blocking.html" title="basic_socket::non_blocking">basic_socket::non_blocking()</a>, + <a class="link" href="../../reference/basic_socket/native_non_blocking.html" title="basic_socket::native_non_blocking">basic_socket::native_non_blocking()</a>, + <a class="link" href="../../examples.html#boost_asio.examples.nonblocking">nonblocking example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="streams.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="line_based.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/strands.html b/doc/html/boost_asio/overview/core/strands.html new file mode 100755 index 0000000000..34ca281747 --- /dev/null +++ b/doc/html/boost_asio/overview/core/strands.html @@ -0,0 +1,111 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Strands: Use Threads Without Explicit Locking</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="threads.html" title="Threads and Boost.Asio"> +<link rel="next" href="buffers.html" title="Buffers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="threads.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="buffers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.strands"></a><a class="link" href="strands.html" title="Strands: Use Threads Without Explicit Locking">Strands: Use Threads + Without Explicit Locking</a> +</h4></div></div></div> +<p> + 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 multithreaded program without the need for explicit locking (e.g. + using mutexes). + </p> +<p> + Strands may be either implicit or explicit, as illustrated by the following + alternative approaches: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Calling io_service::run() from only one thread means all event handlers + execute in an implicit strand, due to the io_service's guarantee that + handlers are only invoked from inside run(). + </li> +<li class="listitem"> + Where there is a single chain of asynchronous operations associated + with a connection (e.g. in a half duplex protocol implementation like + HTTP) there is no possibility of concurrent execution of the handlers. + This is an implicit strand. + </li> +<li class="listitem"> + An explicit strand is an instance of <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">strand</span></code>. + All event handler function objects need to be wrapped using <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">strand</span><span class="special">::</span><span class="identifier">wrap</span><span class="special">()</span></code> + or otherwise posted/dispatched through the <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">strand</span></code> + object. + </li> +</ul></div> +<p> + In the case of composed asynchronous operations, such as <code class="computeroutput"><span class="identifier">async_read</span><span class="special">()</span></code> + or <code class="computeroutput"><span class="identifier">async_read_until</span><span class="special">()</span></code>, + if a completion handler goes through a strand, then all intermediate handlers + should also go through the same strand. This is needed to ensure thread + safe access for any objects that are shared between the caller and the + composed operation (in the case of <code class="computeroutput"><span class="identifier">async_read</span><span class="special">()</span></code> it's the socket, which the caller can + close() to cancel the operation). This is done by having hook functions + for all intermediate handlers which forward the calls to the customisable + hook associated with the final handler: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_handler</span> +<span class="special">{</span> + <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">asio_handler_invoke</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">my_handler</span><span class="special">*)</span> +<span class="special">{</span> + <span class="comment">// Do custom invocation here.</span> + <span class="comment">// Default implementation calls f();</span> +<span class="special">}</span> +</pre> +<p> + The <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">strand</span><span class="special">::</span><span class="identifier">wrap</span><span class="special">()</span></code> + function creates a new completion handler that defines <code class="computeroutput"><span class="identifier">asio_handler_invoke</span></code> + so that the function object is executed through the strand. + </p> +<h6> +<a name="boost_asio.overview.core.strands.h0"></a> + <span><a name="boost_asio.overview.core.strands.see_also"></a></span><a class="link" href="strands.html#boost_asio.overview.core.strands.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/io_service__strand.html" title="io_service::strand">io_service::strand</a>, + <a class="link" href="../../tutorial/tuttimer5.html" title="Timer.5 - Synchronising handlers in multithreaded programs">tutorial Timer.5</a>, + <a class="link" href="../../examples.html#boost_asio.examples.http_server_3">HTTP server 3 example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="threads.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="buffers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/streams.html b/doc/html/boost_asio/overview/core/streams.html new file mode 100755 index 0000000000..f997143e01 --- /dev/null +++ b/doc/html/boost_asio/overview/core/streams.html @@ -0,0 +1,127 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Streams, Short Reads and Short Writes</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="buffers.html" title="Buffers"> +<link rel="next" href="reactor.html" title="Reactor-Style Operations"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="buffers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reactor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.streams"></a><a class="link" href="streams.html" title="Streams, Short Reads and Short Writes">Streams, Short Reads + and Short Writes</a> +</h4></div></div></div> +<p> + Many I/O objects in Boost.Asio are stream-oriented. This means that: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + There are no message boundaries. The data being transferred is a continuous + sequence of bytes. + </li> +<li class="listitem"> + Read or write operations may transfer fewer bytes than requested. This + is referred to as a short read or short write. + </li> +</ul></div> +<p> + Objects that provide stream-oriented I/O model one or more of the following + type requirements: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">SyncReadStream</span></code>, where + synchronous read operations are performed using a member function called + <code class="computeroutput"><span class="identifier">read_some</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">AsyncReadStream</span></code>, where + asynchronous read operations are performed using a member function + called <code class="computeroutput"><span class="identifier">async_read_some</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">SyncWriteStream</span></code>, where + synchronous write operations are performed using a member function + called <code class="computeroutput"><span class="identifier">write_some</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">AsyncWriteStream</span></code>, where + synchronous write operations are performed using a member function + called <code class="computeroutput"><span class="identifier">async_write_some</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Examples of stream-oriented I/O objects include <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span></code>, + <code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special"><></span></code>, + <code class="computeroutput"><span class="identifier">posix</span><span class="special">::</span><span class="identifier">stream_descriptor</span></code>, <code class="computeroutput"><span class="identifier">windows</span><span class="special">::</span><span class="identifier">stream_handle</span></code>, + etc. + </p> +<p> + 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: <code class="computeroutput"><span class="identifier">read</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">async_read</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">write</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">async_write</span><span class="special">()</span></code>. + </p> +<h6> +<a name="boost_asio.overview.core.streams.h0"></a> + <span><a name="boost_asio.overview.core.streams.why_eof_is_an_error"></a></span><a class="link" href="streams.html#boost_asio.overview.core.streams.why_eof_is_an_error">Why EOF + is an Error</a> + </h6> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + The end of a stream can cause <code class="computeroutput"><span class="identifier">read</span></code>, + <code class="computeroutput"><span class="identifier">async_read</span></code>, <code class="computeroutput"><span class="identifier">read_until</span></code> or <code class="computeroutput"><span class="identifier">async_read_until</span></code> + functions to violate their contract. E.g. a read of N bytes may finish + early due to EOF. + </li> +<li class="listitem"> + An EOF error may be used to distinguish the end of a stream from a + successful read of size 0. + </li> +</ul></div> +<h6> +<a name="boost_asio.overview.core.streams.h1"></a> + <span><a name="boost_asio.overview.core.streams.see_also"></a></span><a class="link" href="streams.html#boost_asio.overview.core.streams.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../../reference/async_write.html" title="async_write">async_write()</a>, <a class="link" href="../../reference/read.html" title="read">read()</a>, <a class="link" href="../../reference/write.html" title="write">write()</a>, + <a class="link" href="../../reference/AsyncReadStream.html" title="Buffer-oriented asynchronous read stream requirements">AsyncReadStream</a>, + <a class="link" href="../../reference/AsyncWriteStream.html" title="Buffer-oriented asynchronous write stream requirements">AsyncWriteStream</a>, + <a class="link" href="../../reference/SyncReadStream.html" title="Buffer-oriented synchronous read stream requirements">SyncReadStream</a>, + <a class="link" href="../../reference/SyncWriteStream.html" title="Buffer-oriented synchronous write stream requirements">SyncWriteStream</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="buffers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reactor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/core/threads.html b/doc/html/boost_asio/overview/core/threads.html new file mode 100755 index 0000000000..0ab13bd707 --- /dev/null +++ b/doc/html/boost_asio/overview/core/threads.html @@ -0,0 +1,130 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Threads and Boost.Asio</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../core.html" title="Core Concepts and Functionality"> +<link rel="prev" href="async.html" title="The Proactor Design Pattern: Concurrency Without Threads"> +<link rel="next" href="strands.html" title="Strands: Use Threads Without Explicit Locking"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="async.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="strands.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.core.threads"></a><a class="link" href="threads.html" title="Threads and Boost.Asio">Threads and Boost.Asio</a> +</h4></div></div></div> +<h6> +<a name="boost_asio.overview.core.threads.h0"></a> + <span><a name="boost_asio.overview.core.threads.thread_safety"></a></span><a class="link" href="threads.html#boost_asio.overview.core.threads.thread_safety">Thread + Safety</a> + </h6> +<p> + In general, it is safe to make concurrent use of distinct objects, but + unsafe to make concurrent use of a single object. However, types such as + <code class="computeroutput"><span class="identifier">io_service</span></code> provide a stronger + guarantee that it is safe to use a single object concurrently. + </p> +<h6> +<a name="boost_asio.overview.core.threads.h1"></a> + <span><a name="boost_asio.overview.core.threads.thread_pools"></a></span><a class="link" href="threads.html#boost_asio.overview.core.threads.thread_pools">Thread + Pools</a> + </h6> +<p> + Multiple threads may call <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> to set up a pool of threads from which + completion handlers may be invoked. This approach may also be used with + <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">post</span><span class="special">()</span></code> + to use a means to perform any computational tasks across a thread pool. + </p> +<p> + Note that all threads that have joined an <code class="computeroutput"><span class="identifier">io_service</span></code>'s + pool are considered equivalent, and the <code class="computeroutput"><span class="identifier">io_service</span></code> + may distribute work across them in an arbitrary fashion. + </p> +<h6> +<a name="boost_asio.overview.core.threads.h2"></a> + <span><a name="boost_asio.overview.core.threads.internal_threads"></a></span><a class="link" href="threads.html#boost_asio.overview.core.threads.internal_threads">Internal + Threads</a> + </h6> +<p> + The implementation of this library for a particular platform may make use + of one or more internal threads to emulate asynchronicity. As far as possible, + these threads must be invisible to the library user. In particular, the + threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + must not call the user's code directly; and + </li> +<li class="listitem"> + must block all signals. + </li> +</ul></div> +<p> + This approach is complemented by the following guarantee: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Asynchronous completion handlers will only be called from threads that + are currently calling <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>. + </li></ul></div> +<p> + Consequently, it is the library user's responsibility to create and manage + all threads to which the notifications will be delivered. + </p> +<p> + The reasons for this approach include: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + By only calling <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> from a single thread, the user's + code can avoid the development complexity associated with synchronisation. + For example, a library user can implement scalable servers that are + single-threaded (from the user's point of view). + </li> +<li class="listitem"> + A library user may need to perform initialisation in a thread shortly + after the thread starts and before any other application code is executed. + For example, users of Microsoft's COM must call <code class="computeroutput"><span class="identifier">CoInitializeEx</span></code> + before any other COM operations can be called from that thread. + </li> +<li class="listitem"> + The library interface is decoupled from interfaces for thread creation + and management, and permits implementations on platforms where threads + are not available. + </li> +</ul></div> +<h6> +<a name="boost_asio.overview.core.threads.h3"></a> + <span><a name="boost_asio.overview.core.threads.see_also"></a></span><a class="link" href="threads.html#boost_asio.overview.core.threads.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/io_service.html" title="io_service">io_service</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="async.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="strands.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011.html b/doc/html/boost_asio/overview/cpp2011.html new file mode 100755 index 0000000000..9b6e9f88e5 --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011.html @@ -0,0 +1,64 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>C++ 2011 Support</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="ssl.html" title="SSL"> +<link rel="next" href="cpp2011/move_objects.html" title="Movable I/O Objects"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="ssl.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp2011/move_objects.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.cpp2011"></a><a class="link" href="cpp2011.html" title="C++ 2011 Support">C++ 2011 Support</a> +</h3></div></div></div> +<p> + <a class="link" href="cpp2011/move_objects.html" title="Movable I/O Objects">Movable I/O Objects</a> + </p> +<p> + <a class="link" href="cpp2011/move_handlers.html" title="Movable Handlers">Movable Handlers</a> + </p> +<p> + <a class="link" href="cpp2011/variadic.html" title="Variadic Templates">Variadic Templates</a> + </p> +<p> + <a class="link" href="cpp2011/array.html" title="Array Container">Array Container</a> + </p> +<p> + <a class="link" href="cpp2011/atomic.html" title="Atomics">Atomics</a> + </p> +<p> + <a class="link" href="cpp2011/shared_ptr.html" title="Shared Pointers">Shared Pointers</a> + </p> +<p> + <a class="link" href="cpp2011/chrono.html" title="Chrono">Chrono</a> + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="ssl.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp2011/move_objects.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/array.html b/doc/html/boost_asio/overview/cpp2011/array.html new file mode 100755 index 0000000000..b0d4ea64cf --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/array.html @@ -0,0 +1,69 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Array Container</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="variadic.html" title="Variadic Templates"> +<link rel="next" href="atomic.html" title="Atomics"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="variadic.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="atomic.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.array"></a><a class="link" href="array.html" title="Array Container">Array Container</a> +</h4></div></div></div> +<p> + Where the standard library provides <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special"><></span></code>, Boost.Asio: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Provides overloads for the <a class="link" href="../../reference/buffer.html" title="buffer">buffer()</a> + function. + </li> +<li class="listitem"> + Uses it in preference to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special"><></span></code> for the <a class="link" href="../../reference/ip__address_v4/bytes_type.html" title="ip::address_v4::bytes_type">ip::address_v4::bytes_type</a> + and <a class="link" href="../../reference/ip__address_v6/bytes_type.html" title="ip::address_v6::bytes_type">ip::address_v6::bytes_type</a> + types. + </li> +<li class="listitem"> + Uses it in preference to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special"><></span></code> where a fixed size array type + is needed in the implementation. + </li> +</ul></div> +<p> + Support for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special"><></span></code> + is automatically enabled for <code class="literal">g++</code> 4.3 and later, when + the <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code> compiler + options are used, as well as for Microsoft Visual C++ 10. It may be disabled + by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_STD_ARRAY</span></code>, + or explicitly enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_STD_ARRAY</span></code>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="variadic.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="atomic.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/atomic.html b/doc/html/boost_asio/overview/cpp2011/atomic.html new file mode 100755 index 0000000000..18cdfef622 --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/atomic.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Atomics</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="array.html" title="Array Container"> +<link rel="next" href="shared_ptr.html" title="Shared Pointers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="array.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_ptr.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.atomic"></a><a class="link" href="atomic.html" title="Atomics">Atomics</a> +</h4></div></div></div> +<p> + Boost.Asio's implementation can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic</span><span class="special"><></span></code> in preference to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">atomic_count</span></code>. + </p> +<p> + Support for the standard atomic integer template is automatically enabled + for <code class="literal">g++</code> 4.5 and later, when the <code class="literal">-std=c++0x</code> + or <code class="literal">-std=gnu++0x</code> compiler options are used. It may be + disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_STD_ATOMIC</span></code>, + or explicitly enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_STD_ATOMIC</span></code>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="array.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_ptr.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/chrono.html b/doc/html/boost_asio/overview/cpp2011/chrono.html new file mode 100755 index 0000000000..8ccffd6a67 --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/chrono.html @@ -0,0 +1,67 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chrono</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="shared_ptr.html" title="Shared Pointers"> +<link rel="next" href="../implementation.html" title="Platform-Specific Implementation Notes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="shared_ptr.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../implementation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.chrono"></a><a class="link" href="chrono.html" title="Chrono">Chrono</a> +</h4></div></div></div> +<p> + Boost.Asio provides timers based on the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span></code> + facilities via the <a class="link" href="../../reference/basic_waitable_timer.html" title="basic_waitable_timer">basic_waitable_timer</a> + class template. The typedefs <a class="link" href="../../reference/system_timer.html" title="system_timer">system_timer</a>, + <a class="link" href="../../reference/steady_timer.html" title="steady_timer">steady_timer</a> and + <a class="link" href="../../reference/high_resolution_timer.html" title="high_resolution_timer">high_resolution_timer</a> + utilise the standard clocks <code class="computeroutput"><span class="identifier">system_clock</span></code>, + <code class="computeroutput"><span class="identifier">steady_clock</span></code> and <code class="computeroutput"><span class="identifier">high_resolution_clock</span></code> respectively. + </p> +<p> + Support for the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span></code> facilities is automatically enabled + for <code class="literal">g++</code> 4.6 and later, when the <code class="literal">-std=c++0x</code> + or <code class="literal">-std=gnu++0x</code> compiler options are used. (Note that, + for <code class="literal">g++</code>, the draft-standard <code class="computeroutput"><span class="identifier">monotonic_clock</span></code> + is used in place of <code class="computeroutput"><span class="identifier">steady_clock</span></code>.) + Support may be disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_STD_CHRONO</span></code>, + or explicitly enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_STD_CHRONO</span></code>. + </p> +<p> + When standard <code class="computeroutput"><span class="identifier">chrono</span></code> is + unavailable, Boost.Asio will otherwise use the Boost.Chrono library. The + <a class="link" href="../../reference/basic_waitable_timer.html" title="basic_waitable_timer">basic_waitable_timer</a> + class template may be used with either. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="shared_ptr.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../implementation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/move_handlers.html b/doc/html/boost_asio/overview/cpp2011/move_handlers.html new file mode 100755 index 0000000000..4e3e57983c --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/move_handlers.html @@ -0,0 +1,90 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Movable Handlers</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="move_objects.html" title="Movable I/O Objects"> +<link rel="next" href="variadic.html" title="Variadic Templates"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="move_objects.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="variadic.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.move_handlers"></a><a class="link" href="move_handlers.html" title="Movable Handlers">Movable + Handlers</a> +</h4></div></div></div> +<p> + As an optimisation, user-defined completion handlers may provide move constructors, + and Boost.Asio's implementation will use a handler's move constructor in + preference to its copy constructor. In certain circumstances, Boost.Asio + may be able to eliminate all calls to a handler's copy constructor. However, + handler types are still required to be copy constructible. + </p> +<p> + When move support is enabled, asynchronous that are documented as follows: + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Handler</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">async_XYZ</span><span class="special">(...,</span> <span class="identifier">Handler</span> <span class="identifier">handler</span><span class="special">);</span> +</pre> +<p> + are actually declared as: + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Handler</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">async_XYZ</span><span class="special">(...,</span> <span class="identifier">Handler</span><span class="special">&&</span> <span class="identifier">handler</span><span class="special">);</span> +</pre> +<p> + The handler argument is perfectly forwarded and the move construction occurs + within the body of <code class="computeroutput"><span class="identifier">async_XYZ</span><span class="special">()</span></code>. This ensures that all other function + arguments are evaluated prior to the move. This is critical when the other + arguments to <code class="computeroutput"><span class="identifier">async_XYZ</span><span class="special">()</span></code> are members of the handler. For example: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_operation</span> +<span class="special">{</span> + <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">></span> <span class="identifier">socket</span><span class="special">;</span> + <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">char</span><span class="special">>></span> <span class="identifier">buffer</span><span class="special">;</span> + <span class="special">...</span> + <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">length</span><span class="special">)</span> + <span class="special">{</span> + <span class="special">...</span> + <span class="identifier">socket</span><span class="special">-></span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">buffer</span><span class="special">(*</span><span class="identifier">buffer</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(*</span><span class="keyword">this</span><span class="special">));</span> + <span class="special">...</span> + <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + Move support is automatically enabled for <code class="literal">g++</code> 4.5 and + later, when the <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code> + compiler options are used. It may be disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_MOVE</span></code>, or explicitly + enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_MOVE</span></code>. + Note that these macros also affect the availability of <a class="link" href="move_objects.html" title="Movable I/O Objects">movable + I/O objects</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="move_objects.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="variadic.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/move_objects.html b/doc/html/boost_asio/overview/cpp2011/move_objects.html new file mode 100755 index 0000000000..0dd4b34bd6 --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/move_objects.html @@ -0,0 +1,110 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Movable I/O Objects</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="next" href="move_handlers.html" title="Movable Handlers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../cpp2011.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="move_handlers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.move_objects"></a><a class="link" href="move_objects.html" title="Movable I/O Objects">Movable I/O + Objects</a> +</h4></div></div></div> +<p> + When move support is available (via rvalue references), Boost.Asio allows + move construction and assignment of sockets, serial ports, POSIX descriptors + and Windows handles. + </p> +<p> + Move support allows you to write code like: + </p> +<pre class="programlisting"><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">make_socket</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">&</span> <span class="identifier">i</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">s</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> + <span class="special">...</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + or: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">connection</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">enable_shared_from_this</span><span class="special"><</span><span class="identifier">connection</span><span class="special">></span> +<span class="special">{</span> +<span class="keyword">private</span><span class="special">:</span> + <span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket_</span><span class="special">;</span> + <span class="special">...</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="identifier">connection</span><span class="special">(</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&&</span> <span class="identifier">s</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">socket_</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s</span><span class="special">))</span> <span class="special">{}</span> + <span class="special">...</span> +<span class="special">};</span> + +<span class="special">...</span> + +<span class="keyword">class</span> <span class="identifier">server</span> +<span class="special">{</span> +<span class="keyword">private</span><span class="special">:</span> + <span class="identifier">tcp</span><span class="special">::</span><span class="identifier">acceptor</span> <span class="identifier">acceptor_</span><span class="special">;</span> + <span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket_</span><span class="special">;</span> + <span class="special">...</span> + <span class="keyword">void</span> <span class="identifier">handle_accept</span><span class="special">(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ec</span><span class="special">)</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special"><</span><span class="identifier">connection</span><span class="special">>(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">socket_</span><span class="special">))-></span><span class="identifier">go</span><span class="special">();</span> + <span class="identifier">acceptor_</span><span class="special">.</span><span class="identifier">async_accept</span><span class="special">(</span><span class="identifier">socket_</span><span class="special">,</span> <span class="special">...);</span> + <span class="special">}</span> + <span class="special">...</span> +<span class="special">};</span> +</pre> +<p> + as well as: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">></span> <span class="identifier">sockets</span><span class="special">;</span> +<span class="identifier">sockets</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">(...));</span> +</pre> +<p> + A word of warning: There is nothing stopping you from moving these objects + while there are pending asynchronous operations, but it is unlikely to + be a good idea to do so. In particular, composed operations like <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a> store a reference + to the stream object. Moving during the composed operation means that the + composed operation may attempt to access a moved-from object. + </p> +<p> + Move support is automatically enabled for <code class="literal">g++</code> 4.5 and + later, when the <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code> + compiler options are used. It may be disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_MOVE</span></code>, or explicitly + enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_MOVE</span></code>. + Note that these macros also affect the availability of <a class="link" href="move_handlers.html" title="Movable Handlers">movable + handlers</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../cpp2011.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="move_handlers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/shared_ptr.html b/doc/html/boost_asio/overview/cpp2011/shared_ptr.html new file mode 100755 index 0000000000..724c2cda69 --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/shared_ptr.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Shared Pointers</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="atomic.html" title="Atomics"> +<link rel="next" href="chrono.html" title="Chrono"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="atomic.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="chrono.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.shared_ptr"></a><a class="link" href="shared_ptr.html" title="Shared Pointers">Shared Pointers</a> +</h4></div></div></div> +<p> + Boost.Asio's implementation can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special"><></span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">weak_ptr</span><span class="special"><></span></code> in preference to the Boost equivalents. + </p> +<p> + Support for the standard smart pointers is automatically enabled for <code class="literal">g++</code> + 4.3 and later, when the <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code> + compiler options are used, as well as for Microsoft Visual C++ 10. It may + be disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_STD_SHARED_PTR</span></code>, + or explicitly enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_STD_SHARED_PTR</span></code>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="atomic.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="chrono.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/cpp2011/variadic.html b/doc/html/boost_asio/overview/cpp2011/variadic.html new file mode 100755 index 0000000000..458f2f4fde --- /dev/null +++ b/doc/html/boost_asio/overview/cpp2011/variadic.html @@ -0,0 +1,55 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Variadic Templates</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../cpp2011.html" title="C++ 2011 Support"> +<link rel="prev" href="move_handlers.html" title="Movable Handlers"> +<link rel="next" href="array.html" title="Array Container"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="move_handlers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="array.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.cpp2011.variadic"></a><a class="link" href="variadic.html" title="Variadic Templates">Variadic Templates</a> +</h4></div></div></div> +<p> + When supported by a compiler, Boost.Asio can use variadic templates to + implement the <a class="link" href="../../reference/basic_socket_streambuf/connect.html" title="basic_socket_streambuf::connect">basic_socket_streambuf::connect()</a> + and <a class="link" href="../../reference/basic_socket_iostream/connect.html" title="basic_socket_iostream::connect">basic_socket_iostream::connect()</a> + functions. + </p> +<p> + Support for variadic templates is automatically enabled for <code class="literal">g++</code> + 4.3 and later, when the <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code> + compiler options are used. It may be disabled by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_VARIADIC_TEMPLATES</span></code>, + or explicitly enabled for other compilers by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_VARIADIC_TEMPLATES</span></code>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="move_handlers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cpp2011.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="array.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/implementation.html b/doc/html/boost_asio/overview/implementation.html new file mode 100755 index 0000000000..50a08500cf --- /dev/null +++ b/doc/html/boost_asio/overview/implementation.html @@ -0,0 +1,429 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Platform-Specific Implementation Notes</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="cpp2011/chrono.html" title="Chrono"> +<link rel="next" href="../using.html" title="Using Boost.Asio"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="cpp2011/chrono.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../using.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.implementation"></a><a class="link" href="implementation.html" title="Platform-Specific Implementation Notes">Platform-Specific + Implementation Notes</a> +</h3></div></div></div> +<p> + This section lists platform-specific implementation details, such as the + default demultiplexing mechanism, the number of threads created internally, + and when threads are created. + </p> +<h5> +<a name="boost_asio.overview.implementation.h0"></a> + <span><a name="boost_asio.overview.implementation.linux_kernel_2_4"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.linux_kernel_2_4">Linux + Kernel 2.4</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + This means that the number of file descriptors in the process cannot + be permitted to exceed <code class="computeroutput"><span class="identifier">FD_SETSIZE</span></code>. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h1"></a> + <span><a name="boost_asio.overview.implementation.linux_kernel_2_6"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.linux_kernel_2_6">Linux + Kernel 2.6</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">epoll</span></code> for demultiplexing. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">epoll</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h2"></a> + <span><a name="boost_asio.overview.implementation.solaris"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.solaris">Solaris</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="literal">/dev/poll</code> for demultiplexing. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="literal">/dev/poll</code> is performed in one + of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h3"></a> + <span><a name="boost_asio.overview.implementation.qnx_neutrino"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.qnx_neutrino">QNX + Neutrino</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + This means that the number of file descriptors in the process cannot + be permitted to exceed <code class="computeroutput"><span class="identifier">FD_SETSIZE</span></code>. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h4"></a> + <span><a name="boost_asio.overview.implementation.mac_os_x"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.mac_os_x">Mac + OS X</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">kqueue</span></code> for demultiplexing. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">kqueue</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h5"></a> + <span><a name="boost_asio.overview.implementation.freebsd"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.freebsd">FreeBSD</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">kqueue</span></code> for demultiplexing. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">kqueue</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h6"></a> + <span><a name="boost_asio.overview.implementation.aix"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.aix">AIX</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + This means that the number of file descriptors in the process cannot + be permitted to exceed <code class="computeroutput"><span class="identifier">FD_SETSIZE</span></code>. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h7"></a> + <span><a name="boost_asio.overview.implementation.hp_ux"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.hp_ux">HP-UX</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + This means that the number of file descriptors in the process cannot + be permitted to exceed <code class="computeroutput"><span class="identifier">FD_SETSIZE</span></code>. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h8"></a> + <span><a name="boost_asio.overview.implementation.tru64"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.tru64">Tru64</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + This means that the number of file descriptors in the process cannot + be permitted to exceed <code class="computeroutput"><span class="identifier">FD_SETSIZE</span></code>. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + At most <code class="computeroutput"><span class="identifier">min</span><span class="special">(</span><span class="number">64</span><span class="special">,</span><span class="identifier">IOV_MAX</span><span class="special">)</span></code> buffers may be transferred in a single + operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h9"></a> + <span><a name="boost_asio.overview.implementation.windows_95__98_and_me"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.windows_95__98_and_me">Windows + 95, 98 and Me</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for demultiplexing. + </li></ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using <code class="computeroutput"><span class="identifier">select</span></code> + is performed in one of the threads that calls <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + For sockets, at most 16 buffers may be transferred in a single operation. + </li></ul></div> +<h5> +<a name="boost_asio.overview.implementation.h10"></a> + <span><a name="boost_asio.overview.implementation.windows_nt__2000__xp__2003_and_vista"></a></span><a class="link" href="implementation.html#boost_asio.overview.implementation.windows_nt__2000__xp__2003_and_vista">Windows + NT, 2000, XP, 2003 and Vista</a> + </h5> +<p> + Demultiplexing mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Uses overlapped I/O and I/O completion ports for all asynchronous socket + operations except for asynchronous connect. + </li> +<li class="listitem"> + Uses <code class="computeroutput"><span class="identifier">select</span></code> for emulating + asynchronous connect. + </li> +</ul></div> +<p> + Threads: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Demultiplexing using I/O completion ports is performed in all threads + that call <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run_one</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">poll_one</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to trigger timers. This thread is created on construction of + the first <code class="computeroutput"><span class="identifier">deadline_timer</span></code> + or <code class="computeroutput"><span class="identifier">deadline_timer_service</span></code> + objects. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used for the <code class="computeroutput"><span class="identifier">select</span></code> + demultiplexing. This thread is created on the first call to <code class="computeroutput"><span class="identifier">async_connect</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + An additional thread per <code class="computeroutput"><span class="identifier">io_service</span></code> + is used to emulate asynchronous host resolution. This thread is created + on the first call to either <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">async_resolve</span><span class="special">()</span></code>. + </li> +</ul></div> +<p> + Scatter-Gather: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + For sockets, at most 64 buffers may be transferred in a single operation. + </li> +<li class="listitem"> + For stream-oriented handles, only one buffer may be transferred in a + single operation. + </li> +</ul></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="cpp2011/chrono.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../using.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/networking.html b/doc/html/boost_asio/overview/networking.html new file mode 100755 index 0000000000..d5d53a9254 --- /dev/null +++ b/doc/html/boost_asio/overview/networking.html @@ -0,0 +1,56 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Networking</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="core/handler_tracking.html" title="Handler Tracking"> +<link rel="next" href="networking/protocols.html" title="TCP, UDP and ICMP"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="core/handler_tracking.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="networking/protocols.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.networking"></a><a class="link" href="networking.html" title="Networking">Networking</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a class="link" href="networking/protocols.html" title="TCP, UDP and ICMP">TCP, UDP and + ICMP</a> + </li> +<li class="listitem"> + <a class="link" href="networking/iostreams.html" title="Socket Iostreams">Socket Iostreams</a> + </li> +<li class="listitem"> + <a class="link" href="networking/bsd_sockets.html" title="The BSD Socket API and Boost.Asio">The BSD Socket + API and Boost.Asio</a> + </li> +</ul></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="core/handler_tracking.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="networking/protocols.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/networking/bsd_sockets.html b/doc/html/boost_asio/overview/networking/bsd_sockets.html new file mode 100755 index 0000000000..4f415c3bff --- /dev/null +++ b/doc/html/boost_asio/overview/networking/bsd_sockets.html @@ -0,0 +1,562 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>The BSD Socket API and Boost.Asio</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../networking.html" title="Networking"> +<link rel="prev" href="iostreams.html" title="Socket Iostreams"> +<link rel="next" href="../timers.html" title="Timers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="iostreams.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../timers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.networking.bsd_sockets"></a><a class="link" href="bsd_sockets.html" title="The BSD Socket API and Boost.Asio">The BSD + Socket API and Boost.Asio</a> +</h4></div></div></div> +<p> + 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. + </p> +<p> + Unsafe and error prone aspects of the BSD socket API not included. For + example, the use of <code class="computeroutput"><span class="keyword">int</span></code> 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 <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span></code>, and for UDP one uses <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">socket</span></code>. + </p> +<p> + The following table shows the mapping between the BSD socket API and Boost.Asio: + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + BSD Socket API Elements + </p> + </th> +<th> + <p> + Equivalents in Boost.Asio + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + socket descriptor - <code class="computeroutput"><span class="keyword">int</span></code> + (POSIX) or <code class="computeroutput"><span class="identifier">SOCKET</span></code> + (Windows) + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/ip__tcp/socket.html" title="ip::tcp::socket">ip::tcp::socket</a>, + <a class="link" href="../../reference/ip__tcp/acceptor.html" title="ip::tcp::acceptor">ip::tcp::acceptor</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/ip__udp/socket.html" title="ip::udp::socket">ip::udp::socket</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket.html" title="basic_socket">basic_socket</a>, + <a class="link" href="../../reference/basic_stream_socket.html" title="basic_stream_socket">basic_stream_socket</a>, + <a class="link" href="../../reference/basic_datagram_socket.html" title="basic_datagram_socket">basic_datagram_socket</a>, + <a class="link" href="../../reference/basic_raw_socket.html" title="basic_raw_socket">basic_raw_socket</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">in_addr</span></code>, <code class="computeroutput"><span class="identifier">in6_addr</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/ip__address.html" title="ip::address">ip::address</a>, + <a class="link" href="../../reference/ip__address.html" title="ip::address">ip::address_v4</a>, + <a class="link" href="../../reference/ip__address.html" title="ip::address">ip::address_v6</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">sockaddr_in</span></code>, + <code class="computeroutput"><span class="identifier">sockaddr_in6</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/ip__tcp/endpoint.html" title="ip::tcp::endpoint">ip::tcp::endpoint</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/ip__udp/endpoint.html" title="ip::udp::endpoint">ip::udp::endpoint</a> + </p> + <p> + <a class="link" href="../../reference/ip__basic_endpoint.html" title="ip::basic_endpoint">ip::basic_endpoint</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">accept</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket_acceptor/accept.html" title="basic_socket_acceptor::accept">ip::tcp::acceptor::accept()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket_acceptor/accept.html" title="basic_socket_acceptor::accept">basic_socket_acceptor::accept()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">bind</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/bind.html" title="basic_socket::bind">ip::tcp::acceptor::bind()</a>, + <a class="link" href="../../reference/basic_socket/bind.html" title="basic_socket::bind">ip::tcp::socket::bind()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/bind.html" title="basic_socket::bind">ip::udp::socket::bind()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/bind.html" title="basic_socket::bind">basic_socket::bind()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">close</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/close.html" title="basic_socket::close">ip::tcp::acceptor::close()</a>, + <a class="link" href="../../reference/basic_socket/close.html" title="basic_socket::close">ip::tcp::socket::close()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/close.html" title="basic_socket::close">ip::udp::socket::close()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/close.html" title="basic_socket::close">basic_socket::close()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">connect</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/connect.html" title="basic_socket::connect">ip::tcp::socket::connect()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/connect.html" title="basic_socket::connect">ip::udp::socket::connect()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/connect.html" title="basic_socket::connect">basic_socket::connect()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">getaddrinfo</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">gethostbyaddr</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">gethostbyname</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">getnameinfo</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">getservbyname</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">getservbyport</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/ip__basic_resolver/resolve.html" title="ip::basic_resolver::resolve">ip::tcp::resolver::resolve()</a>, + <a class="link" href="../../reference/ip__basic_resolver/async_resolve.html" title="ip::basic_resolver::async_resolve">ip::tcp::resolver::async_resolve()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/ip__basic_resolver/resolve.html" title="ip::basic_resolver::resolve">ip::udp::resolver::resolve()</a>, + <a class="link" href="../../reference/ip__basic_resolver/async_resolve.html" title="ip::basic_resolver::async_resolve">ip::udp::resolver::async_resolve()</a> + </p> + <p> + <a class="link" href="../../reference/ip__basic_resolver/resolve.html" title="ip::basic_resolver::resolve">ip::basic_resolver::resolve()</a>, + <a class="link" href="../../reference/ip__basic_resolver/async_resolve.html" title="ip::basic_resolver::async_resolve">ip::basic_resolver::async_resolve()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">gethostname</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/ip__host_name.html" title="ip::host_name">ip::host_name()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">getpeername</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/remote_endpoint.html" title="basic_socket::remote_endpoint">ip::tcp::socket::remote_endpoint()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/remote_endpoint.html" title="basic_socket::remote_endpoint">ip::udp::socket::remote_endpoint()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/remote_endpoint.html" title="basic_socket::remote_endpoint">basic_socket::remote_endpoint()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">getsockname</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/local_endpoint.html" title="basic_socket::local_endpoint">ip::tcp::acceptor::local_endpoint()</a>, + <a class="link" href="../../reference/basic_socket/local_endpoint.html" title="basic_socket::local_endpoint">ip::tcp::socket::local_endpoint()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/local_endpoint.html" title="basic_socket::local_endpoint">ip::udp::socket::local_endpoint()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/local_endpoint.html" title="basic_socket::local_endpoint">basic_socket::local_endpoint()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">getsockopt</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/get_option.html" title="basic_socket::get_option">ip::tcp::acceptor::get_option()</a>, + <a class="link" href="../../reference/basic_socket/get_option.html" title="basic_socket::get_option">ip::tcp::socket::get_option()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/get_option.html" title="basic_socket::get_option">ip::udp::socket::get_option()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/get_option.html" title="basic_socket::get_option">basic_socket::get_option()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">inet_addr</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">inet_aton</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">inet_pton</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/ip__address/from_string.html" title="ip::address::from_string">ip::address::from_string()</a>, + <a class="link" href="../../reference/ip__address/from_string.html" title="ip::address::from_string">ip::address_v4::from_string()</a>, + <a class="link" href="../../reference/ip__address/from_string.html" title="ip::address::from_string">ip_address_v6::from_string()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">inet_ntoa</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">inet_ntop</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/ip__address/to_string.html" title="ip::address::to_string">ip::address::to_string()</a>, + <a class="link" href="../../reference/ip__address/to_string.html" title="ip::address::to_string">ip::address_v4::to_string()</a>, + <a class="link" href="../../reference/ip__address/to_string.html" title="ip::address::to_string">ip_address_v6::to_string()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">ioctl</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/io_control.html" title="basic_socket::io_control">ip::tcp::socket::io_control()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/io_control.html" title="basic_socket::io_control">ip::udp::socket::io_control()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/io_control.html" title="basic_socket::io_control">basic_socket::io_control()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">listen</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket_acceptor/listen.html" title="basic_socket_acceptor::listen">ip::tcp::acceptor::listen()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket_acceptor/listen.html" title="basic_socket_acceptor::listen">basic_socket_acceptor::listen()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">poll</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">select</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">pselect</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/io_service/run.html" title="io_service::run">io_service::run()</a>, + <a class="link" href="../../reference/io_service/run_one.html" title="io_service::run_one">io_service::run_one()</a>, + <a class="link" href="../../reference/io_service/poll.html" title="io_service::poll">io_service::poll()</a>, + <a class="link" href="../../reference/io_service/poll_one.html" title="io_service::poll_one">io_service::poll_one()</a> + </p> + <p> + Note: in conjunction with asynchronous operations. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">readv</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">recv</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">read</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_stream_socket/read_some.html" title="basic_stream_socket::read_some">ip::tcp::socket::read_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_read_some.html" title="basic_stream_socket::async_read_some">ip::tcp::socket::async_read_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/receive.html" title="basic_stream_socket::receive">ip::tcp::socket::receive()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_receive.html" title="basic_stream_socket::async_receive">ip::tcp::socket::async_receive()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_datagram_socket/receive.html" title="basic_datagram_socket::receive">ip::udp::socket::receive()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive.html" title="basic_datagram_socket::async_receive">ip::udp::socket::async_receive()</a> + </p> + <p> + <a class="link" href="../../reference/basic_stream_socket/read_some.html" title="basic_stream_socket::read_some">basic_stream_socket::read_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_read_some.html" title="basic_stream_socket::async_read_some">basic_stream_socket::async_read_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/receive.html" title="basic_stream_socket::receive">basic_stream_socket::receive()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_receive.html" title="basic_stream_socket::async_receive">basic_stream_socket::async_receive()</a>, + <a class="link" href="../../reference/basic_datagram_socket/receive.html" title="basic_datagram_socket::receive">basic_datagram_socket::receive()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive.html" title="basic_datagram_socket::async_receive">basic_datagram_socket::async_receive()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">recvfrom</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For UDP: <a class="link" href="../../reference/basic_datagram_socket/receive_from.html" title="basic_datagram_socket::receive_from">ip::udp::socket::receive_from()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive_from.html" title="basic_datagram_socket::async_receive_from">ip::udp::socket::async_receive_from()</a> + </p> + <p> + <a class="link" href="../../reference/basic_datagram_socket/receive_from.html" title="basic_datagram_socket::receive_from">basic_datagram_socket::receive_from()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive_from.html" title="basic_datagram_socket::async_receive_from">basic_datagram_socket::async_receive_from()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">send</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">write</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">writev</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_stream_socket/write_some.html" title="basic_stream_socket::write_some">ip::tcp::socket::write_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_write_some.html" title="basic_stream_socket::async_write_some">ip::tcp::socket::async_write_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/send.html" title="basic_stream_socket::send">ip::tcp::socket::send()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_send.html" title="basic_stream_socket::async_send">ip::tcp::socket::async_send()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_datagram_socket/send.html" title="basic_datagram_socket::send">ip::udp::socket::send()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_send.html" title="basic_datagram_socket::async_send">ip::udp::socket::async_send()</a> + </p> + <p> + <a class="link" href="../../reference/basic_stream_socket/write_some.html" title="basic_stream_socket::write_some">basic_stream_socket::write_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_write_some.html" title="basic_stream_socket::async_write_some">basic_stream_socket::async_write_some()</a>, + <a class="link" href="../../reference/basic_stream_socket/send.html" title="basic_stream_socket::send">basic_stream_socket::send()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_send.html" title="basic_stream_socket::async_send">basic_stream_socket::async_send()</a>, + <a class="link" href="../../reference/basic_datagram_socket/send.html" title="basic_datagram_socket::send">basic_datagram_socket::send()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_send.html" title="basic_datagram_socket::async_send">basic_datagram_socket::async_send()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">sendto</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For UDP: <a class="link" href="../../reference/basic_datagram_socket/send_to.html" title="basic_datagram_socket::send_to">ip::udp::socket::send_to()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_send_to.html" title="basic_datagram_socket::async_send_to">ip::udp::socket::async_send_to()</a> + </p> + <p> + <a class="link" href="../../reference/basic_datagram_socket/send_to.html" title="basic_datagram_socket::send_to">basic_datagram_socket::send_to()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_send_to.html" title="basic_datagram_socket::async_send_to">basic_datagram_socket::async_send_to()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">setsockopt</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/set_option.html" title="basic_socket::set_option">ip::tcp::acceptor::set_option()</a>, + <a class="link" href="../../reference/basic_socket/set_option.html" title="basic_socket::set_option">ip::tcp::socket::set_option()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/set_option.html" title="basic_socket::set_option">ip::udp::socket::set_option()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/set_option.html" title="basic_socket::set_option">basic_socket::set_option()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">shutdown</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/shutdown.html" title="basic_socket::shutdown">ip::tcp::socket::shutdown()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/shutdown.html" title="basic_socket::shutdown">ip::udp::socket::shutdown()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/shutdown.html" title="basic_socket::shutdown">basic_socket::shutdown()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">sockatmark</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/at_mark.html" title="basic_socket::at_mark">ip::tcp::socket::at_mark()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/at_mark.html" title="basic_socket::at_mark">basic_socket::at_mark()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">socket</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + For TCP: <a class="link" href="../../reference/basic_socket/open.html" title="basic_socket::open">ip::tcp::acceptor::open()</a>, + <a class="link" href="../../reference/basic_socket/open.html" title="basic_socket::open">ip::tcp::socket::open()</a> + </p> + <p> + For UDP: <a class="link" href="../../reference/basic_socket/open.html" title="basic_socket::open">ip::udp::socket::open()</a> + </p> + <p> + <a class="link" href="../../reference/basic_socket/open.html" title="basic_socket::open">basic_socket::open()</a> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">socketpair</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <a class="link" href="../../reference/local__connect_pair.html" title="local::connect_pair">local::connect_pair()</a> + </p> + <p> + Note: POSIX operating systems only. + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="iostreams.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../timers.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/networking/iostreams.html b/doc/html/boost_asio/overview/networking/iostreams.html new file mode 100755 index 0000000000..94f1a0cc2a --- /dev/null +++ b/doc/html/boost_asio/overview/networking/iostreams.html @@ -0,0 +1,119 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Socket Iostreams</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../networking.html" title="Networking"> +<link rel="prev" href="protocols.html" title="TCP, UDP and ICMP"> +<link rel="next" href="bsd_sockets.html" title="The BSD Socket API and Boost.Asio"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="protocols.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bsd_sockets.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.networking.iostreams"></a><a class="link" href="iostreams.html" title="Socket Iostreams">Socket Iostreams</a> +</h4></div></div></div> +<p> + 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: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">iostream</span> <span class="identifier">stream</span><span class="special">(</span><span class="string">"www.boost.org"</span><span class="special">,</span> <span class="string">"http"</span><span class="special">);</span> +<span class="keyword">if</span> <span class="special">(!</span><span class="identifier">stream</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// Can't connect.</span> +<span class="special">}</span> +</pre> +<p> + The iostream class can also be used in conjunction with an acceptor to + create simple servers. For example: + </p> +<pre class="programlisting"><span class="identifier">io_service</span> <span class="identifier">ios</span><span class="special">;</span> + +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">endpoint</span><span class="special">(</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">v4</span><span class="special">(),</span> <span class="number">80</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">acceptor</span> <span class="identifier">acceptor</span><span class="special">(</span><span class="identifier">ios</span><span class="special">,</span> <span class="identifier">endpoint</span><span class="special">);</span> + +<span class="keyword">for</span> <span class="special">(;;)</span> +<span class="special">{</span> + <span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">iostream</span> <span class="identifier">stream</span><span class="special">;</span> + <span class="identifier">acceptor</span><span class="special">.</span><span class="identifier">accept</span><span class="special">(*</span><span class="identifier">stream</span><span class="special">.</span><span class="identifier">rdbuf</span><span class="special">());</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +<p> + Timeouts may be set by calling <code class="computeroutput"><span class="identifier">expires_at</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">expires_from_now</span><span class="special">()</span></code> to establish a deadline. Any socket operations + that occur past the deadline will put the iostream into a "bad" + state. + </p> +<p> + For example, a simple client program like this: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">iostream</span> <span class="identifier">stream</span><span class="special">;</span> +<span class="identifier">stream</span><span class="special">.</span><span class="identifier">expires_from_now</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">60</span><span class="special">));</span> +<span class="identifier">stream</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="string">"www.boost.org"</span><span class="special">,</span> <span class="string">"http"</span><span class="special">);</span> +<span class="identifier">stream</span> <span class="special"><<</span> <span class="string">"GET /LICENSE_1_0.txt HTTP/1.0\r\n"</span><span class="special">;</span> +<span class="identifier">stream</span> <span class="special"><<</span> <span class="string">"Host: www.boost.org\r\n"</span><span class="special">;</span> +<span class="identifier">stream</span> <span class="special"><<</span> <span class="string">"Accept: */*\r\n"</span><span class="special">;</span> +<span class="identifier">stream</span> <span class="special"><<</span> <span class="string">"Connection: close\r\n\r\n"</span><span class="special">;</span> +<span class="identifier">stream</span><span class="special">.</span><span class="identifier">flush</span><span class="special">();</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">stream</span><span class="special">.</span><span class="identifier">rdbuf</span><span class="special">();</span> +</pre> +<p> + will fail if all the socket operations combined take longer than 60 seconds. + </p> +<p> + If an error does occur, the iostream's <code class="computeroutput"><span class="identifier">error</span><span class="special">()</span></code> member function may be used to retrieve + the error code from the most recent system call: + </p> +<pre class="programlisting"><span class="keyword">if</span> <span class="special">(!</span><span class="identifier">stream</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Error: "</span> <span class="special"><<</span> <span class="identifier">stream</span><span class="special">.</span><span class="identifier">error</span><span class="special">().</span><span class="identifier">message</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<h6> +<a name="boost_asio.overview.networking.iostreams.h0"></a> + <span><a name="boost_asio.overview.networking.iostreams.see_also"></a></span><a class="link" href="iostreams.html#boost_asio.overview.networking.iostreams.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/ip__tcp/iostream.html" title="ip::tcp::iostream">ip::tcp::iostream</a>, + <a class="link" href="../../reference/basic_socket_iostream.html" title="basic_socket_iostream">basic_socket_iostream</a>, + <a class="link" href="../../examples.html#boost_asio.examples.iostreams">iostreams examples</a>. + </p> +<h6> +<a name="boost_asio.overview.networking.iostreams.h1"></a> + <span><a name="boost_asio.overview.networking.iostreams.notes"></a></span><a class="link" href="iostreams.html#boost_asio.overview.networking.iostreams.notes">Notes</a> + </h6> +<p> + These iostream templates only support <code class="computeroutput"><span class="keyword">char</span></code>, + not <code class="computeroutput"><span class="keyword">wchar_t</span></code>, and do not perform + any code conversion. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="protocols.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bsd_sockets.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/networking/protocols.html b/doc/html/boost_asio/overview/networking/protocols.html new file mode 100755 index 0000000000..85604aef61 --- /dev/null +++ b/doc/html/boost_asio/overview/networking/protocols.html @@ -0,0 +1,218 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>TCP, UDP and ICMP</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../networking.html" title="Networking"> +<link rel="prev" href="../networking.html" title="Networking"> +<link rel="next" href="iostreams.html" title="Socket Iostreams"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../networking.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iostreams.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.networking.protocols"></a><a class="link" href="protocols.html" title="TCP, UDP and ICMP">TCP, UDP + and ICMP</a> +</h4></div></div></div> +<p> + Boost.Asio provides off-the-shelf support for the internet protocols TCP, + UDP and ICMP. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h0"></a> + <span><a name="boost_asio.overview.networking.protocols.tcp_clients"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.tcp_clients">TCP Clients</a> + </h6> +<p> + Hostname resolution is performed using a resolver, where host and service + names are looked up and converted into one or more endpoints: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span> <span class="identifier">resolver</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">query</span> <span class="identifier">query</span><span class="special">(</span><span class="string">"www.boost.org"</span><span class="special">,</span> <span class="string">"http"</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iter</span> <span class="special">=</span> <span class="identifier">resolver</span><span class="special">.</span><span class="identifier">resolve</span><span class="special">(</span><span class="identifier">query</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">;</span> <span class="comment">// End marker.</span> +<span class="keyword">while</span> <span class="special">(</span><span class="identifier">iter</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">endpoint</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">iter</span><span class="special">++;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">endpoint</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + The list of endpoints obtained above could contain both IPv4 and IPv6 endpoints, + so a program should try each of them until it finds one that works. This + keeps the client program independent of a specific IP version. + </p> +<p> + To simplify the development of protocol-independent programs, TCP clients + may establish connections using the free functions <a class="link" href="../../reference/connect.html" title="connect">connect()</a> + and <a class="link" href="../../reference/async_connect.html" title="async_connect">async_connect()</a>. + These operations try each endpoint in a list until the socket is successfully + connected. For example, a single call: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">socket</span><span class="special">,</span> <span class="identifier">resolver</span><span class="special">.</span><span class="identifier">resolve</span><span class="special">(</span><span class="identifier">query</span><span class="special">));</span> +</pre> +<p> + will synchronously try all endpoints until one is successfully connected. + Similarly, an asynchronous connect may be performed by writing: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">async_connect</span><span class="special">(</span><span class="identifier">socket_</span><span class="special">,</span> <span class="identifier">iter</span><span class="special">,</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">handle_connect</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">placeholders</span><span class="special">::</span><span class="identifier">error</span><span class="special">));</span> + +<span class="comment">// ...</span> + +<span class="keyword">void</span> <span class="identifier">handle_connect</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">error</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">error</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// Start read or write operations.</span> + <span class="special">}</span> + <span class="keyword">else</span> + <span class="special">{</span> + <span class="comment">// Handle error.</span> + <span class="special">}</span> +<span class="special">}</span> +</pre> +<p> + When a specific endpoint is available, a socket can be created and connected: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">endpoint</span><span class="special">);</span> +</pre> +<p> + Data may be read from or written to a connected TCP socket using the <a class="link" href="../../reference/basic_stream_socket/receive.html" title="basic_stream_socket::receive">receive()</a>, + <a class="link" href="../../reference/basic_stream_socket/async_receive.html" title="basic_stream_socket::async_receive">async_receive()</a>, + <a class="link" href="../../reference/basic_stream_socket/send.html" title="basic_stream_socket::send">send()</a> + or <a class="link" href="../../reference/basic_stream_socket/async_send.html" title="basic_stream_socket::async_send">async_send()</a> + member functions. However, as these could result in <a class="link" href="../core/streams.html" title="Streams, Short Reads and Short Writes">short + writes or reads</a>, an application will typically use the following + operations instead: <a class="link" href="../../reference/read.html" title="read">read()</a>, + <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../../reference/write.html" title="write">write()</a> and <a class="link" href="../../reference/async_write.html" title="async_write">async_write()</a>. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h1"></a> + <span><a name="boost_asio.overview.networking.protocols.tcp_servers"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.tcp_servers">TCP Servers</a> + </h6> +<p> + A program uses an acceptor to accept incoming TCP connections: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">acceptor</span> <span class="identifier">acceptor</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">my_endpoint</span><span class="special">);</span> +<span class="special">...</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">acceptor</span><span class="special">.</span><span class="identifier">accept</span><span class="special">(</span><span class="identifier">socket</span><span class="special">);</span> +</pre> +<p> + After a socket has been successfully accepted, it may be read from or written + to as illustrated for TCP clients above. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h2"></a> + <span><a name="boost_asio.overview.networking.protocols.udp"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.udp">UDP</a> + </h6> +<p> + UDP hostname resolution is also performed using a resolver: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span> <span class="identifier">resolver</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">query</span> <span class="identifier">query</span><span class="special">(</span><span class="string">"localhost"</span><span class="special">,</span> <span class="string">"daytime"</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iter</span> <span class="special">=</span> <span class="identifier">resolver</span><span class="special">.</span><span class="identifier">resolve</span><span class="special">(</span><span class="identifier">query</span><span class="special">);</span> +<span class="special">...</span> +</pre> +<p> + A UDP socket is typically bound to a local endpoint. The following code + will create an IP version 4 UDP socket and bind it to the "any" + address on port <code class="computeroutput"><span class="number">12345</span></code>: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">endpoint</span><span class="special">(</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">v4</span><span class="special">(),</span> <span class="number">12345</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">udp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">endpoint</span><span class="special">);</span> +</pre> +<p> + Data may be read from or written to an unconnected UDP socket using the + <a class="link" href="../../reference/basic_datagram_socket/receive_from.html" title="basic_datagram_socket::receive_from">receive_from()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive_from.html" title="basic_datagram_socket::async_receive_from">async_receive_from()</a>, + <a class="link" href="../../reference/basic_datagram_socket/send_to.html" title="basic_datagram_socket::send_to">send_to()</a> + or <a class="link" href="../../reference/basic_datagram_socket/async_send_to.html" title="basic_datagram_socket::async_send_to">async_send_to()</a> + member functions. For a connected UDP socket, use the <a class="link" href="../../reference/basic_datagram_socket/receive.html" title="basic_datagram_socket::receive">receive()</a>, + <a class="link" href="../../reference/basic_datagram_socket/async_receive.html" title="basic_datagram_socket::async_receive">async_receive()</a>, + <a class="link" href="../../reference/basic_datagram_socket/send.html" title="basic_datagram_socket::send">send()</a> + or <a class="link" href="../../reference/basic_datagram_socket/async_send.html" title="basic_datagram_socket::async_send">async_send()</a> + member functions. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h3"></a> + <span><a name="boost_asio.overview.networking.protocols.icmp"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.icmp">ICMP</a> + </h6> +<p> + As with TCP and UDP, ICMP hostname resolution is performed using a resolver: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">resolver</span> <span class="identifier">resolver</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">query</span> <span class="identifier">query</span><span class="special">(</span><span class="string">"localhost"</span><span class="special">,</span> <span class="string">""</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iter</span> <span class="special">=</span> <span class="identifier">resolver</span><span class="special">.</span><span class="identifier">resolve</span><span class="special">(</span><span class="identifier">query</span><span class="special">);</span> +<span class="special">...</span> +</pre> +<p> + An ICMP socket may be bound to a local endpoint. The following code will + create an IP version 6 ICMP socket and bind it to the "any" address: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">endpoint</span><span class="special">(</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">v6</span><span class="special">(),</span> <span class="number">0</span><span class="special">);</span> +<span class="identifier">ip</span><span class="special">::</span><span class="identifier">icmp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">endpoint</span><span class="special">);</span> +</pre> +<p> + The port number is not used for ICMP. + </p> +<p> + Data may be read from or written to an unconnected ICMP socket using the + <a class="link" href="../../reference/basic_raw_socket/receive_from.html" title="basic_raw_socket::receive_from">receive_from()</a>, + <a class="link" href="../../reference/basic_raw_socket/async_receive_from.html" title="basic_raw_socket::async_receive_from">async_receive_from()</a>, + <a class="link" href="../../reference/basic_raw_socket/send_to.html" title="basic_raw_socket::send_to">send_to()</a> + or <a class="link" href="../../reference/basic_raw_socket/async_send_to.html" title="basic_raw_socket::async_send_to">async_send_to()</a> + member functions. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h4"></a> + <span><a name="boost_asio.overview.networking.protocols.other_protocols"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.other_protocols">Other + Protocols</a> + </h6> +<p> + Support for other socket protocols (such as Bluetooth or IRCOMM sockets) + can be added by implementing the <a class="link" href="../../reference/Protocol.html" title="Protocol requirements">Protocol</a> + type requirements. + </p> +<h6> +<a name="boost_asio.overview.networking.protocols.h5"></a> + <span><a name="boost_asio.overview.networking.protocols.see_also"></a></span><a class="link" href="protocols.html#boost_asio.overview.networking.protocols.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/ip__tcp.html" title="ip::tcp">ip::tcp</a>, <a class="link" href="../../reference/ip__udp.html" title="ip::udp">ip::udp</a>, + <a class="link" href="../../reference/ip__icmp.html" title="ip::icmp">ip::icmp</a>, <a class="link" href="../../tutorial/tutdaytime1.html" title="Daytime.1 - A synchronous TCP daytime client">daytime + protocol tutorials</a>, <a class="link" href="../../examples.html#boost_asio.examples.icmp">ICMP + ping example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../networking.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../networking.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iostreams.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/posix.html b/doc/html/boost_asio/overview/posix.html new file mode 100755 index 0000000000..f224986377 --- /dev/null +++ b/doc/html/boost_asio/overview/posix.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>POSIX-Specific Functionality</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="signals.html" title="Signal Handling"> +<link rel="next" href="posix/local.html" title="UNIX Domain Sockets"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="signals.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix/local.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.posix"></a><a class="link" href="posix.html" title="POSIX-Specific Functionality">POSIX-Specific Functionality</a> +</h3></div></div></div> +<p> + <a class="link" href="posix/local.html" title="UNIX Domain Sockets">UNIX Domain Sockets</a> + </p> +<p> + <a class="link" href="posix/stream_descriptor.html" title="Stream-Oriented File Descriptors">Stream-Oriented + File Descriptors</a> + </p> +<p> + <a class="link" href="posix/fork.html" title="Fork">Fork</a> + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="signals.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix/local.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/posix/fork.html b/doc/html/boost_asio/overview/posix/fork.html new file mode 100755 index 0000000000..44cfed9d7e --- /dev/null +++ b/doc/html/boost_asio/overview/posix/fork.html @@ -0,0 +1,83 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Fork</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../posix.html" title="POSIX-Specific Functionality"> +<link rel="prev" href="stream_descriptor.html" title="Stream-Oriented File Descriptors"> +<link rel="next" href="../windows.html" title="Windows-Specific Functionality"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="stream_descriptor.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../windows.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.posix.fork"></a><a class="link" href="fork.html" title="Fork">Fork</a> +</h4></div></div></div> +<p> + Boost.Asio supports programs that utilise the <code class="computeroutput"><span class="identifier">fork</span><span class="special">()</span></code> system call. Provided the program calls + <code class="computeroutput"><span class="identifier">io_service</span><span class="special">.</span><span class="identifier">notify_fork</span><span class="special">()</span></code> + at the appropriate times, Boost.Asio will recreate any internal file descriptors + (such as the "self-pipe trick" descriptor used for waking up + a reactor). The notification is usually performed as follows: + </p> +<pre class="programlisting"><span class="identifier">io_service_</span><span class="special">.</span><span class="identifier">notify_fork</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">fork_prepare</span><span class="special">);</span> +<span class="keyword">if</span> <span class="special">(</span><span class="identifier">fork</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">io_service_</span><span class="special">.</span><span class="identifier">notify_fork</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">fork_child</span><span class="special">);</span> + <span class="special">...</span> +<span class="special">}</span> +<span class="keyword">else</span> +<span class="special">{</span> + <span class="identifier">io_service_</span><span class="special">.</span><span class="identifier">notify_fork</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">fork_parent</span><span class="special">);</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +<p> + User-defined services can also be made fork-aware by overriding the <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">service</span><span class="special">::</span><span class="identifier">fork_service</span><span class="special">()</span></code> + virtual function. + </p> +<p> + Note that any file descriptors accessible via Boost.Asio's public API (e.g. + the descriptors underlying <code class="computeroutput"><span class="identifier">basic_socket</span><span class="special"><></span></code>, <code class="computeroutput"><span class="identifier">posix</span><span class="special">::</span><span class="identifier">stream_descriptor</span></code>, + etc.) are not altered during a fork. It is the program's responsibility + to manage these as required. + </p> +<h6> +<a name="boost_asio.overview.posix.fork.h0"></a> + <span><a name="boost_asio.overview.posix.fork.see_also"></a></span><a class="link" href="fork.html#boost_asio.overview.posix.fork.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/io_service/notify_fork.html" title="io_service::notify_fork">io_service::notify_fork()</a>, + <a class="link" href="../../reference/io_service/fork_event.html" title="io_service::fork_event">io_service::fork_event</a>, + <a class="link" href="../../reference/io_service__service/fork_service.html" title="io_service::service::fork_service">io_service::service::fork_service()</a>, + <a class="link" href="../../examples.html#boost_asio.examples.fork">Fork examples</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="stream_descriptor.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../windows.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/posix/local.html b/doc/html/boost_asio/overview/posix/local.html new file mode 100755 index 0000000000..91a45b2c77 --- /dev/null +++ b/doc/html/boost_asio/overview/posix/local.html @@ -0,0 +1,110 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>UNIX Domain Sockets</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../posix.html" title="POSIX-Specific Functionality"> +<link rel="prev" href="../posix.html" title="POSIX-Specific Functionality"> +<link rel="next" href="stream_descriptor.html" title="Stream-Oriented File Descriptors"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../posix.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="stream_descriptor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.posix.local"></a><a class="link" href="local.html" title="UNIX Domain Sockets">UNIX Domain Sockets</a> +</h4></div></div></div> +<p> + 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: + </p> +<pre class="programlisting"><span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket1</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket2</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">connect_pair</span><span class="special">(</span><span class="identifier">socket1</span><span class="special">,</span> <span class="identifier">socket2</span><span class="special">);</span> +</pre> +<p> + will create a pair of stream-oriented sockets. To do the same for datagram-oriented + sockets, use: + </p> +<pre class="programlisting"><span class="identifier">local</span><span class="special">::</span><span class="identifier">datagram_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket1</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">datagram_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket2</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">connect_pair</span><span class="special">(</span><span class="identifier">socket1</span><span class="special">,</span> <span class="identifier">socket2</span><span class="special">);</span> +</pre> +<p> + 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: + </p> +<pre class="programlisting"><span class="special">::</span><span class="identifier">unlink</span><span class="special">(</span><span class="string">"/tmp/foobar"</span><span class="special">);</span> <span class="comment">// Remove previous binding.</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">ep</span><span class="special">(</span><span class="string">"/tmp/foobar"</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">acceptor</span> <span class="identifier">acceptor</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">ep</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">acceptor</span><span class="special">.</span><span class="identifier">accept</span><span class="special">(</span><span class="identifier">socket</span><span class="special">);</span> +</pre> +<p> + A client that connects to this server might look like: + </p> +<pre class="programlisting"><span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">endpoint</span> <span class="identifier">ep</span><span class="special">(</span><span class="string">"/tmp/foobar"</span><span class="special">);</span> +<span class="identifier">local</span><span class="special">::</span><span class="identifier">stream_protocol</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">ep</span><span class="special">);</span> +</pre> +<p> + 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 <a class="link" href="../../reference/basic_socket/native.html" title="basic_socket::native">native()</a> + member function. + </p> +<h6> +<a name="boost_asio.overview.posix.local.h0"></a> + <span><a name="boost_asio.overview.posix.local.see_also"></a></span><a class="link" href="local.html#boost_asio.overview.posix.local.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/local__connect_pair.html" title="local::connect_pair">local::connect_pair</a>, + <a class="link" href="../../reference/local__datagram_protocol.html" title="local::datagram_protocol">local::datagram_protocol</a>, + <a class="link" href="../../reference/local__datagram_protocol/endpoint.html" title="local::datagram_protocol::endpoint">local::datagram_protocol::endpoint</a>, + <a class="link" href="../../reference/local__datagram_protocol/socket.html" title="local::datagram_protocol::socket">local::datagram_protocol::socket</a>, + <a class="link" href="../../reference/local__stream_protocol.html" title="local::stream_protocol">local::stream_protocol</a>, + <a class="link" href="../../reference/local__stream_protocol/acceptor.html" title="local::stream_protocol::acceptor">local::stream_protocol::acceptor</a>, + <a class="link" href="../../reference/local__stream_protocol/endpoint.html" title="local::stream_protocol::endpoint">local::stream_protocol::endpoint</a>, + <a class="link" href="../../reference/local__stream_protocol/iostream.html" title="local::stream_protocol::iostream">local::stream_protocol::iostream</a>, + <a class="link" href="../../reference/local__stream_protocol/socket.html" title="local::stream_protocol::socket">local::stream_protocol::socket</a>, + <a class="link" href="../../examples.html#boost_asio.examples.unix_domain_sockets">UNIX domain sockets + examples</a>. + </p> +<h6> +<a name="boost_asio.overview.posix.local.h1"></a> + <span><a name="boost_asio.overview.posix.local.notes"></a></span><a class="link" href="local.html#boost_asio.overview.posix.local.notes">Notes</a> + </h6> +<p> + UNIX domain sockets are only available at compile time if supported by + the target operating system. A program may test for the macro <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_LOCAL_SOCKETS</span></code> to determine + whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../posix.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="stream_descriptor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/posix/stream_descriptor.html b/doc/html/boost_asio/overview/posix/stream_descriptor.html new file mode 100755 index 0000000000..153c88ce72 --- /dev/null +++ b/doc/html/boost_asio/overview/posix/stream_descriptor.html @@ -0,0 +1,84 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Stream-Oriented File Descriptors</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../posix.html" title="POSIX-Specific Functionality"> +<link rel="prev" href="local.html" title="UNIX Domain Sockets"> +<link rel="next" href="fork.html" title="Fork"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="local.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="fork.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.posix.stream_descriptor"></a><a class="link" href="stream_descriptor.html" title="Stream-Oriented File Descriptors">Stream-Oriented + File Descriptors</a> +</h4></div></div></div> +<p> + 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 <span class="emphasis"><em>not</em></span> + regular files). + </p> +<p> + For example, to perform read and write operations on standard input and + output, the following objects may be created: + </p> +<pre class="programlisting"><span class="identifier">posix</span><span class="special">::</span><span class="identifier">stream_descriptor</span> <span class="identifier">in</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="special">::</span><span class="identifier">dup</span><span class="special">(</span><span class="identifier">STDIN_FILENO</span><span class="special">));</span> +<span class="identifier">posix</span><span class="special">::</span><span class="identifier">stream_descriptor</span> <span class="identifier">out</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="special">::</span><span class="identifier">dup</span><span class="special">(</span><span class="identifier">STDOUT_FILENO</span><span class="special">));</span> +</pre> +<p> + These are then used as synchronous or asynchronous read and write streams. + This means the objects can be used with any of the <a class="link" href="../../reference/read.html" title="read">read()</a>, + <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../../reference/write.html" title="write">write()</a>, <a class="link" href="../../reference/async_write.html" title="async_write">async_write()</a>, + <a class="link" href="../../reference/read_until.html" title="read_until">read_until()</a> or + <a class="link" href="../../reference/async_read_until.html" title="async_read_until">async_read_until()</a> + free functions. + </p> +<h6> +<a name="boost_asio.overview.posix.stream_descriptor.h0"></a> + <span><a name="boost_asio.overview.posix.stream_descriptor.see_also"></a></span><a class="link" href="stream_descriptor.html#boost_asio.overview.posix.stream_descriptor.see_also">See Also</a> + </h6> +<p> + <a class="link" href="../../reference/posix__stream_descriptor.html" title="posix::stream_descriptor">posix::stream_descriptor</a>, + <a class="link" href="../../reference/posix__basic_stream_descriptor.html" title="posix::basic_stream_descriptor">posix::basic_stream_descriptor</a>, + <a class="link" href="../../reference/posix__stream_descriptor_service.html" title="posix::stream_descriptor_service">posix::stream_descriptor_service</a>, + <a class="link" href="../../examples.html#boost_asio.examples.chat">Chat example</a>. + </p> +<h6> +<a name="boost_asio.overview.posix.stream_descriptor.h1"></a> + <span><a name="boost_asio.overview.posix.stream_descriptor.notes"></a></span><a class="link" href="stream_descriptor.html#boost_asio.overview.posix.stream_descriptor.notes">Notes</a> + </h6> +<p> + POSIX stream descriptors are only available at compile time if supported + by the target operating system. A program may test for the macro <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR</span></code> + to determine whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="local.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../posix.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="fork.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/rationale.html b/doc/html/boost_asio/overview/rationale.html new file mode 100755 index 0000000000..dc09b9033a --- /dev/null +++ b/doc/html/boost_asio/overview/rationale.html @@ -0,0 +1,103 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Rationale</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="../overview.html" title="Overview"> +<link rel="next" href="core.html" title="Core Concepts and Functionality"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../overview.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="core.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a> +</h3></div></div></div> +<p> + 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. + </p> +<p> + Boost.Asio provides the tools to manage these long running operations, without + requiring programs to use concurrency models based on threads and explicit + locking. + </p> +<p> + 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: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <span class="bold"><strong>Portability.</strong></span> The library should support + a range of commonly used operating systems, and provide consistent behaviour + across these operating systems. + </li> +<li class="listitem"> + <span class="bold"><strong>Scalability.</strong></span> 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. + </li> +<li class="listitem"> + <span class="bold"><strong>Efficiency.</strong></span> The library should support + techniques such as scatter-gather I/O, and allow programs to minimise + data copying. + </li> +<li class="listitem"> + <span class="bold"><strong>Model concepts from established APIs, such as BSD + sockets.</strong></span> 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. + </li> +<li class="listitem"> + <span class="bold"><strong>Ease of use.</strong></span> 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. + </li> +<li class="listitem"> + <span class="bold"><strong>Basis for further abstraction.</strong></span> 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. + </li> +</ul></div> +<p> + 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. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../overview.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="core.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/serial_ports.html b/doc/html/boost_asio/overview/serial_ports.html new file mode 100755 index 0000000000..f2d9ec3b3a --- /dev/null +++ b/doc/html/boost_asio/overview/serial_ports.html @@ -0,0 +1,91 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Serial Ports</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="timers.html" title="Timers"> +<link rel="next" href="signals.html" title="Signal Handling"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="timers.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="signals.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.serial_ports"></a><a class="link" href="serial_ports.html" title="Serial Ports">Serial Ports</a> +</h3></div></div></div> +<p> + Boost.Asio includes classes for creating and manipulating serial ports in + a portable manner. For example, a serial port may be opened using: + </p> +<pre class="programlisting"><span class="identifier">serial_port</span> <span class="identifier">port</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">name</span><span class="special">);</span> +</pre> +<p> + where name is something like <code class="computeroutput"><span class="string">"COM1"</span></code> + on Windows, and <code class="computeroutput"><span class="string">"/dev/ttyS0"</span></code> + on POSIX platforms. + </p> +<p> + Once opened, the serial port may be used as a <a class="link" href="core/streams.html" title="Streams, Short Reads and Short Writes">stream</a>. + This means the objects can be used with any of the <a class="link" href="../reference/read.html" title="read">read()</a>, + <a class="link" href="../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../reference/write.html" title="write">write()</a>, <a class="link" href="../reference/async_write.html" title="async_write">async_write()</a>, + <a class="link" href="../reference/read_until.html" title="read_until">read_until()</a> or <a class="link" href="../reference/async_read_until.html" title="async_read_until">async_read_until()</a> + free functions. + </p> +<p> + The serial port implementation also includes option classes for configuring + the port's baud rate, flow control type, parity, stop bits and character + size. + </p> +<h5> +<a name="boost_asio.overview.serial_ports.h0"></a> + <span><a name="boost_asio.overview.serial_ports.see_also"></a></span><a class="link" href="serial_ports.html#boost_asio.overview.serial_ports.see_also">See + Also</a> + </h5> +<p> + <a class="link" href="../reference/serial_port.html" title="serial_port">serial_port</a>, <a class="link" href="../reference/serial_port_base.html" title="serial_port_base">serial_port_base</a>, + <a class="link" href="../reference/basic_serial_port.html" title="basic_serial_port">basic_serial_port</a>, + <a class="link" href="../reference/serial_port_service.html" title="serial_port_service">serial_port_service</a>, + <a class="link" href="../reference/serial_port_base__baud_rate.html" title="serial_port_base::baud_rate">serial_port_base::baud_rate</a>, + <a class="link" href="../reference/serial_port_base__flow_control.html" title="serial_port_base::flow_control">serial_port_base::flow_control</a>, + <a class="link" href="../reference/serial_port_base__parity.html" title="serial_port_base::parity">serial_port_base::parity</a>, + <a class="link" href="../reference/serial_port_base__stop_bits.html" title="serial_port_base::stop_bits">serial_port_base::stop_bits</a>, + <a class="link" href="../reference/serial_port_base__character_size.html" title="serial_port_base::character_size">serial_port_base::character_size</a>. + </p> +<h5> +<a name="boost_asio.overview.serial_ports.h1"></a> + <span><a name="boost_asio.overview.serial_ports.notes"></a></span><a class="link" href="serial_ports.html#boost_asio.overview.serial_ports.notes">Notes</a> + </h5> +<p> + 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 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_SERIAL_PORTS</span></code> to determine + whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="timers.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="signals.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/signals.html b/doc/html/boost_asio/overview/signals.html new file mode 100755 index 0000000000..f24e16b006 --- /dev/null +++ b/doc/html/boost_asio/overview/signals.html @@ -0,0 +1,80 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Signal Handling</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="serial_ports.html" title="Serial Ports"> +<link rel="next" href="posix.html" title="POSIX-Specific Functionality"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="serial_ports.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.signals"></a><a class="link" href="signals.html" title="Signal Handling">Signal Handling</a> +</h3></div></div></div> +<p> + Boost.Asio supports signal handling using a class called <a class="link" href="../reference/signal_set.html" title="signal_set">signal_set</a>. + Programs may add one or more signals to the set, and then perform an <code class="computeroutput"><span class="identifier">async_wait</span><span class="special">()</span></code> + operation. The specified handler will be called when one of the signals occurs. + The same signal number may be registered with multiple <a class="link" href="../reference/signal_set.html" title="signal_set">signal_set</a> + objects, however the signal number must be used only with Boost.Asio. + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">handler</span><span class="special">(</span> + <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">error</span><span class="special">,</span> + <span class="keyword">int</span> <span class="identifier">signal_number</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">error</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// A signal occurred.</span> + <span class="special">}</span> +<span class="special">}</span> + +<span class="special">...</span> + +<span class="comment">// Construct a signal set registered for process termination.</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">signal_set</span> <span class="identifier">signals</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">,</span> <span class="identifier">SIGINT</span><span class="special">,</span> <span class="identifier">SIGTERM</span><span class="special">);</span> + +<span class="comment">// Start an asynchronous wait for one of the signals to occur.</span> +<span class="identifier">signals</span><span class="special">.</span><span class="identifier">async_wait</span><span class="special">(</span><span class="identifier">handler</span><span class="special">);</span> +</pre> +<p> + Signal handling also works on Windows, as the Microsoft Visual C++ runtime + library maps console events like Ctrl+C to the equivalent signal. + </p> +<h5> +<a name="boost_asio.overview.signals.h0"></a> + <span><a name="boost_asio.overview.signals.see_also"></a></span><a class="link" href="signals.html#boost_asio.overview.signals.see_also">See + Also</a> + </h5> +<p> + <a class="link" href="../reference/signal_set.html" title="signal_set">signal_set</a>, <a class="link" href="../examples.html#boost_asio.examples.http_server">HTTP server example</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="serial_ports.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/ssl.html b/doc/html/boost_asio/overview/ssl.html new file mode 100755 index 0000000000..b88863b3b8 --- /dev/null +++ b/doc/html/boost_asio/overview/ssl.html @@ -0,0 +1,192 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>SSL</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="windows/object_handle.html" title="Object HANDLEs"> +<link rel="next" href="cpp2011.html" title="C++ 2011 Support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="windows/object_handle.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp2011.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.ssl"></a><a class="link" href="ssl.html" title="SSL">SSL</a> +</h3></div></div></div> +<p> + 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. + </p> +<p> + 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: + </p> +<pre class="programlisting"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span> <span class="identifier">ctx</span><span class="special">(</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">sslv23</span><span class="special">);</span> +<span class="identifier">ctx</span><span class="special">.</span><span class="identifier">set_verify_mode</span><span class="special">(</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">verify_peer</span><span class="special">);</span> +<span class="identifier">ctx</span><span class="special">.</span><span class="identifier">load_verify_file</span><span class="special">(</span><span class="string">"ca.pem"</span><span class="special">);</span> +</pre> +<p> + To use SSL with a TCP socket, one may write: + </p> +<pre class="programlisting"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special"><</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">></span> <span class="identifier">ssl_sock</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">);</span> +</pre> +<p> + 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 <code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code> template's <a class="link" href="../reference/ssl__stream/lowest_layer.html" title="ssl::stream::lowest_layer"><code class="computeroutput"><span class="identifier">lowest_layer</span><span class="special">()</span></code></a> + member function: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">::</span><span class="identifier">lowest_layer_type</span><span class="special">&</span> <span class="identifier">sock</span> <span class="special">=</span> <span class="identifier">ssl_sock</span><span class="special">.</span><span class="identifier">lowest_layer</span><span class="special">();</span> +<span class="identifier">sock</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">my_endpoint</span><span class="special">);</span> +</pre> +<p> + 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: + </p> +<pre class="programlisting"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">sock</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">);</span> +<span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special"><</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&></span> <span class="identifier">ssl_sock</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">);</span> +</pre> +<p> + SSL handshaking must be performed prior to transmitting or receiving data + over an encrypted connection. This is accomplished using the <code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code> + template's <a class="link" href="../reference/ssl__stream/handshake.html" title="ssl::stream::handshake">handshake()</a> + or <a class="link" href="../reference/ssl__stream/async_handshake.html" title="ssl::stream::async_handshake">async_handshake()</a> + member functions. + </p> +<p> + 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 + <a class="link" href="../reference/read.html" title="read">read()</a>, <a class="link" href="../reference/async_read.html" title="async_read">async_read()</a>, + <a class="link" href="../reference/write.html" title="write">write()</a>, <a class="link" href="../reference/async_write.html" title="async_write">async_write()</a>, + <a class="link" href="../reference/read_until.html" title="read_until">read_until()</a> or <a class="link" href="../reference/async_read_until.html" title="async_read_until">async_read_until()</a> + free functions. + </p> +<h5> +<a name="boost_asio.overview.ssl.h0"></a> + <span><a name="boost_asio.overview.ssl.certificate_verification"></a></span><a class="link" href="ssl.html#boost_asio.overview.ssl.certificate_verification">Certificate + Verification</a> + </h5> +<p> + Boost.Asio provides various methods for configuring the way SSL certificates + are verified: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a class="link" href="../reference/ssl__context/set_default_verify_paths.html" title="ssl::context::set_default_verify_paths">ssl::context::set_default_verify_paths()</a> + </li> +<li class="listitem"> + <a class="link" href="../reference/ssl__context/set_verify_mode.html" title="ssl::context::set_verify_mode">ssl::context::set_verify_mode()</a> + </li> +<li class="listitem"> + <a class="link" href="../reference/ssl__context/set_verify_callback.html" title="ssl::context::set_verify_callback">ssl::context::set_verify_callback()</a> + </li> +<li class="listitem"> + <a class="link" href="../reference/ssl__context/load_verify_file.html" title="ssl::context::load_verify_file">ssl::context::load_verify_file()</a> + </li> +<li class="listitem"> + <a class="link" href="../reference/ssl__stream/set_verify_mode.html" title="ssl::stream::set_verify_mode">ssl::stream::set_verify_mode()</a> + </li> +<li class="listitem"> + <a class="link" href="../reference/ssl__stream/set_verify_callback.html" title="ssl::stream::set_verify_callback">ssl::stream::set_verify_callback()</a> + </li> +</ul></div> +<p> + To simplify use cases where certificates are verified according to the rules + in RFC 2818 (certificate verification for HTTPS), Boost.Asio provides a reusable + verification callback as a function object: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + <a class="link" href="../reference/ssl__rfc2818_verification.html" title="ssl::rfc2818_verification">ssl::rfc2818_verification</a> + </li></ul></div> +<p> + The following example shows verification of a remote host's certificate according + to the rules used by HTTPS: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">;</span> +<span class="keyword">namespace</span> <span class="identifier">ssl</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">;</span> +<span class="keyword">typedef</span> <span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">></span> <span class="identifier">ssl_socket</span><span class="special">;</span> + +<span class="comment">// Create a context that uses the default paths for</span> +<span class="comment">// finding CA certificates.</span> +<span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span> <span class="identifier">ctx</span><span class="special">(</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">sslv23</span><span class="special">);</span> +<span class="identifier">ctx</span><span class="special">.</span><span class="identifier">set_default_verify_paths</span><span class="special">();</span> + +<span class="comment">// Open a socket and connect it to the remote host.</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span> <span class="identifier">io_service</span><span class="special">;</span> +<span class="identifier">ssl_socket</span> <span class="identifier">sock</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">);</span> +<span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span> <span class="identifier">resolver</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">);</span> +<span class="identifier">tcp</span><span class="special">::</span><span class="identifier">resolver</span><span class="special">::</span><span class="identifier">query</span> <span class="identifier">query</span><span class="special">(</span><span class="string">"host.name"</span><span class="special">,</span> <span class="string">"https"</span><span class="special">);</span> +<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">sock</span><span class="special">.</span><span class="identifier">lowest_layer</span><span class="special">(),</span> <span class="identifier">resolver</span><span class="special">.</span><span class="identifier">resolve</span><span class="special">(</span><span class="identifier">query</span><span class="special">));</span> +<span class="identifier">sock</span><span class="special">.</span><span class="identifier">lowest_layer</span><span class="special">().</span><span class="identifier">set_option</span><span class="special">(</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">no_delay</span><span class="special">(</span><span class="keyword">true</span><span class="special">));</span> + +<span class="comment">// Perform SSL handshake and verify the remote host's</span> +<span class="comment">// certificate.</span> +<span class="identifier">sock</span><span class="special">.</span><span class="identifier">set_verify_mode</span><span class="special">(</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">verify_peer</span><span class="special">);</span> +<span class="identifier">sock</span><span class="special">.</span><span class="identifier">set_verify_callback</span><span class="special">(</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">rfc2818_verification</span><span class="special">(</span><span class="string">"host.name"</span><span class="special">));</span> +<span class="identifier">sock</span><span class="special">.</span><span class="identifier">handshake</span><span class="special">(</span><span class="identifier">ssl_socket</span><span class="special">::</span><span class="identifier">client</span><span class="special">);</span> + +<span class="comment">// ... read and write as normal ...</span> +</pre> +<h5> +<a name="boost_asio.overview.ssl.h1"></a> + <span><a name="boost_asio.overview.ssl.ssl_and_threads"></a></span><a class="link" href="ssl.html#boost_asio.overview.ssl.ssl_and_threads">SSL + and Threads</a> + </h5> +<p> + SSL stream objects perform no locking of their own. Therefore, it is essential + that all asynchronous SSL operations are performed in an implicit or explicit + <a class="link" href="core/strands.html" title="Strands: Use Threads Without Explicit Locking">strand</a>. Note that + this means that no synchronisation is required (and so no locking overhead + is incurred) in single threaded programs. + </p> +<h5> +<a name="boost_asio.overview.ssl.h2"></a> + <span><a name="boost_asio.overview.ssl.see_also"></a></span><a class="link" href="ssl.html#boost_asio.overview.ssl.see_also">See + Also</a> + </h5> +<p> + <a class="link" href="../reference/ssl__context.html" title="ssl::context">ssl::context</a>, <a class="link" href="../reference/ssl__rfc2818_verification.html" title="ssl::rfc2818_verification">ssl::rfc2818_verification</a>, + <a class="link" href="../reference/ssl__stream.html" title="ssl::stream">ssl::stream</a>, <a class="link" href="../examples.html#boost_asio.examples.ssl">SSL example</a>. + </p> +<h5> +<a name="boost_asio.overview.ssl.h3"></a> + <span><a name="boost_asio.overview.ssl.notes"></a></span><a class="link" href="ssl.html#boost_asio.overview.ssl.notes">Notes</a> + </h5> +<p> + <a href="http://www.openssl.org" target="_top">OpenSSL</a> 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 <a class="link" href="../reference/ssl__context/native_handle.html" title="ssl::context::native_handle"><code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">native_handle</span><span class="special">()</span></code></a> or <a class="link" href="../reference/ssl__stream/native_handle.html" title="ssl::stream::native_handle"><code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">::</span><span class="identifier">native_handle</span><span class="special">()</span></code></a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="windows/object_handle.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp2011.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/timers.html b/doc/html/boost_asio/overview/timers.html new file mode 100755 index 0000000000..162f4c5de0 --- /dev/null +++ b/doc/html/boost_asio/overview/timers.html @@ -0,0 +1,95 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Timers</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="networking/bsd_sockets.html" title="The BSD Socket API and Boost.Asio"> +<link rel="next" href="serial_ports.html" title="Serial Ports"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="networking/bsd_sockets.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="serial_ports.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.timers"></a><a class="link" href="timers.html" title="Timers">Timers</a> +</h3></div></div></div> +<p> + 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. + </p> +<p> + As a simple example, to perform a synchronous wait operation on a timer using + a relative time one may write: + </p> +<pre class="programlisting"><span class="identifier">io_service</span> <span class="identifier">i</span><span class="special">;</span> +<span class="special">...</span> +<span class="identifier">deadline_timer</span> <span class="identifier">t</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> +<span class="identifier">t</span><span class="special">.</span><span class="identifier">expires_from_now</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">5</span><span class="special">));</span> +<span class="identifier">t</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> +</pre> +<p> + More commonly, a program will perform an asynchronous wait operation on a + timer: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">handler</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> +<span class="special">...</span> +<span class="identifier">io_service</span> <span class="identifier">i</span><span class="special">;</span> +<span class="special">...</span> +<span class="identifier">deadline_timer</span> <span class="identifier">t</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> +<span class="identifier">t</span><span class="special">.</span><span class="identifier">expires_from_now</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">milliseconds</span><span class="special">(</span><span class="number">400</span><span class="special">));</span> +<span class="identifier">t</span><span class="special">.</span><span class="identifier">async_wait</span><span class="special">(</span><span class="identifier">handler</span><span class="special">);</span> +<span class="special">...</span> +<span class="identifier">i</span><span class="special">.</span><span class="identifier">run</span><span class="special">();</span> +</pre> +<p> + The deadline associated with a timer may also be obtained as a relative time: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">time_duration</span> <span class="identifier">time_until_expiry</span> + <span class="special">=</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">expires_from_now</span><span class="special">();</span> +</pre> +<p> + or as an absolute time to allow composition of timers: + </p> +<pre class="programlisting"><span class="identifier">deadline_timer</span> <span class="identifier">t2</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> +<span class="identifier">t2</span><span class="special">.</span><span class="identifier">expires_at</span><span class="special">(</span><span class="identifier">t</span><span class="special">.</span><span class="identifier">expires_at</span><span class="special">()</span> <span class="special">+</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">30</span><span class="special">));</span> +</pre> +<h5> +<a name="boost_asio.overview.timers.h0"></a> + <span><a name="boost_asio.overview.timers.see_also"></a></span><a class="link" href="timers.html#boost_asio.overview.timers.see_also">See + Also</a> + </h5> +<p> + <a class="link" href="../reference/basic_deadline_timer.html" title="basic_deadline_timer">basic_deadline_timer</a>, + <a class="link" href="../reference/deadline_timer.html" title="deadline_timer">deadline_timer</a>, + <a class="link" href="../reference/deadline_timer_service.html" title="deadline_timer_service">deadline_timer_service</a>, + <a class="link" href="../tutorial/tuttimer1.html" title="Timer.1 - Using a timer synchronously">timer tutorials</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="networking/bsd_sockets.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="serial_ports.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/windows.html b/doc/html/boost_asio/overview/windows.html new file mode 100755 index 0000000000..7824c9a6cb --- /dev/null +++ b/doc/html/boost_asio/overview/windows.html @@ -0,0 +1,54 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Windows-Specific Functionality</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../overview.html" title="Overview"> +<link rel="prev" href="posix/fork.html" title="Fork"> +<link rel="next" href="windows/stream_handle.html" title="Stream-Oriented HANDLEs"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="posix/fork.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="windows/stream_handle.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="boost_asio.overview.windows"></a><a class="link" href="windows.html" title="Windows-Specific Functionality">Windows-Specific Functionality</a> +</h3></div></div></div> +<p> + <a class="link" href="windows/stream_handle.html" title="Stream-Oriented HANDLEs">Stream-Oriented + HANDLEs</a> + </p> +<p> + <a class="link" href="windows/random_access_handle.html" title="Random-Access HANDLEs">Random-Access + HANDLEs</a> + </p> +<p> + <a class="link" href="windows/object_handle.html" title="Object HANDLEs">Object HANDLEs</a> + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="posix/fork.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="windows/stream_handle.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/windows/object_handle.html b/doc/html/boost_asio/overview/windows/object_handle.html new file mode 100755 index 0000000000..445ec62c86 --- /dev/null +++ b/doc/html/boost_asio/overview/windows/object_handle.html @@ -0,0 +1,105 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Object HANDLEs</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../windows.html" title="Windows-Specific Functionality"> +<link rel="prev" href="random_access_handle.html" title="Random-Access HANDLEs"> +<link rel="next" href="../ssl.html" title="SSL"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="random_access_handle.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../ssl.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.windows.object_handle"></a><a class="link" href="object_handle.html" title="Object HANDLEs">Object HANDLEs</a> +</h4></div></div></div> +<p> + Boost.Asio provides Windows-specific classes that permit asynchronous wait + operations to be performed on HANDLEs to kernel objects of the following + types: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Change notification + </li> +<li class="listitem"> + Console input + </li> +<li class="listitem"> + Event + </li> +<li class="listitem"> + Memory resource notification + </li> +<li class="listitem"> + Process + </li> +<li class="listitem"> + Semaphore + </li> +<li class="listitem"> + Thread + </li> +<li class="listitem"> + Waitable timer + </li> +</ul></div> +<p> + For example, to perform asynchronous operations on an event, the following + object may be created: + </p> +<pre class="programlisting"><span class="identifier">HANDLE</span> <span class="identifier">handle</span> <span class="special">=</span> <span class="special">::</span><span class="identifier">CreateEvent</span><span class="special">(...);</span> +<span class="identifier">windows</span><span class="special">::</span><span class="identifier">object_handle</span> <span class="identifier">file</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">handle</span><span class="special">);</span> +</pre> +<p> + The <code class="computeroutput"><span class="identifier">wait</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">async_wait</span><span class="special">()</span></code> + member functions may then be used to wait until the kernel object is signalled. + </p> +<h6> +<a name="boost_asio.overview.windows.object_handle.h0"></a> + <span><a name="boost_asio.overview.windows.object_handle.see_also"></a></span><a class="link" href="object_handle.html#boost_asio.overview.windows.object_handle.see_also">See Also</a> + </h6> +<p> + <a class="link" href="../../reference/windows__object_handle.html" title="windows::object_handle">windows::object_handle</a>, + <a class="link" href="../../reference/windows__basic_object_handle.html" title="windows::basic_object_handle">windows::basic_object_handle</a>, + <a class="link" href="../../reference/windows__object_handle_service.html" title="windows::object_handle_service">windows::object_handle_service</a>. + </p> +<h6> +<a name="boost_asio.overview.windows.object_handle.h1"></a> + <span><a name="boost_asio.overview.windows.object_handle.notes"></a></span><a class="link" href="object_handle.html#boost_asio.overview.windows.object_handle.notes">Notes</a> + </h6> +<p> + Windows object <code class="computeroutput"><span class="identifier">HANDLE</span></code>s + are only available at compile time when targeting Windows. Programs may + test for the macro <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE</span></code> + to determine whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="random_access_handle.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../ssl.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/windows/random_access_handle.html b/doc/html/boost_asio/overview/windows/random_access_handle.html new file mode 100755 index 0000000000..cdbacf477e --- /dev/null +++ b/doc/html/boost_asio/overview/windows/random_access_handle.html @@ -0,0 +1,88 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Random-Access HANDLEs</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../windows.html" title="Windows-Specific Functionality"> +<link rel="prev" href="stream_handle.html" title="Stream-Oriented HANDLEs"> +<link rel="next" href="object_handle.html" title="Object HANDLEs"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="stream_handle.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="object_handle.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.windows.random_access_handle"></a><a class="link" href="random_access_handle.html" title="Random-Access HANDLEs">Random-Access + HANDLEs</a> +</h4></div></div></div> +<p> + Boost.Asio provides Windows-specific classes that permit asynchronous read + and write operations to be performed on HANDLEs that refer to regular files. + </p> +<p> + For example, to perform asynchronous operations on a file the following + object may be created: + </p> +<pre class="programlisting"><span class="identifier">HANDLE</span> <span class="identifier">handle</span> <span class="special">=</span> <span class="special">::</span><span class="identifier">CreateFile</span><span class="special">(...);</span> +<span class="identifier">windows</span><span class="special">::</span><span class="identifier">random_access_handle</span> <span class="identifier">file</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">handle</span><span class="special">);</span> +</pre> +<p> + Data may be read from or written to the handle using one of the <code class="computeroutput"><span class="identifier">read_some_at</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">async_read_some_at</span><span class="special">()</span></code>, + <code class="computeroutput"><span class="identifier">write_some_at</span><span class="special">()</span></code> + or <code class="computeroutput"><span class="identifier">async_write_some_at</span><span class="special">()</span></code> member functions. However, like the equivalent + functions (<code class="computeroutput"><span class="identifier">read_some</span><span class="special">()</span></code>, + etc.) on streams, these functions are only required to transfer one or + more bytes in a single operation. Therefore free functions called <a class="link" href="../../reference/read_at.html" title="read_at">read_at()</a>, <a class="link" href="../../reference/async_read_at.html" title="async_read_at">async_read_at()</a>, + <a class="link" href="../../reference/write_at.html" title="write_at">write_at()</a> and <a class="link" href="../../reference/async_write_at.html" title="async_write_at">async_write_at()</a> have + been created to repeatedly call the corresponding <code class="literal"><span class="bold"><strong>*</strong></span>_some_at()</code> + function until all data has been transferred. + </p> +<h6> +<a name="boost_asio.overview.windows.random_access_handle.h0"></a> + <span><a name="boost_asio.overview.windows.random_access_handle.see_also"></a></span><a class="link" href="random_access_handle.html#boost_asio.overview.windows.random_access_handle.see_also">See + Also</a> + </h6> +<p> + <a class="link" href="../../reference/windows__random_access_handle.html" title="windows::random_access_handle">windows::random_access_handle</a>, + <a class="link" href="../../reference/windows__basic_random_access_handle.html" title="windows::basic_random_access_handle">windows::basic_random_access_handle</a>, + <a class="link" href="../../reference/windows__random_access_handle_service.html" title="windows::random_access_handle_service">windows::random_access_handle_service</a>. + </p> +<h6> +<a name="boost_asio.overview.windows.random_access_handle.h1"></a> + <span><a name="boost_asio.overview.windows.random_access_handle.notes"></a></span><a class="link" href="random_access_handle.html#boost_asio.overview.windows.random_access_handle.notes">Notes</a> + </h6> +<p> + Windows random-access <code class="computeroutput"><span class="identifier">HANDLE</span></code>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 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE</span></code> + to determine whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="stream_handle.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="object_handle.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/doc/html/boost_asio/overview/windows/stream_handle.html b/doc/html/boost_asio/overview/windows/stream_handle.html new file mode 100755 index 0000000000..d61a732203 --- /dev/null +++ b/doc/html/boost_asio/overview/windows/stream_handle.html @@ -0,0 +1,89 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Stream-Oriented HANDLEs</title> +<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../boost_asio.html" title="Boost.Asio"> +<link rel="up" href="../windows.html" title="Windows-Specific Functionality"> +<link rel="prev" href="../windows.html" title="Windows-Specific Functionality"> +<link rel="next" href="random_access_handle.html" title="Random-Access HANDLEs"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> +<td align="center"><a href="../../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../windows.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="random_access_handle.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boost_asio.overview.windows.stream_handle"></a><a class="link" href="stream_handle.html" title="Stream-Oriented HANDLEs">Stream-Oriented + HANDLEs</a> +</h4></div></div></div> +<p> + Boost.Asio contains classes to allow asynchronous read and write operations + to be performed on Windows <code class="computeroutput"><span class="identifier">HANDLE</span></code>s, + such as named pipes. + </p> +<p> + For example, to perform asynchronous operations on a named pipe, the following + object may be created: + </p> +<pre class="programlisting"><span class="identifier">HANDLE</span> <span class="identifier">handle</span> <span class="special">=</span> <span class="special">::</span><span class="identifier">CreateFile</span><span class="special">(...);</span> +<span class="identifier">windows</span><span class="special">::</span><span class="identifier">stream_handle</span> <span class="identifier">pipe</span><span class="special">(</span><span class="identifier">my_io_service</span><span class="special">,</span> <span class="identifier">handle</span><span class="special">);</span> +</pre> +<p> + These are then used as synchronous or asynchronous read and write streams. + This means the objects can be used with any of the <a class="link" href="../../reference/read.html" title="read">read()</a>, + <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../../reference/write.html" title="write">write()</a>, <a class="link" href="../../reference/async_write.html" title="async_write">async_write()</a>, + <a class="link" href="../../reference/read_until.html" title="read_until">read_until()</a> or + <a class="link" href="../../reference/async_read_until.html" title="async_read_until">async_read_until()</a> + free functions. + </p> +<p> + The kernel object referred to by the <code class="computeroutput"><span class="identifier">HANDLE</span></code> + must support use with I/O completion ports (which means that named pipes + are supported, but anonymous pipes and console streams are not). + </p> +<h6> +<a name="boost_asio.overview.windows.stream_handle.h0"></a> + <span><a name="boost_asio.overview.windows.stream_handle.see_also"></a></span><a class="link" href="stream_handle.html#boost_asio.overview.windows.stream_handle.see_also">See Also</a> + </h6> +<p> + <a class="link" href="../../reference/windows__stream_handle.html" title="windows::stream_handle">windows::stream_handle</a>, + <a class="link" href="../../reference/windows__basic_stream_handle.html" title="windows::basic_stream_handle">windows::basic_stream_handle</a>, + <a class="link" href="../../reference/windows__stream_handle_service.html" title="windows::stream_handle_service">windows::stream_handle_service</a>. + </p> +<h6> +<a name="boost_asio.overview.windows.stream_handle.h1"></a> + <span><a name="boost_asio.overview.windows.stream_handle.notes"></a></span><a class="link" href="stream_handle.html#boost_asio.overview.windows.stream_handle.notes">Notes</a> + </h6> +<p> + Windows stream <code class="computeroutput"><span class="identifier">HANDLE</span></code>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 <code class="computeroutput"><span class="identifier">BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE</span></code> + to determine whether they are supported. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2003-2012 Christopher M. Kohlhoff<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../windows.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../windows.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="random_access_handle.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> |