diff options
Diffstat (limited to '3rdparty/asio/src/doc/using.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/using.qbk | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/using.qbk b/3rdparty/asio/src/doc/using.qbk new file mode 100644 index 00000000000..b4bcb01c831 --- /dev/null +++ b/3rdparty/asio/src/doc/using.qbk @@ -0,0 +1,316 @@ +[/ + / Copyright (c) 2003-2016 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 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. + +[heading Dependencies] + +The following libraries must be available in order to link programs that use +Asio: + +* Boost.Regex (optional) if you use any of the [link +asio.reference.read_until `read_until()`] or [link +asio.reference.async_read_until `async_read_until()`] overloads that take +a `boost::regex` parameter. + +* [@http://www.openssl.org OpenSSL] (optional) if you use Asio's SSL +support. + +Furthermore, some of the examples also require 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 Optional separate compilation] + +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 `#include +<asio/impl/src.hpp>` to one (and only one) source file in a program, then build +the program with `ASIO_SEPARATE_COMPILATION` defined in the project\/compiler +settings. Alternatively, `ASIO_DYN_LINK` may be defined to build a +separately-compiled Asio as part of a shared library. + +If using Asio's SSL support, you will also need to add `#include +<asio/ssl/impl/src.hpp>`. + +[heading Building the tests and examples on Linux or UNIX] + +If the boost directory (e.g. the directory called `boost_1_34_1`) is in the +same directory as the asio source kit, then you may configure asio by simply +going: + + ./configure + +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. + +If the boost directory is in some other location, then you need to +specify this directory when running configure: + + ./configure --with-boost=``['path_to_boost]`` + +When specifying the boost directory in this way you should ensure that you use +an absolute path. + +To build the examples, simply run `make` 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 `make check`. + +[heading Building the tests and examples with MSVC] + +To build using the MSVC 7.1 or MSVC 8.0 command line compiler, perform the +following steps in a Command Prompt window: + +* If you are using a version of boost other than 1.34.1, or if the boost + directory (i.e. the directory called `boost_1_34_1`) is not in the same + directory as the asio source kit, then specify the location of boost by + running a command similar to [^set BOOSTDIR=['path_to_boost]]. Ensure that + you specify an absolute path. + +* Change to the asio `src` directory. + +* Execute the command `nmake -f Makefile.msc`. + +* Execute the command `nmake -f Makefile.msc check` to run a suite of tests to + confirm that asio is working correctly. + +[heading Building the tests and examples with MinGW] + +To build using the MinGW g++ compiler from the command line, perform the +following steps in a Command Prompt window: + +* If you are using a version of boost other than 1.34.1, or if the boost + directory (i.e. the directory called `boost_1_34_1`) is not in the same + directory as the asio source kit, then specify the location of boost by + running a command similar to [^set BOOSTDIR=['path_to_boost]]. Ensure that + you specify an absolute path using ['forward slashes] (i.e. + `c:/projects/boost_1_34_1` rather than `c:\projects\boost_1_34_1`). + +* Change to the asio `src` directory. + +* Execute the command `make -f Makefile.mgw`. + +* Execute the command `make -f Makefile.mgw check` to run a suite of tests to + confirm that asio is working correctly. + +[note The above instructions do not work when building inside MSYS. If you want +to build using MSYS, you should use [^export] rather than [^set] to specify the +location of boost.] + +[heading Macros] + +The macros listed in the table below may be used to control the behaviour of +Asio. + +[table + [[Macro][Description]] + [ + [`ASIO_ENABLE_BUFFER_DEBUGGING`] + [ + 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). + + When using Microsoft Visual C++, this macro is defined automatically if + the compiler's iterator debugging support is enabled, unless + `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 + `ASIO_DISABLE_BUFFER_DEBUGGING` has been defined. + ] + ] + [ + [`ASIO_DISABLE_BUFFER_DEBUGGING`] + [ + Explictly disables Asio's buffer debugging support. + ] + ] + [ + [`ASIO_DISABLE_DEV_POLL`] + [ + Explicitly disables [^/dev/poll] support on Solaris, forcing the use of + a `select`-based implementation. + ] + ] + [ + [`ASIO_DISABLE_EPOLL`] + [ + Explicitly disables `epoll` support on Linux, forcing the use of a + `select`-based implementation. + ] + ] + [ + [`ASIO_DISABLE_EVENTFD`] + [ + Explicitly disables `eventfd` support on Linux, forcing the use of a + pipe to interrupt blocked epoll/select system calls. + ] + ] + [ + [`ASIO_DISABLE_KQUEUE`] + [ + Explicitly disables `kqueue` support on Mac OS X and BSD variants, + forcing the use of a `select`-based implementation. + ] + ] + [ + [`ASIO_DISABLE_IOCP`] + [ + Explicitly disables I/O completion ports support on Windows, forcing the + use of a `select`-based implementation. + ] + ] + [ + [`ASIO_DISABLE_THREADS`] + [ + Explicitly disables Asio's threading support, independent of whether or + not Boost supports threads. + ] + ] + [ + [`ASIO_NO_WIN32_LEAN_AND_MEAN`] + [ + By default, 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 + `ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from + being defined. + ] + ] + [ + [`ASIO_NO_NOMINMAX`] + [ + By default, Asio will automatically define `NOMINMAX` when compiling for + Windows, to suppress the definition of the `min()` and `max()` macros. + The presence of `ASIO_NO_NOMINMAX` prevents `NOMINMAX` from being + defined. + ] + ] + [ + [`ASIO_NO_DEFAULT_LINKED_LIBS`] + [ + 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. [^ws2_32.lib] and [^mswsock.lib], or [^ws2.lib] when + building for Windows CE). The `ASIO_NO_DEFAULT_LINKED_LIBS` macro + prevents these libraries from being linked. + ] + ] + [ + [`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. + ] + ] + [ + [`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. + ] + ] + [ + [`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 + ASIO_DISABLE_IOCP. + + * Use the socket object's close() function to simultaneously + cancel the outstanding operations and close the socket. + ] + ] + [ + [`ASIO_NO_TYPEID`] + [ + Disables uses of the `typeid` operator in asio. Defined automatically if + `BOOST_NO_TYPEID` is defined. + ] + ] + [ + [`ASIO_HASH_MAP_BUCKETS`] + [ + Determines the number of buckets in 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 `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 `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 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 Asio wiki, +which is located at [@http://think-async.com/Asio/]. + +[endsect] |