Files
plains/lib/asio-1.18.0/doc/asio/using.html
T

550 lines
22 KiB
HTML

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Using Asio</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Asio">
<link rel="up" href="../index.html" title="Asio">
<link rel="prev" href="overview/implementation.html" title="Platform-Specific Implementation Notes">
<link rel="next" href="tutorial.html" title="Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../asio.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview/implementation.html"><img src="../prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="asio.using"></a><a class="link" href="using.html" title="Using Asio">Using Asio</a>
</h2></div></div></div>
<h4>
<a name="asio.using.h0"></a>
<span><a name="asio.using.supported_platforms"></a></span><a class="link" href="using.html#asio.using.supported_platforms">Supported
Platforms</a>
</h4>
<p>
The following platform and compiler combinations are regularly tested:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Linux using g++ 4.1 or later
</li>
<li class="listitem">
Linux using clang 3.2 or later
</li>
<li class="listitem">
FreeBSD using g++ 4.1 or later
</li>
<li class="listitem">
macOS using Xcode 8 or later
</li>
<li class="listitem">
Win32 using Visual C++ 9.0 or later
</li>
<li class="listitem">
Win32 using g++ 4.1 or later (MinGW)
</li>
<li class="listitem">
Win64 using Visual C++ 9.0 or later
</li>
</ul></div>
<p>
The following platforms may also work:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
AIX
</li>
<li class="listitem">
Android
</li>
<li class="listitem">
HP-UX
</li>
<li class="listitem">
iOS
</li>
<li class="listitem">
NetBSD
</li>
<li class="listitem">
OpenBSD
</li>
<li class="listitem">
QNX Neutrino
</li>
<li class="listitem">
Solaris
</li>
<li class="listitem">
Tru64
</li>
<li class="listitem">
Win32 using Cygwin. (<code class="computeroutput">__USE_W32_SOCKETS</code> must be defined.)
</li>
</ul></div>
<h4>
<a name="asio.using.h1"></a>
<span><a name="asio.using.dependencies"></a></span><a class="link" href="using.html#asio.using.dependencies">Dependencies</a>
</h4>
<p>
The following libraries must be available in order to link programs that use
Asio:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Boost.Coroutine (optional) if you use <a class="link" href="reference/spawn.html" title="spawn"><code class="computeroutput">spawn()</code></a>
to launch coroutines.
</li>
<li class="listitem">
Boost.Regex (optional) if you use any of the <a class="link" href="reference/read_until.html" title="read_until"><code class="computeroutput">read_until()</code></a>
or <a class="link" href="reference/async_read_until.html" title="async_read_until"><code class="computeroutput">async_read_until()</code></a>
overloads that take a <code class="computeroutput">boost::regex</code> parameter.
</li>
<li class="listitem">
<a href="http://www.openssl.org" target="_top">OpenSSL</a> (optional) if you use
Asio's SSL support.
</li>
</ul></div>
<p>
Furthermore, some of the examples also require Boost.Date_Time or Boost.Serialization
libraries.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
With MSVC or Borland C++ you may want to add <code class="computeroutput">-DBOOST_DATE_TIME_NO_LIB</code>
and <code class="computeroutput">-DBOOST_REGEX_NO_LIB</code> 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.
</p></td></tr>
</table></div>
<h4>
<a name="asio.using.h2"></a>
<span><a name="asio.using.optional_separate_compilation"></a></span><a class="link" href="using.html#asio.using.optional_separate_compilation">Optional
separate compilation</a>
</h4>
<p>
By default, Asio is a header-only library. However, some developers may prefer
to build Asio using separately compiled source code. To do this, add <code class="computeroutput">#include
&lt;asio/impl/src.hpp&gt;</code> to one (and only one) source file in a program,
then build the program with <code class="computeroutput">ASIO_SEPARATE_COMPILATION</code> defined
in the project/compiler settings. Alternatively, <code class="computeroutput">ASIO_DYN_LINK</code>
may be defined to build a separately-compiled Asio as part of a shared library.
</p>
<p>
If using Asio's SSL support, you will also need to add <code class="computeroutput">#include &lt;asio/ssl/impl/src.hpp&gt;</code>.
</p>
<h4>
<a name="asio.using.h3"></a>
<span><a name="asio.using.building_the_tests_and_examples_on_linux_or_unix"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_on_linux_or_unix">Building
the tests and examples on Linux or UNIX</a>
</h4>
<p>
If the boost directory (e.g. the directory called <code class="computeroutput">boost_1_34_1</code>)
is in the same directory as the asio source kit, then you may configure asio
by simply going:
</p>
<pre class="programlisting">./configure
</pre>
<p>
in the root directory of the asio source kit. Note that configure will always
use the most recent boost version it knows about (i.e. 1.34.1) in preference
to earlier versions, if there is more than one version present.
</p>
<p>
If the boost directory is in some other location, then you need to specify
this directory when running configure:
</p>
<pre class="programlisting">./configure --with-boost=<span class="emphasis"><em>path_to_boost</em></span>
</pre>
<p>
When specifying the boost directory in this way you should ensure that you
use an absolute path.
</p>
<p>
To build the examples, simply run <code class="computeroutput">make</code> in the root directory of
the asio source kit. To also build and run the unit tests, to confirm that
asio is working correctly, run <code class="computeroutput">make check</code>.
</p>
<h4>
<a name="asio.using.h4"></a>
<span><a name="asio.using.building_the_tests_and_examples_with_msvc"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_with_msvc">Building
the tests and examples with MSVC</a>
</h4>
<p>
To build using the MSVC 9.0 (or later) command line compiler, perform the following
steps in a Command Prompt window:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
If you are using a version of boost other than 1.34.1, or if the boost
directory (i.e. the directory called <code class="computeroutput">boost_1_34_1</code>) is not
in the same directory as the asio source kit, then specify the location
of boost by running a command similar to <code class="literal">set BOOSTDIR=<span class="emphasis"><em>path_to_boost</em></span></code>.
Ensure that you specify an absolute path.
</li>
<li class="listitem">
Change to the asio <code class="computeroutput">src</code> directory.
</li>
<li class="listitem">
Execute the command <code class="computeroutput">nmake -f Makefile.msc</code>.
</li>
<li class="listitem">
Execute the command <code class="computeroutput">nmake -f Makefile.msc check</code> to run a suite
of tests to confirm that asio is working correctly.
</li>
</ul></div>
<h4>
<a name="asio.using.h5"></a>
<span><a name="asio.using.building_the_tests_and_examples_with_mingw"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_with_mingw">Building
the tests and examples with MinGW</a>
</h4>
<p>
To build using the MinGW g++ compiler from the command line, perform the following
steps in a Command Prompt window:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
If you are using a version of boost other than 1.34.1, or if the boost
directory (i.e. the directory called <code class="computeroutput">boost_1_34_1</code>) is not
in the same directory as the asio source kit, then specify the location
of boost by running a command similar to <code class="literal">set BOOSTDIR=<span class="emphasis"><em>path_to_boost</em></span></code>.
Ensure that you specify an absolute path using <span class="emphasis"><em>forward slashes</em></span>
(i.e. <code class="computeroutput">c:/projects/boost_1_34_1</code> rather than <code class="computeroutput">c:\projects\boost_1_34_1</code>).
</li>
<li class="listitem">
Change to the asio <code class="computeroutput">src</code> directory.
</li>
<li class="listitem">
Execute the command <code class="computeroutput">make -f Makefile.mgw</code>.
</li>
<li class="listitem">
Execute the command <code class="computeroutput">make -f Makefile.mgw check</code> to run a suite
of tests to confirm that asio is working correctly.
</li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
The above instructions do not work when building inside MSYS. If you want
to build using MSYS, you should use <code class="literal">export</code> rather than
<code class="literal">set</code> to specify the location of boost.
</p></td></tr>
</table></div>
<h4>
<a name="asio.using.h6"></a>
<span><a name="asio.using.macros"></a></span><a class="link" href="using.html#asio.using.macros">Macros</a>
</h4>
<p>
The macros listed in the table below may be used to control the behaviour of
Asio.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Macro
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_ENABLE_BUFFER_DEBUGGING</code>
</p>
</td>
<td>
<p>
Enables 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).
</p>
<p>
When using Microsoft Visual C++ 11.0 or later, this macro is defined
automatically if the compiler's iterator debugging support is enabled,
unless <code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code> has been defined.
</p>
<p>
When using g++, this macro is defined automatically if standard library
debugging is enabled (<code class="computeroutput">_GLIBCXX_DEBUG</code> is defined), unless
<code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code> has been defined.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code>
</p>
</td>
<td>
<p>
Explictly disables Asio's buffer debugging support.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_DEV_POLL</code>
</p>
</td>
<td>
<p>
Explicitly disables <code class="literal">/dev/poll</code> support on Solaris,
forcing the use of a <code class="computeroutput">select</code>-based implementation.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_EPOLL</code>
</p>
</td>
<td>
<p>
Explicitly disables <code class="computeroutput">epoll</code> support on Linux, forcing
the use of a <code class="computeroutput">select</code>-based implementation.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_EVENTFD</code>
</p>
</td>
<td>
<p>
Explicitly disables <code class="computeroutput">eventfd</code> support on Linux, forcing
the use of a pipe to interrupt blocked epoll/select system calls.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_KQUEUE</code>
</p>
</td>
<td>
<p>
Explicitly disables <code class="computeroutput">kqueue</code> support on macOS and BSD
variants, forcing the use of a <code class="computeroutput">select</code>-based implementation.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_IOCP</code>
</p>
</td>
<td>
<p>
Explicitly disables I/O completion ports support on Windows, forcing
the use of a <code class="computeroutput">select</code>-based implementation.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_DISABLE_THREADS</code>
</p>
</td>
<td>
<p>
Explicitly disables Asio's threading support, independent of whether
or not Boost supports threads.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_NO_WIN32_LEAN_AND_MEAN</code>
</p>
</td>
<td>
<p>
By default, Asio will automatically define <code class="computeroutput">WIN32_LEAN_AND_MEAN</code>
when compiling for Windows, to minimise the number of Windows SDK
header files and features that are included. The presence of <code class="computeroutput">ASIO_NO_WIN32_LEAN_AND_MEAN</code>
prevents <code class="computeroutput">WIN32_LEAN_AND_MEAN</code> from being defined.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_NO_NOMINMAX</code>
</p>
</td>
<td>
<p>
By default, Asio will automatically define <code class="computeroutput">NOMINMAX</code>
when compiling for Windows, to suppress the definition of the <code class="computeroutput">min()</code>
and <code class="computeroutput">max()</code> macros. The presence of <code class="computeroutput">ASIO_NO_NOMINMAX</code>
prevents <code class="computeroutput">NOMINMAX</code> from being defined.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_NO_DEFAULT_LINKED_LIBS</code>
</p>
</td>
<td>
<p>
When compiling for Windows using Microsoft Visual C++ or Borland
C++, Asio will automatically link in the necessary Windows SDK libraries
for sockets support (i.e. <code class="literal">ws2_32.lib</code> and <code class="literal">mswsock.lib</code>,
or <code class="literal">ws2.lib</code> when building for Windows CE). The
<code class="computeroutput">ASIO_NO_DEFAULT_LINKED_LIBS</code> macro prevents these libraries
from being linked.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_ENABLE_CANCELIO</code>
</p>
</td>
<td>
<p>
Enables use of the <code class="computeroutput">CancelIo</code> function on older versions
of Windows. If not enabled, calls to <code class="computeroutput">cancel()</code> on a socket
object will always fail with <code class="computeroutput">asio::error::operation_not_supported</code>
when run on Windows XP, Windows Server 2003, and earlier versions
of Windows. When running on Windows Vista, Windows Server 2008, and
later, the <code class="computeroutput">CancelIoEx</code> function is always used.
</p>
<p>
The <code class="computeroutput">CancelIo</code> function has two issues that should be
considered before enabling its use:
</p>
<p>
* It will only cancel asynchronous operations that were initiated
in the current thread.
</p>
<p>
* 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.
</p>
<p>
For portable cancellation, consider using one of the following alternatives:
</p>
<p>
* Disable asio's I/O completion port backend by defining ASIO_DISABLE_IOCP.
</p>
<p>
* Use the socket object's close() function to simultaneously cancel
the outstanding operations and close the socket.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_NO_TYPEID</code>
</p>
</td>
<td>
<p>
Disables uses of the <code class="computeroutput">typeid</code> operator in asio. Defined
automatically if <code class="computeroutput">BOOST_NO_TYPEID</code> is defined.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code>
</p>
</td>
<td>
<p>
Determines the number of buckets in asio's internal <code class="computeroutput">hash_map</code>
objects. The value should be a comma separated list of prime numbers,
in ascending order. The <code class="computeroutput">hash_map</code> implementation will
automatically increase the number of buckets as the number of elements
in the map increases.
</p>
<p>
Some examples:
</p>
<p>
* Defining <code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">1021</code>
means that the <code class="computeroutput">hash_map</code> objects will always contain
1021 buckets, irrespective of the number of elements in the map.
</p>
<p>
* Defining <code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">53,389,1543</code>
means that the <code class="computeroutput">hash_map</code> 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.
</p>
</td>
</tr>
</tbody>
</table></div>
<h4>
<a name="asio.using.h7"></a>
<span><a name="asio.using.mailing_list"></a></span><a class="link" href="using.html#asio.using.mailing_list">Mailing
List</a>
</h4>
<p>
A mailing list specifically for Asio may be found on <a href="http://sourceforge.net/mail/?group_id=122478" target="_top">SourceForge.net</a>.
Newsgroup access is provided via <a href="http://dir.gmane.org/gmane.comp.lib.boost.asio.user" target="_top">Gmane</a>.
</p>
<h4>
<a name="asio.using.h8"></a>
<span><a name="asio.using.wiki"></a></span><a class="link" href="using.html#asio.using.wiki">Wiki</a>
</h4>
<p>
Users are encouraged to share examples, tips and FAQs on the Asio wiki, which
is located at <a href="http://think-async.com/Asio/" target="_top">http://think-async.com/Asio/</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-2020 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/implementation.html"><img src="../prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../next.png" alt="Next"></a>
</div>
</body>
</html>