asio C++ library

PrevUpHomeNext

Using, Building, and Configuring 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 interface, functionality, and behaviour of Asio.

Macro

Description

ASIO_NO_DEPRECATED

Disables Asio's deprecated interfaces and functionality.

See Networking TS Compatibility for a list of older interfaces that have been deprecated, and their replacements.

ASIO_NO_TS_EXECUTORS

Disables Asio's support for the Networking TS executor model.

By default, Asio simultaneously supports both Networking TS-style executors, and executors that adhere to the proposed standard executor model. This macro may be used to limit support to the proposed standard executors only. See Proposed Standard Executors for more information.

ASIO_USE_TS_EXECUTOR_AS_DEFAULT

Specifies that any_io_executor refer to the Networking TS-style polymorphic wrapper.

The any_io_executor type alias is the default runtime-polymorphic executor for all I/O objects. This type alias points to the execution::any_executor<> template with a set of supportable properties specified for use with I/O.

This new name may break existing code that directly uses the old Networking TS-style polymorphic wrapper, executor. If required for backward compatibility, ASIO_USE_TS_EXECUTOR_AS_DEFAULT changes the any_io_executor type alias to instead point to the executor polymorphic wrapper.

See Proposed Standard Executors for more information.

ASIO_NO_DYNAMIC_BUFFER_V1

Disables support for the DynamicBuffer_v1 type requirements.

By default, dynamic buffer operations such as read, async_read, read_until, async_read_until, write, and async_write support both the DynamicBuffer_v1 and the DynamicBuffer_v2 type requirements for dynamic buffers.

When ASIO_NO_DYNAMIC_BUFFER_V1 is defined, all support for DynamicBuffer_v1 types and functions is #ifdef-ed out. Support for using basic_streambuf with the read, async_read, read_until, async_read_until, write, and async_write functions is also disabled as a consequence.

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_ENABLE_HANDLER_TRACKING

Enables Asio's Handler Tracking debugging facility.

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.

ASIO_USE_BOOST_DATE_TIME_FOR_SOCKET_IOSTREAM

Changes basic_socket_streambuf and basic_socket_iostream to use the old Boost.Date_Time interface, rather than chrono.

ASIO_SEPARATE_COMPILATION

Uses separately compiled source code for Asio's implementation.

See above for further information.

ASIO_DYN_LINK

Uses separately compiled source code for Asio's implementation, with symbols exported for inclusion as part of a shared library.

See above for further information.

ASIO_DISABLE_VISIBILITY

Disables all symbol visibility pragmas.

Note: If symbols are hidden, extra care must be taken to ensure that Asio types are not passed across shared library API boundaries.

Compiler/platform feature detection macros

Asio automatically defines preprocessor macros corresponding to the detected available features on a particular compiler and target platform. These macros are named with the prefix ASIO_HAS_, and are listed in the table below.

Many of these macros also have a corresponding ASIO_DISABLE_ macro that may be used to explicitly disable the feature.

In general, ASIO_HAS_ macros should not be explicitly defined by the user, except when absolutely required as a workaround for the latest version of a compiler or platform. For older compiler/platform combinations where a specific ASIO_HAS_ macro is not automatically defined, testing may have shown that a claimed feature isn't sufficiently conformant to be compatible with Asio's needs.

Macro

Description

Macro to disable feature

ASIO_HAS_ALIAS_TEMPLATES

Support alias templates on compilers known to allow it.

ASIO_DISABLE_ALIAS_TEMPLATES

ASIO_HAS_ALIGNED_NEW

Support for operator new with alignment argument.

ASIO_DISABLE_ALIGNED_NEW

ASIO_HAS_ALIGNOF

Support for the alignof operator.

ASIO_DISABLE_ALIGNOF

ASIO_HAS_BOOST_ALIGN

Boost align library.

ASIO_DISABLE_BOOST_ALIGN

ASIO_HAS_BOOST_ARRAY

Boost array library.

ASIO_DISABLE_BOOST_ARRAY

