boost/asio
2
0
Fork 0
mirror of https://github.com/boostorg/asio.git synced 2026-01-28 06:42:08 +00:00
Code Issues Projects Releases Wiki Activity
Files
d499517905abf5deab322d32e2ba03b8a7e4e829
asio/doc/using.qbk
Christopher Kohlhoff 603397befb Merge from trunk. 
------------------------------------------------------------------------
r84301 | chris_kohlhoff | 2013-05-17 07:34:54 +1000 (Fri, 17 May 2013) | 2 lines

Enable handler type requirements static_assert on clang.

------------------------------------------------------------------------
r84308 | chris_kohlhoff | 2013-05-17 09:26:04 +1000 (Fri, 17 May 2013) | 3 lines

Add new traits classes, handler_type and async_result, that allow
the customisation of the return type of an initiating function.

------------------------------------------------------------------------
r84311 | chris_kohlhoff | 2013-05-17 11:38:47 +1000 (Fri, 17 May 2013) | 81 lines

Add the asio::spawn() function, a high-level wrapper for running
stackful coroutines. It is based on the Boost.Coroutine library.

Here is an example of its use:

  asio::spawn(my_strand, do_echo);

  // ...

  void do_echo(asio::yield_context yield)
  {
    try
    {
      char data[128];
      for (;;)
      {
        std::size_t length =
          my_socket.async_read_some(
            asio::buffer(data), yield);

        asio::async_write(my_socket,
            asio::buffer(data, length), yield);
      }
    }
    catch (std::exception& e)
    {
      // ...
    }
  }

The first argument to asio::spawn() may be a strand, io_service or
completion handler. This argument determines the context in which the
coroutine is permitted to execute. For example, a server's per-client
object may consist of multiple coroutines; they should all run on the
same strand so that no explicit synchronisation is required.

The second argument is a function object with signature (**):

  void coroutine(asio::yield_context yield);

that specifies the code to be run as part of the coroutine. The
parameter yield may be passed to an asynchronous operation in place of
the completion handler, as in:

  std::size_t length =
    my_socket.async_read_some(
      asio::buffer(data), yield);

This starts the asynchronous operation and suspends the coroutine. The
coroutine will be resumed automatically when the asynchronous operation
completes.

Where a completion handler signature has the form:

  void handler(error_code ec, result_type result);

the initiating function returns the result_type. In the async_read_some
example above, this is std::size_t. If the asynchronous operation fails,
the error_code is converted into a system_error exception and thrown.

Where a completion handler signature has the form:

  void handler(error_code ec);

the initiating function returns void. As above, an error is passed back
to the coroutine as a system_error exception.

To collect the error_code from an operation, rather than have it throw
an exception, associate the output variable with the yield_context as
follows:

  error_code ec;
  std::size_t length =
    my_socket.async_read_some(
      asio::buffer(data), yield[ec]);

**Note: if asio::spawn() is used with a custom completion handler of
type Handler, the function object signature is actually:
  
  void coroutine(asio::basic_yield_context<Handler> yield);

------------------------------------------------------------------------
r84312 | chris_kohlhoff | 2013-05-17 12:25:10 +1000 (Fri, 17 May 2013) | 4 lines

Move existing examples into a C++03-specific directory, and add a new
directory for C++11-specific examples. A limited subset of the C++03
examples have been converted to their C++11 equivalents.

------------------------------------------------------------------------
r84313 | chris_kohlhoff | 2013-05-17 12:35:08 +1000 (Fri, 17 May 2013) | 26 lines

Add the asio::use_future special value, which adds first-class support
for returning a C++11 std::future from an asynchronous operation's
initiating function.

To use asio::use_future, pass it to an asynchronous operation instead of
a normal completion handler. For example:

  std::future<std::size_t> length =
    my_socket.async_read_some(my_buffer, asio::use_future);

Where a completion handler signature has the form:

  void handler(error_code ec, result_type result);

the initiating function returns a std::future templated on result_type.
In the above example, this is std::size_t. If the asynchronous operation
fails, the error_code is converted into a system_error exception and
passed back to the caller through the future.

Where a completion handler signature has the form:

  void handler(error_code ec);

