asio C++ library

PrevUpHomeNext

Using Asio

Supported Platforms

The following platform and compiler combinations are regularly tested:

The following platforms may also work:

Dependencies

The following libraries must be available in order to link programs that use Asio:

Furthermore, some of the examples also require Boost.Date_Time or Boost.Serialization libraries.

[Note] 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.

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>.

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.

Building the tests and examples with MSVC

To build using the MSVC 9.0 (or later) command line compiler, perform the following steps in a Command Prompt window:

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:

[Note] 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.

Macros

The macros listed in the table below may be used to control the behaviour of Asio.

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++ 11.0 or later, 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 macOS 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_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.

Mailing List

A mailing list specifically for Asio may be found on SourceForge.net. Newsgroup access is provided via Gmane.

Wiki

Users are encouraged to share examples, tips and FAQs on the Asio wiki, which is located at http://think-async.com/Asio/.


PrevUpHomeNext