ASIO_HAS_BOOST_ASSERT

Boost assert macro.

ASIO_DISABLE_BOOST_ASSERT

ASIO_HAS_BOOST_BIND

Boost bind function.

ASIO_DISABLE_BOOST_BIND

ASIO_HAS_BOOST_CHRONO

Boost support for chrono.

ASIO_DISABLE_BOOST_CHRONO

ASIO_HAS_BOOST_CONFIG

boostify: non-boost code ends here

ASIO_HAS_BOOST_DATE_TIME

Boost support for the DateTime library.

ASIO_DISABLE_BOOST_DATE_TIME

ASIO_HAS_BOOST_LIMITS

Boost limits header.

ASIO_DISABLE_BOOST_LIMITS

ASIO_HAS_BOOST_REGEX

Boost regex library.

ASIO_DISABLE_BOOST_REGEX

ASIO_HAS_BOOST_THROW_EXCEPTION

Boost throw_exception function.

ASIO_DISABLE_BOOST_THROW_EXCEPTION

ASIO_HAS_BOOST_WORKAROUND

Boost's BOOST_WORKAROUND macro.

ASIO_DISABLE_BOOST_WORKAROUND

ASIO_HAS_CHRONO

Some form of chrono library is available.

ASIO_HAS_CLANG_LIBCXX

Clang / libc++ detection.

ASIO_HAS_CONCEPTS

Support concepts on compilers known to allow them.

ASIO_DISABLE_CONCEPTS

ASIO_HAS_CONSTANT_EXPRESSION_SFINAE

Support SFINAE use of constant expressions on compilers known to allow it.

ASIO_DISABLE_CONSTANT_EXPRESSION_SFINAE

ASIO_HAS_CONSTEXPR

Support constexpr on compilers known to allow it.

ASIO_DISABLE_CONSTEXPR

ASIO_HAS_CO_AWAIT

Support the co_await keyword on compilers known to allow it.

ASIO_DISABLE_CO_AWAIT

ASIO_HAS_CSTDINT

Standard library support for the cstdint header.

ASIO_DISABLE_CSTDINT

ASIO_HAS_CXX11_ALLOCATORS

Standard library support for the C++11 allocator additions.

ASIO_DISABLE_CXX11_ALLOCATORS

ASIO_HAS_DECLTYPE

Support automatic type deduction on compilers known to support it.

ASIO_DISABLE_DECLTYPE

ASIO_HAS_DEFAULT_FUNCTION_TEMPLATE_ARGUMENTS

Support default function template arguments on compilers known to allow it.

ASIO_DISABLE_DEFAULT_FUNCTION_TEMPLATE_ARGUMENTS

ASIO_HAS_DEV_POLL

Solaris: /dev/poll.

ASIO_DISABLE_DEV_POLL

ASIO_HAS_EPOLL

Linux: epoll, eventfd and timerfd.

ASIO_DISABLE_EPOLL

ASIO_HAS_EVENTFD

Linux: epoll, eventfd and timerfd.

ASIO_DISABLE_EVENTFD

ASIO_HAS_GETADDRINFO

Can use getaddrinfo() and getnameinfo().

ASIO_DISABLE_GETADDRINFO

ASIO_HAS_HANDLER_HOOKS

Handler hooking. Disabled for ancient Borland C++ and gcc compilers.

ASIO_DISABLE_HANDLER_HOOKS

ASIO_HAS_IOCP

Windows: IO Completion Ports.

ASIO_DISABLE_IOCP

ASIO_HAS_KQUEUE

Mac OS X, FreeBSD, NetBSD, OpenBSD: kqueue.

ASIO_DISABLE_KQUEUE

ASIO_HAS_LOCAL_SOCKETS

UNIX domain sockets.

ASIO_DISABLE_LOCAL_SOCKETS

ASIO_HAS_MOVE

Support move construction and assignment on compilers known to allow it.

ASIO_DISABLE_MOVE

ASIO_HAS_MSG_NOSIGNAL