the initiating function returns std::future<void>. As above, an error
is passed back in the future as a system_error exception.

------------------------------------------------------------------------
r84314 | chris_kohlhoff | 2013-05-17 13:07:51 +1000 (Fri, 17 May 2013) | 27 lines

Add a new handler hook called asio_handler_is_continuation.

Asynchronous operations may represent a continuation of the asynchronous
control flow associated with the current handler. Asio's implementation
can use this knowledge to optimise scheduling of the handler.

The asio_handler_is_continuation hook returns true to indicate whether a
completion handler represents a continuation of the current call
context. The default implementation of the hook returns false, and
applications may customise the hook when necessary. The hook has already
been customised within Asio to return true for the following cases:

- Handlers returned by strand.wrap(), when the corresponding
  asynchronous operation is being initiated from within the strand.

- The internal handlers used to implement the asio::spawn() function's
  stackful coroutines.

- When an intermediate handler of a composed operation (e.g.
  asio::async_read(), asio::async_write(), asio::async_connect(),
  ssl::stream<>, etc.) starts a new asynchronous operation due to the
  composed operation not being complete.

To support this optimisation, a new running_in_this_thread() member
function has been added to the io_service::strand class. This function
returns true when called from within a strand.

------------------------------------------------------------------------
r84315 | chris_kohlhoff | 2013-05-17 20:06:50 +1000 (Fri, 17 May 2013) | 3 lines

Partially decouple Asio from other boost components via an extra level
of indirection.

------------------------------------------------------------------------
r84316 | chris_kohlhoff | 2013-05-17 20:15:21 +1000 (Fri, 17 May 2013) | 2 lines

Minor cleanup.

------------------------------------------------------------------------
r84319 | chris_kohlhoff | 2013-05-17 20:52:08 +1000 (Fri, 17 May 2013) | 9 lines

Support handshake with re-use of data already read from the wire.

Add new overloads of the SSL stream's handshake() and async_handshake()
functions, that accepts a ConstBufferSequence to be used as initial
input to the ssl engine for the handshake procedure.

Thanks go to Nick Jones <nick dot fa dot jones at gmail dot com>, on
whose work this commit is partially based.

------------------------------------------------------------------------
r84320 | chris_kohlhoff | 2013-05-17 20:57:02 +1000 (Fri, 17 May 2013) | 6 lines

Support for creation of TLSv1.1 and TLSv1.2 contexts.

Thanks go to Alvin Cheung <alvin dot cheung at alumni dot ust dot hk>
and Nick Jones <nick dot fa dot jones at gmail dot com>, on whose work
this is based.

------------------------------------------------------------------------
r84322 | chris_kohlhoff | 2013-05-17 21:00:49 +1000 (Fri, 17 May 2013) | 5 lines

Add set_verify_depth function to SSL context and stream.

Thanks go to Nick Jones <nick dot fa dot jones at gmail dot com>, on
whose work this commit is based.

------------------------------------------------------------------------
r84325 | chris_kohlhoff | 2013-05-17 21:04:11 +1000 (Fri, 17 May 2013) | 9 lines

Allow loading of SSL certificate and key data from memory buffers.

Added new buffer-based interfaces:
add_certificate_authority, use_certificate, use_certificate_chain,
use_private_key, use_rsa_private_key, use_tmp_dh.

Thanks go to Nick Jones <nick dot fa dot jones at gmail dot com>, on
whose work this commit is based.

------------------------------------------------------------------------
r84345 | chris_kohlhoff | 2013-05-18 21:24:59 +1000 (Sat, 18 May 2013) | 2 lines

Update copyright notices.

------------------------------------------------------------------------
r84346 | chris_kohlhoff | 2013-05-18 21:54:59 +1000 (Sat, 18 May 2013) | 3 lines

Remove the stackless coroutine class and macros from the HTTP server 4
example, and instead make them a part of Asio's documented interface.

------------------------------------------------------------------------
r84347 | chris_kohlhoff | 2013-05-18 22:01:59 +1000 (Sat, 18 May 2013) | 4 lines

Fix basic_waitable_timer's underlying implementation so that it can
handle any time_point value without overflowing the intermediate
duration objects.

