...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The following platform and compiler combinations are regularly tested:
The following platforms may also work:
__USE_W32_SOCKETS
must be defined.)
The following libraries must be available in order to link programs that use Boost.Asio:
boost::system::error_code
and boost::system::system_error
classes.
spawn()
to launch coroutines.
read_until()
or async_read_until()
overloads that take a boost::regex
parameter.
Furthermore, some of the examples also require the Boost.Thread, Boost.Date_Time or Boost.Serialization libraries.
Note | |
---|---|
With MSVC or Borland C++ you may want to add |
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.
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>
.
The macros listed in the table below may be used to control the interface, functionality, and behaviour of Boost.Asio.
Macro |
Description |
---|---|
|
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. |
|
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. |
|
Specifies that
The
This new name may break existing code that directly uses the old
Networking TS-style polymorphic wrapper, See Proposed Standard Executors for more information. |
|
Disables support for the
By default, dynamic buffer operations such as
When |
|
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
When using g++, this macro is defined automatically if standard library
debugging is enabled ( |
|
Explictly disables Boost.Asio's buffer debugging support. |
|
Enables Boost.Asio's Handler Tracking debugging facility. |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables I/O completion ports support on Windows, forcing
the use of a |
|
Explicitly disables Boost.Asio's threading support, independent of whether or not Boost as a whole supports threads. |
|
By default, Boost.Asio will automatically define |
|
By default, Boost.Asio will automatically define |
|
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. |
|
Enables use of the
The
|
|
Disables uses of the |
|
Determines the number of buckets in Boost.Asio's internal Some examples:
|
|
Changes |
|
Uses separately compiled source code for Boost.Asio's implementation. See above for further information. |
|
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. |
|
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. |
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 |
---|---|---|
|
Support alias templates on compilers known to allow it. |
|
|
Support for the alignof operator. |
|
|
Boost align library. |
|
|
Boost array library. |
|
|
Boost assert macro. |
|
|
Boost bind function. |
|
|
Boost support for chrono. |
|
|
Boost.Config library is available. |
|
|
Boost support for the DateTime library. |
|
|
Boost limits header. |
|
|
Boost regex library. |
|
|
Boost throw_exception function. |
|
|
Boost's BOOST_WORKAROUND macro. |
|
|
Some form of chrono library is available. |
|
|
Clang / libc++ detection. |
|
|
Support concepts on compilers known to allow them. |
|
|
Support SFINAE use of constant expressions on compilers known to allow it. |
|
|
Support constexpr on compilers known to allow it. |
|
|
Support the co_await keyword on compilers known to allow it. |
|
|
Standard library support for the cstdint header. |
|
|
Standard library support for the C++11 allocator additions. |
|
|
Support automatic type deduction on compilers known to support it. |
|
|
Support default function template arguments on compilers known to allow it. |
|
|
Solaris: /dev/poll. |
|
|
Support enum classes on compilers known to allow them. |
|
|
Linux: epoll, eventfd and timerfd. |
|
|
Linux: epoll, eventfd and timerfd. |
|
|
Files. |
|
|
Can use getaddrinfo() and getnameinfo(). |
|
|
Handler hooking. Disabled for ancient Borland C++ and gcc compilers. |
|
|
Windows: IO Completion Ports. |
|
|
Linux: io_uring is used instead of epoll. |
|
|
Mac OS X, FreeBSD, NetBSD, OpenBSD: kqueue. |
|
|
UNIX domain sockets. |
|
|
Support move construction and assignment on compilers known to allow it. |
|
|
Kernel support for MSG_NOSIGNAL. |
|
|
Support noexcept on compilers known to allow it. |
|
|
Support noexcept on function types on compilers known to allow it. |
|
|
Standard library support for the nullptr_t type. |
|
|
Pipes. |
|
|
POSIX: stream-oriented file descriptors. |
|
|
POSIX threads. |
|
|
Support ref-qualified functions on compilers known to allow it. |
|
|
Support return type deduction on compilers known to allow it. |
|
|
Microsoft Visual C++'s secure C runtime library. |
|
|
Serial ports. |
|
|
Support SFINAEd template variables on compilers known to allow it. |
|
|
Can use sigaction() instead of signal(). |
|
|
Can use signal(). |
|
|
Standard library has a source_location that we can use. |
|
|
Support for POSIX ssize_t typedef. |
|
|
Standard library support for addressof. |
|
|
Standard library support for aligned allocation. |
|
|
Standard library support for allocator_arg_t. |
|
|
Standard library support for std::any. |
|
|
Standard library support for arrays. |
|
|
Standard library support for atomic operations. |
|
|
Standard library support for the call_once function. |
|
|
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. |
|
|
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. |
|
|
Standard library support for coroutines. |
|
|
Standard library support for std::exception_ptr and std::current_exception. |
|
|
Standard library support for std::experimental::source_location. |
|
|
Standard library support for std::experimental::string_view. |
|
|
Standard library support for the function class. |
|
|
Standard library support for futures. |
|
|
Standard library support for std::hash. |
|
|
Standard library has invoke_result (which supersedes result_of). |
|
|
Standard library support for iostream move construction and assignment. |
|
|
Standard library support for the mutex and condition variable classes. |
|
|
Standard library support for std::nested_exception. |
|
|
Standard library support for the reference_wrapper class. |
|
|
Standard library support for shared_ptr and weak_ptr. |
|
|
Standard library support for std::string_view. |
|
|
Standard library support for system errors. |
|
|
Standard library support for the thread class. |
|
|
Standard library support for type traits. |
|
|
Standard library has a string_view that we can use. |
|
|
Threads. |
|
|
Support for the __thread keyword extension. |
|
|
Linux: epoll, eventfd and timerfd. |
|
|
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. |
|
|
Support template variables on compilers known to allow it. |
|
|
Support variadic templates on compilers known to allow it. |
|
|
Windows: object handles. |
|
|
Windows: OVERLAPPED wrapper. |
|
|
Windows: random access handles. |
|
|
Windows: stream handles. |
|
|
Enable workarounds for lack of working expression SFINAE. |
|
A mailing list specifically for Boost.Asio may be found on SourceForge.net. Newsgroup access is provided via Gmane.