Kernel support for MSG_NOSIGNAL.

ASIO_HAS_NOEXCEPT

Support noexcept on compilers known to allow it.

ASIO_DISABLE_NOEXCEPT

ASIO_HAS_NULLPTR

Standard library support for the nullptr_t type.

ASIO_DISABLE_NULLPTR

ASIO_HAS_POSIX_STREAM_DESCRIPTOR

POSIX: stream-oriented file descriptors.

ASIO_DISABLE_POSIX_STREAM_DESCRIPTOR

ASIO_HAS_PTHREADS

POSIX threads.

ASIO_HAS_REF_QUALIFIED_FUNCTIONS

Support ref-qualified functions on compilers known to allow it.

ASIO_DISABLE_REF_QUALIFIED_FUNCTIONS

ASIO_HAS_RETURN_TYPE_DEDUCTION

Support return type deduction on compilers known to allow it.

ASIO_DISABLE_RETURN_TYPE_DEDUCTION

ASIO_HAS_SECURE_RTL

Microsoft Visual C++'s secure C runtime library.

ASIO_DISABLE_SECURE_RTL

ASIO_HAS_SERIAL_PORT

Serial ports.

ASIO_DISABLE_SERIAL_PORT

ASIO_HAS_SFINAE_VARIABLE_TEMPLATES

Support SFINAEd template variables on compilers known to allow it.

ASIO_DISABLE_SFINAE_VARIABLE_TEMPLATES

ASIO_HAS_SIGACTION

Can use sigaction() instead of signal().

ASIO_DISABLE_SIGACTION

ASIO_HAS_SIGNAL

Can use signal().

ASIO_DISABLE_SIGNAL

ASIO_HAS_SOURCE_LOCATION

Standard library has a source_location that we can use.

ASIO_DISABLE_SOURCE_LOCATION

ASIO_HAS_SSIZE_T

Support for POSIX ssize_t typedef.

ASIO_DISABLE_SSIZE_T

ASIO_HAS_STD_ADDRESSOF

Standard library support for addressof.

ASIO_DISABLE_STD_ADDRESSOF

ASIO_HAS_STD_ALLOCATOR_ARG

Standard library support for allocator_arg_t.

ASIO_DISABLE_STD_ALLOCATOR_ARG

ASIO_HAS_STD_ANY

Standard library support for std::any.

ASIO_DISABLE_STD_ANY

ASIO_HAS_STD_ARRAY

Standard library support for arrays.

ASIO_DISABLE_STD_ARRAY

ASIO_HAS_STD_ATOMIC

Standard library support for atomic operations.

ASIO_DISABLE_STD_ATOMIC

ASIO_HAS_STD_CALL_ONCE

Standard library support for the call_once function.

ASIO_DISABLE_STD_CALL_ONCE

ASIO_HAS_STD_CHRONO

Standard library support for chrono. Some standard libraries (such as the libstdc++ shipped with gcc 4.6) provide monotonic_clock as per early C++0x drafts, rather than the eventually standardised name of steady_clock.

ASIO_DISABLE_STD_CHRONO

ASIO_HAS_STD_CHRONO_MONOTONIC_CLOCK

Standard library support for chrono. Some standard libraries (such as the libstdc++ shipped with gcc 4.6) provide monotonic_clock as per early C++0x drafts, rather than the eventually standardised name of steady_clock.

ASIO_HAS_STD_COROUTINE

Standard library support for coroutines.

ASIO_DISABLE_STD_COROUTINE

ASIO_HAS_STD_EXCEPTION_PTR

Standard library support for std::exception_ptr and std::current_exception.

ASIO_DISABLE_STD_EXCEPTION_PTR

ASIO_HAS_STD_EXPERIMENTAL_SOURCE_LOCATION

Standard library support for std::experimental::source_location.

ASIO_DISABLE_STD_EXPERIMENTAL_SOURCE_LOCATION

ASIO_HAS_STD_EXPERIMENTAL_STRING_VIEW