------------------------------------------------------------------------
r84348 | chris_kohlhoff | 2013-05-18 22:07:00 +1000 (Sat, 18 May 2013) | 3 lines

Fix a problem with lost thread wakeups that can occur when making
concurrent calls to run() and poll() on the same io_service object.

------------------------------------------------------------------------
r84349 | chris_kohlhoff | 2013-05-18 22:13:17 +1000 (Sat, 18 May 2013) | 3 lines

Fix implementation of asynchronous connect operation so that it can cope
with spurious readiness notifications from the reactor.

------------------------------------------------------------------------
r84361 | chris_kohlhoff | 2013-05-19 07:56:31 +1000 (Sun, 19 May 2013) | 1 line

Remove some trailing spaces and fix another copyright notice.

------------------------------------------------------------------------
r84363 | chris_kohlhoff | 2013-05-19 14:55:11 +1000 (Sun, 19 May 2013) | 53 lines

Add generic socket protocols and converting move constructors.

Four new protocol classes have been added:

- asio::generic::datagram_protocol
- asio::generic::raw_protocol
- asio::generic::seq_packet_protocol
- asio::generic::stream_protocol

These classes implement the Protocol type requirements, but allow the
user to specify the address family (e.g. AF_INET) and protocol type
(e.g. IPPROTO_TCP) at runtime.

A new endpoint class template, asio::generic::basic_endpoint, has been
added to support these new protocol classes. This endpoint can hold any
other endpoint type, provided its native representation fits into a
sockaddr_storage object.

When using C++11, it is now possible to perform move construction from a
socket (or acceptor) object to convert to the more generic protocol's
socket (or acceptor) type. If the protocol conversion is valid:

  Protocol1 p1 = ...;
  Protocol2 p2(p1);

then the corresponding socket conversion is allowed:

  Protocol1::socket socket1(io_service);
  ...
  Protocol2::socket socket2(std::move(socket1));

For example, one possible conversion is from a TCP socket to a generic
stream-oriented socket:

  asio::ip::tcp::socket socket1(io_service);
  ...
  asio::generic::stream_protocol::socket socket2(std::move(socket1));

The conversion is also available for move-assignment. Note that these
conversions are not limited to the newly added generic protocol classes.
User-defined protocols may take advantage of this feature by similarly
ensuring the conversion from Protocol1 to Protocol2 is valid, as above.

As a convenience, the socket acceptor's accept() and async_accept()
functions have been changed so that they can directly accept into a
different protocol's socket type, provided the protocol conversion is
valid. For example, the following is now possible:

  asio::ip::tcp::acceptor acceptor(io_service);
  ...
  asio::generic::stream_protocol::socket socket1(io_service);
  acceptor.accept(socket1);


[SVN r84388]
2013-05-20 12:32:20 +00:00

336 lines
10 KiB
Plaintext
Raw Blame History

