Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit b14f8ca719.
PrevUpHomeNext

Using, Building, and Configuring Boost.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 Boost.Asio:

Furthermore, some of the examples also require the Boost.Thread, 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.

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:

  b2 --with-system --with-thread --with-date_time --with-regex --with-serialization stage

This assumes that you have already built b2. Consult the Boost.Build documentation for more details.

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

Debugger support

Some debugger extensions for use with Asio may be found at https://github.com/chriskohlhoff/asio-debugger-extensions.

Macros

The macros listed in the table below may be used to control the interface, functionality, and behaviour of Boost.Asio.

Macro

Description

BOOST_ASIO_NO_DEPRECATED

Disables Boost.Asio's deprecated interfaces and functionality.

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

BOOST_ASIO_NO_TS_EXECUTORS

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

By default, Boost.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.

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

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

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++ 11.0 or later, 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_ENABLE_HANDLER_TRACKING

Enables Boost.Asio's Handler Tracking debugging facility.

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

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

BOOST_ASIO_SEPARATE_COMPILATION

Uses separately compiled source code for Boost.Asio's implementation.

See above for further information.

BOOST_ASIO_DYN_LINK

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

See above for further information.

BOOST_ASIO_DISABLE_VISIBILITY

Disables all symbol visibility pragmas.

Note: If symbols are hidden, extra care must be taken to ensure that Boost.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 BOOST_ASIO_HAS_, and are listed in the table below.

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

In general, BOOST_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 BOOST_ASIO_HAS_ macro is not automatically defined, testing may have shown that a claimed feature isn't sufficiently conformant to be compatible with Boost.Asio's needs.

Macro

Description

Macro to disable feature

BOOST_ASIO_HAS_ALIAS_TEMPLATES

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_ALIGNOF

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_BOOST_ALIGN

Boost align library.

BOOST_ASIO_DISABLE_BOOST_ALIGN

BOOST_ASIO_HAS_BOOST_ARRAY

Boost array library.

BOOST_ASIO_DISABLE_BOOST_ARRAY

BOOST_ASIO_HAS_BOOST_ASSERT

Boost assert macro.

BOOST_ASIO_DISABLE_BOOST_ASSERT

BOOST_ASIO_HAS_BOOST_BIND

Boost bind function.

BOOST_ASIO_DISABLE_BOOST_BIND

BOOST_ASIO_HAS_BOOST_CHRONO

Boost support for chrono.

BOOST_ASIO_DISABLE_BOOST_CHRONO

BOOST_ASIO_HAS_BOOST_CONFIG

Boost.Config library is available.

BOOST_ASIO_HAS_BOOST_CONTEXT_FIBER

Boost support for the Context library's fibers.

BOOST_ASIO_DISABLE_BOOST_CONTEXT_FIBER

BOOST_ASIO_HAS_BOOST_COROUTINE

Boost support for the Coroutine library.

BOOST_ASIO_DISABLE_BOOST_COROUTINE

BOOST_ASIO_HAS_BOOST_DATE_TIME

Boost support for the DateTime library.

BOOST_ASIO_DISABLE_BOOST_DATE_TIME

BOOST_ASIO_HAS_BOOST_LIMITS

Boost limits header.

BOOST_ASIO_DISABLE_BOOST_LIMITS

BOOST_ASIO_HAS_BOOST_REGEX

Boost regex library.

BOOST_ASIO_DISABLE_BOOST_REGEX

BOOST_ASIO_HAS_BOOST_SOURCE_LOCATION

Boost support for source_location and system errors.

BOOST_ASIO_DISABLE_BOOST_SOURCE_LOCATION

BOOST_ASIO_HAS_BOOST_THROW_EXCEPTION

Boost throw_exception function.

BOOST_ASIO_DISABLE_BOOST_THROW_EXCEPTION

BOOST_ASIO_HAS_BOOST_WORKAROUND

Boost's BOOST_WORKAROUND macro.

BOOST_ASIO_DISABLE_BOOST_WORKAROUND

BOOST_ASIO_HAS_CHRONO

Some form of chrono library is available.

BOOST_ASIO_HAS_CLANG_LIBCXX

Clang / libc++ detection.

BOOST_ASIO_HAS_CONCEPTS

Support concepts on compilers known to allow them.

BOOST_ASIO_DISABLE_CONCEPTS

BOOST_ASIO_HAS_CONSTANT_EXPRESSION_SFINAE

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