Standard library support for std::experimental::string_view.

ASIO_DISABLE_STD_EXPERIMENTAL_STRING_VIEW

ASIO_HAS_STD_FUNCTION

Standard library support for the function class.

ASIO_DISABLE_STD_FUNCTION

ASIO_HAS_STD_FUTURE

Standard library support for futures.

ASIO_DISABLE_STD_FUTURE

ASIO_HAS_STD_HASH

Standard library support for std::hash.

ASIO_DISABLE_STD_HASH

ASIO_HAS_STD_INVOKE_RESULT

Standard library has invoke_result (which supersedes result_of).

ASIO_DISABLE_STD_INVOKE_RESULT

ASIO_HAS_STD_IOSTREAM_MOVE

Standard library support for iostream move construction and assignment.

ASIO_DISABLE_STD_IOSTREAM_MOVE

ASIO_HAS_STD_MUTEX_AND_CONDVAR

Standard library support for the mutex and condition variable classes.

ASIO_DISABLE_STD_MUTEX_AND_CONDVAR

ASIO_HAS_STD_NESTED_EXCEPTION

Standard library support for std::nested_exception.

ASIO_DISABLE_STD_NESTED_EXCEPTION

ASIO_HAS_STD_REFERENCE_WRAPPER

Standard library support for the reference_wrapper class.

ASIO_DISABLE_STD_REFERENCE_WRAPPER

ASIO_HAS_STD_SHARED_PTR

Standard library support for shared_ptr and weak_ptr.

ASIO_DISABLE_STD_SHARED_PTR

ASIO_HAS_STD_STRING_VIEW

Standard library support for std::string_view.

ASIO_DISABLE_STD_STRING_VIEW

ASIO_HAS_STD_SYSTEM_ERROR

Standard library support for system errors.

ASIO_DISABLE_STD_SYSTEM_ERROR

ASIO_HAS_STD_THREAD

Standard library support for the thread class.

ASIO_DISABLE_STD_THREAD

ASIO_HAS_STD_TYPE_TRAITS

Standard library support for type traits.

ASIO_DISABLE_STD_TYPE_TRAITS

ASIO_HAS_STRING_VIEW

Standard library has a string_view that we can use.

ASIO_DISABLE_STRING_VIEW

ASIO_HAS_THREADS

Threads.

ASIO_DISABLE_THREADS

ASIO_HAS_THREAD_KEYWORD_EXTENSION

Support for the __thread keyword extension.

ASIO_DISABLE_THREAD_KEYWORD_EXTENSION

ASIO_HAS_TIMERFD

Linux: epoll, eventfd and timerfd.

ASIO_HAS_UNISTD_H

On POSIX (and POSIX-like) platforms we need to include unistd.h in order to get access to the various platform feature macros, e.g. to be able to test for threads support.

ASIO_HAS_VARIABLE_TEMPLATES

Support template variables on compilers known to allow it.

ASIO_DISABLE_VARIABLE_TEMPLATES

ASIO_HAS_VARIADIC_TEMPLATES

Support variadic templates on compilers known to allow it.

ASIO_DISABLE_VARIADIC_TEMPLATES

ASIO_HAS_WINDOWS_OBJECT_HANDLE

Windows: object handles.

ASIO_DISABLE_WINDOWS_OBJECT_HANDLE

ASIO_HAS_WINDOWS_OVERLAPPED_PTR

Windows: OVERLAPPED wrapper.

ASIO_DISABLE_WINDOWS_OVERLAPPED_PTR

ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE

Windows: random access handles.

ASIO_DISABLE_WINDOWS_RANDOM_ACCESS_HANDLE

ASIO_HAS_WINDOWS_STREAM_HANDLE

Windows: stream handles.

ASIO_DISABLE_WINDOWS_STREAM_HANDLE

ASIO_HAS_WORKING_EXPRESSION_SFINAE

Enable workarounds for lack of working expression SFINAE.

ASIO_DISABLE_WORKING_EXPRESSION_SFINAE

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