[/
/ Copyright (c) 2003-2013 Christopher M. Kohlhoff (chris at kohlhoff dot com)
/
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[section:using Using Boost.Asio]
[heading Supported Platforms]
The following platforms and compilers have been tested:
* Win32 and Win64 using Visual C++ 7.1 and Visual C++ 8.0.
* Win32 using MinGW.
* Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
* Linux (2.4 or 2.6 kernels) using g++ 3.3 or later.
* Solaris using g++ 3.3 or later.
* Mac OS X 10.4 using g++ 3.3 or later.
The following platforms may also work:
* AIX 5.3 using XL C/C++ v9.
* HP-UX 11i v3 using patched aC++ A.06.14.
* QNX Neutrino 6.3 using g++ 3.3 or later.
* Solaris using Sun Studio 11 or later.
* Tru64 v5.1 using Compaq C++ v7.1.
* Win32 using Borland C++ 5.9.2
[heading Dependencies]
The following libraries must be available in order to link programs that use
Boost.Asio:
* Boost.System for the `boost::system::error_code` and
`boost::system::system_error` classes.
* Boost.Regex (optional) if you use any of the [link
boost_asio.reference.read_until `read_until()`] or [link
boost_asio.reference.async_read_until `async_read_until()`] overloads that take
a `boost::regex` parameter.
* [@http://www.openssl.org OpenSSL] (optional) if you use Boost.Asio's SSL
support.
Furthermore, some of the examples also require the Boost.Thread,
Boost.Date_Time or Boost.Serialization libraries.
[note With MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB`
and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of
the Boost.Date_Time and Boost.Regex libraries respectively. Alternatively, you
may choose to build these libraries and link to them.]
[heading Building Boost Libraries]
You may build the subset of Boost libraries required to use Boost.Asio and its
examples by running the following command from the root of the Boost download
package:
[pre
bjam --with-system --with-thread --with-date_time --with-regex --with-serialization stage
]
This assumes that you have already built `bjam`. Consult the Boost.Build
documentation for more details.
[/
[heading Compiling Programs With Boost.Asio]
Consider the following minimal Boost.Asio program [^simple.cpp]:
#include <boost/asio.hpp>
#include <iostream>
#include <ostream>
int main()
{
boost::asio::ip::tcp::iostream s("www.boost.org", "http");
s << "GET / HTTP/1.0\r\n";
s << "Host: www.boost.org\r\n";
s << "\r\n" << std::flush;
std::cout << s.rdbuf();
return 0;
}
The following compiler commands may be used to build the program (note that the
name of the `boost_system` library may vary depending on the compiler version):
[table
[
[OS]
[Compiler]
[Command]
]
[
[FreeBSD]
[g++]
[[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc]]
]
[
[Linux]
[g++]
[[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc41]]
]
[
[Mac OS X]
[g++]
[[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system]]
]
[
[Solaris]
[g++]
[[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system -lsocket -lnsl -lpthread]]
]
[
[Windows]
[MSVC 7.1]
[[^cl /EHsc /GR /MT -I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link /libpath:['boost_root]/stage/lib]]
]
[
[Windows]
[MSVC 8.0]
[[^cl /EHsc /GR /MT /I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link /libpath:['boost_root]/stage/lib]]
]
]
]
[heading Optional separate compilation]
By default, Boost.Asio is a header-only library. However, some developers may
prefer to build Boost.Asio using separately compiled source code. To do this,
add `#include <boost/asio/impl/src.hpp>` to one (and only one) source file in a
program, then build the program with `BOOST_ASIO_SEPARATE_COMPILATION` defined
in the project\/compiler settings. Alternatively, `BOOST_ASIO_DYN_LINK` may be
defined to build a separately-compiled Boost.Asio as part of a shared library.
If using Boost.Asio's SSL support, you will also need to add `#include
<boost/asio/ssl/impl/src.hpp>`.
[heading Macros]
The macros listed in the table below may be used to control the behaviour of
Boost.Asio.
[table
[[Macro][Description]]
[
[`BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`]
[
Enables Boost.Asio's buffer debugging support, which can help identify when
invalid buffers are used in read or write operations (e.g. if a
std::string object being written is destroyed before the write operation
completes).
When using Microsoft Visual C++, this macro is defined automatically if
the compiler's iterator debugging support is enabled, unless
`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
When using g++, this macro is defined automatically if standard library
debugging is enabled (`_GLIBCXX_DEBUG` is defined), unless
`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
]
]
[
[`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING`]
[
Explictly disables Boost.Asio's buffer debugging support.
]
]
[
[`BOOST_ASIO_DISABLE_DEV_POLL`]
[
Explicitly disables [^/dev/poll] support on Solaris, forcing the use of
a `select`-based implementation.
]
]
[
[`BOOST_ASIO_DISABLE_EPOLL`]
[
Explicitly disables `epoll` support on Linux, forcing the use of a
`select`-based implementation.
]
]
[
[`BOOST_ASIO_DISABLE_EVENTFD`]
[
Explicitly disables `eventfd` support on Linux, forcing the use of a
pipe to interrupt blocked epoll/select system calls.
]
]
[
[`BOOST_ASIO_DISABLE_KQUEUE`]
[
Explicitly disables `kqueue` support on Mac OS X and BSD variants,
forcing the use of a `select`-based implementation.
]
]
[
[`BOOST_ASIO_DISABLE_IOCP`]
[
Explicitly disables I/O completion ports support on Windows, forcing the
use of a `select`-based implementation.
]
]
[
[`BOOST_ASIO_DISABLE_THREADS`]
[
Explicitly disables Boost.Asio's threading support, independent of whether
or not Boost as a whole supports threads.
]
]
[
[`BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN`]
[
By default, Boost.Asio will automatically define `WIN32_LEAN_AND_MEAN` when
compiling for Windows, to minimise the number of Windows SDK header files
and features that are included. The presence of
`BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from
being defined.
]
]
[
[`BOOST_ASIO_NO_NOMINMAX`]
[
By default, Boost.Asio will automatically define `NOMINMAX` when
compiling for Windows, to suppress the definition of the `min()` and
`max()` macros. The presence of `BOOST_ASIO_NO_NOMINMAX` prevents
`NOMINMAX` from being defined.
]
]
[
[`BOOST_ASIO_NO_DEFAULT_LINKED_LIBS`]
[
When compiling for Windows using Microsoft Visual C++ or Borland C++, Boost.Asio
will automatically link in the necessary Windows SDK libraries for sockets
support (i.e. [^ws2_32.lib] and [^mswsock.lib], or [^ws2.lib] when
building for Windows CE). The `BOOST_ASIO_NO_DEFAULT_LINKED_LIBS` macro
prevents these libraries from being linked.
]
]
[
[`BOOST_ASIO_SOCKET_STREAMBUF_MAX_ARITY`]
[
Determines the maximum number of arguments that may be passed to the
`basic_socket_streambuf` class template's `connect` member function.
Defaults to 5.
]
]
[
[`BOOST_ASIO_SOCKET_IOSTREAM_MAX_ARITY`]
[
Determines the maximum number of arguments that may be passed to the
`basic_socket_iostream` class template's constructor and `connect` member
function. Defaults to 5.
]
]
[
[`BOOST_ASIO_ENABLE_CANCELIO`]
[
Enables use of the `CancelIo` function on older versions of Windows. If
not enabled, calls to `cancel()` on a socket object will always fail with
`asio::error::operation_not_supported` when run on Windows XP, Windows
Server 2003, and earlier versions of Windows. When running on Windows
Vista, Windows Server 2008, and later, the `CancelIoEx` function is
always used.
The `CancelIo` function has two issues that should be considered before
enabling its use:
* It will only cancel asynchronous operations that were initiated in the
current thread.
* It can appear to complete without error, but the request
to cancel the unfinished operations may be silently ignored by the
operating system. Whether it works or not seems to depend on the
drivers that are installed.
For portable cancellation, consider using one of the following
alternatives:
* Disable asio's I/O completion port backend by defining
BOOST_ASIO_DISABLE_IOCP.
* Use the socket object's close() function to simultaneously
cancel the outstanding operations and close the socket.
]
]
[
[`BOOST_ASIO_NO_TYPEID`]
[
Disables uses of the `typeid` operator in Boost.Asio. Defined
automatically if `BOOST_NO_TYPEID` is defined.
]
]
[
[`BOOST_ASIO_HASH_MAP_BUCKETS`]
[
Determines the number of buckets in Boost.Asio's internal `hash_map`
objects. The value should be a comma separated list of prime numbers, in
ascending order. The `hash_map` implementation will automatically
increase the number of buckets as the number of elements in the map
increases.
Some examples:
* Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `1021` means that the
`hash_map` objects will always contain 1021 buckets, irrespective of
the number of elements in the map.
* Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `53,389,1543` means that the
`hash_map` objects will initially contain 53 buckets. The number of
buckets will be increased to 389 and then 1543 as elements are added to
the map.
]
]
]
[heading Mailing List]
A mailing list specifically for Boost.Asio may be found on
[@http://sourceforge.net/mail/?group_id=122478 SourceForge.net]. Newsgroup
access is provided via [@http://dir.gmane.org/gmane.comp.lib.boost.asio.user
Gmane].
[heading Wiki]
Users are encouraged to share examples, tips and FAQs on the Boost.Asio wiki,
which is located at [@http://think-async.com/Asio/].
[endsect]
Reference in New Issue View Git Blame Copy Permalink