BOOST_ASIO_DISABLE_CONSTANT_EXPRESSION_SFINAE

BOOST_ASIO_HAS_CONSTEXPR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_CO_AWAIT

Support the co_await keyword on compilers known to allow it.

BOOST_ASIO_DISABLE_CO_AWAIT

BOOST_ASIO_HAS_CSTDINT

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_CXX11_ALLOCATORS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_DECLTYPE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_DEFAULT_FUNCTION_TEMPLATE_ARGUMENTS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_DEV_POLL

Solaris: /dev/poll.

BOOST_ASIO_DISABLE_DEV_POLL

BOOST_ASIO_HAS_ENUM_CLASS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_EPOLL

Linux: epoll, eventfd, timerfd and io_uring.

BOOST_ASIO_DISABLE_EPOLL

BOOST_ASIO_HAS_EVENTFD

Linux: epoll, eventfd, timerfd and io_uring.

BOOST_ASIO_DISABLE_EVENTFD

BOOST_ASIO_HAS_FILE

Files.

BOOST_ASIO_DISABLE_FILE

BOOST_ASIO_HAS_GETADDRINFO

Can use getaddrinfo() and getnameinfo().

BOOST_ASIO_DISABLE_GETADDRINFO

BOOST_ASIO_HAS_HANDLER_HOOKS

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

BOOST_ASIO_DISABLE_HANDLER_HOOKS

BOOST_ASIO_HAS_IOCP

Windows: IO Completion Ports.

BOOST_ASIO_DISABLE_IOCP

BOOST_ASIO_HAS_IO_URING_AS_DEFAULT

Linux: io_uring is used instead of epoll.

BOOST_ASIO_HAS_KQUEUE

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

BOOST_ASIO_DISABLE_KQUEUE

BOOST_ASIO_HAS_LOCAL_SOCKETS

UNIX domain sockets.

BOOST_ASIO_DISABLE_LOCAL_SOCKETS

BOOST_ASIO_HAS_MOVE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_MSG_NOSIGNAL

Kernel support for MSG_NOSIGNAL.

BOOST_ASIO_HAS_NOEXCEPT

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_NOEXCEPT_FUNCTION_TYPE

Support noexcept on function types on compilers known to allow it.

BOOST_ASIO_DISABLE_NOEXCEPT_FUNCTION_TYPE

BOOST_ASIO_HAS_NULLPTR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_PIPE

Pipes.

BOOST_ASIO_DISABLE_PIPE

BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR

POSIX: stream-oriented file descriptors.

BOOST_ASIO_DISABLE_POSIX_STREAM_DESCRIPTOR

BOOST_ASIO_HAS_PTHREADS

POSIX threads.

BOOST_ASIO_HAS_REF_QUALIFIED_FUNCTIONS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_RETURN_TYPE_DEDUCTION

Support return type deduction on compilers known to allow it.

BOOST_ASIO_DISABLE_RETURN_TYPE_DEDUCTION

BOOST_ASIO_HAS_SECURE_RTL

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

BOOST_ASIO_DISABLE_SECURE_RTL

BOOST_ASIO_HAS_SERIAL_PORT

Serial ports.

BOOST_ASIO_DISABLE_SERIAL_PORT

BOOST_ASIO_HAS_SFINAE_VARIABLE_TEMPLATES

Support SFINAEd template variables on compilers known to allow it.

BOOST_ASIO_DISABLE_SFINAE_VARIABLE_TEMPLATES

BOOST_ASIO_HAS_SIGACTION

Can use sigaction() instead of signal().

BOOST_ASIO_DISABLE_SIGACTION

BOOST_ASIO_HAS_SIGNAL

Can use signal().

BOOST_ASIO_DISABLE_SIGNAL

BOOST_ASIO_HAS_SNPRINTF

Standard library support for snprintf.

BOOST_ASIO_DISABLE_SNPRINTF

BOOST_ASIO_HAS_SOURCE_LOCATION

Standard library has a source_location that we can use.

BOOST_ASIO_DISABLE_SOURCE_LOCATION

BOOST_ASIO_HAS_SSIZE_T

Support for POSIX ssize_t typedef.

BOOST_ASIO_DISABLE_SSIZE_T

BOOST_ASIO_HAS_STD_ADDRESSOF

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_ALIGN

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_ALIGNED_ALLOC

Standard library support for aligned allocation.

BOOST_ASIO_DISABLE_STD_ALIGNED_ALLOC

BOOST_ASIO_HAS_STD_ALLOCATOR_ARG

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_ANY

Standard library support for std::any.

BOOST_ASIO_DISABLE_STD_ANY

BOOST_ASIO_HAS_STD_ARRAY

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_ATOMIC

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_CALL_ONCE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_CHRONO

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_CONCEPTS

Support concepts on compilers known to allow them.

BOOST_ASIO_DISABLE_STD_CONCEPTS

BOOST_ASIO_HAS_STD_COROUTINE

Standard library support for coroutines.

BOOST_ASIO_DISABLE_STD_COROUTINE

BOOST_ASIO_HAS_STD_EXCEPTION_PTR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_EXPERIMENTAL_SOURCE_LOCATION

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

BOOST_ASIO_DISABLE_STD_EXPERIMENTAL_SOURCE_LOCATION

BOOST_ASIO_HAS_STD_EXPERIMENTAL_STRING_VIEW

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

BOOST_ASIO_DISABLE_STD_EXPERIMENTAL_STRING_VIEW

BOOST_ASIO_HAS_STD_FUNCTION

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_FUTURE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_HASH

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_INDEX_SEQUENCE

Standard library support for std::index_sequence.

BOOST_ASIO_DISABLE_STD_INDEX_SEQUENCE

BOOST_ASIO_HAS_STD_INVOKE_RESULT

Standard library has invoke_result (which supersedes result_of).

BOOST_ASIO_DISABLE_STD_INVOKE_RESULT

BOOST_ASIO_HAS_STD_IOSTREAM_MOVE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_MUTEX_AND_CONDVAR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_NESTED_EXCEPTION

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_REFERENCE_WRAPPER

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_SHARED_PTR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_STRING_VIEW

Standard library support for std::string_view.

BOOST_ASIO_DISABLE_STD_STRING_VIEW

BOOST_ASIO_HAS_STD_SYSTEM_ERROR

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_THREAD

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_TO_ADDRESS

Standard library support for std::to_address.

BOOST_ASIO_DISABLE_STD_TO_ADDRESS

BOOST_ASIO_HAS_STD_TUPLE

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_TYPE_TRAITS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_STD_VARIANT

Standard library support for std::variant.

BOOST_ASIO_DISABLE_STD_VARIANT

BOOST_ASIO_HAS_STRING_VIEW

Standard library has a string_view that we can use.

BOOST_ASIO_DISABLE_STRING_VIEW

BOOST_ASIO_HAS_THREADS

Threads.

BOOST_ASIO_DISABLE_THREADS

BOOST_ASIO_HAS_THREAD_KEYWORD_EXTENSION

Support for the __thread keyword extension, or equivalent.

BOOST_ASIO_DISABLE_THREAD_KEYWORD_EXTENSION

BOOST_ASIO_HAS_TIMERFD

Linux: epoll, eventfd, timerfd and io_uring.

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

BOOST_ASIO_HAS_USER_DEFINED_LITERALS

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_VARIABLE_TEMPLATES

Support template variables on compilers known to allow it.

BOOST_ASIO_DISABLE_VARIABLE_TEMPLATES

BOOST_ASIO_HAS_VARIADIC_LAMBDA_CAPTURES

Support for capturing parameter packs in lambdas.

BOOST_ASIO_DISABLE_VARIADIC_LAMBDA_CAPTURES

BOOST_ASIO_HAS_VARIADIC_TEMPLATES

Always enabled. Retained for backwards compatibility in user code.

BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE

Windows: object handles.

BOOST_ASIO_DISABLE_WINDOWS_OBJECT_HANDLE

BOOST_ASIO_HAS_WINDOWS_OVERLAPPED_PTR

Windows: OVERLAPPED wrapper.

BOOST_ASIO_DISABLE_WINDOWS_OVERLAPPED_PTR

BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE

Windows: random access handles.

BOOST_ASIO_DISABLE_WINDOWS_RANDOM_ACCESS_HANDLE

BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE

Windows: stream handles.

BOOST_ASIO_DISABLE_WINDOWS_STREAM_HANDLE

BOOST_ASIO_HAS_WORKING_EXPRESSION_SFINAE

Enable workarounds for lack of working expression SFINAE.

BOOST_ASIO_DISABLE_WORKING_EXPRESSION_SFINAE

Mailing List

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


PrevUpHomeNext