asio C++ library Home | Download | Documentation | Source | Mailing List | Blog

Asio and Boost.Asio

Asio comes in two variants: (non-Boost) Asio and Boost.Asio. The differences between the two are outlined below.

What are the differences in the source code?

— Asio is in a namespace called asio::, whereas Boost.Asio puts everything under boost::asio::.

— The main Asio header file is called asio.hpp. The corresponding header in Boost.Asio is boost/asio.hpp. All other headers are similarly changed.

— Any macros used by or defined in Asio are prefixed with ASIO_. In Boost.Asio they are prefixed with BOOST_ASIO_.

— Asio includes a class for launching threads: asio::thread. Boost.Asio does not include this class, to avoid overlap with the Boost.Thread library

— Boost.Asio always uses the Boost.System library to provide support for error codes (boost::system::error_code and boost::system::system_error). For C++11 and later, Asio uses the std::error_code and std::system_error classes shipped with the compiler. Asio aliases these names in its own namespace (as asio::error_code and asio::system_error), and when targeting C++03, provides a minimal implementation of these classes. If targeting C++03 is important, it is worth noting that the Boost.System version of these classes currently supports better extensibility for user-defined error codes than this minimal implementation.

— Asio is header-file-only and for most uses does not require linking against any Boost library. When using C++11 or later with recent versions of gcc, clang or MSVC, Asio can be used without any dependency on Boost. Boost.Asio always requires that you use the Boost.System library, and also against Boost.Thread if you want to launch threads using boost::thread. This may require linking against these libraries, although it is worth noting that recent versions of Boost allow you to use Boost.System in header-only mode.

Where do I get a release package?

Asio is available for download from SourceForge, in a package named asio-X.Y.Z.tar.gz (or .tar.bz2 or .zip).

Boost.Asio is included in the Boost distributions for version 1.35 and later. It is also available as a separate package on SourceForge, named boost_asio_X_Y_Z.tar.gz. The latter is intended to be copied over the top of an existing Boost source code distribution.

Where are the source code repositories?

Asio is hosted on GitHub.

Boost.Asio is checked into Boost’s GitHub repository.

How are both versions maintained?

All development is done in the Asio repository on GitHub. The source is periodically converted into Boost format using a script called, and the changes merged into the Boost GitHub repository.

Will Asio be discontinued now that Boost.Asio is included with Boost?

No. There are projects using Asio and they will continue to be supported.

Should I use Asio or Boost.Asio?

It depends. Here are some things to consider:

— If you prefer the convenience of header-file-only libraries then using Asio over Boost.Asio is suggested.

— If you must use a version of Boost older than 1.35 then Boost.Asio is not included. You can use Boost.Asio by copying it over the top of your Boost distribution (see above), but not everyone is comfortable doing this. In that case, using Asio over Boost.Asio is suggested.

— New versions of both the Asio and Boost.Asio packages will be created on a faster release cycle than that followed by Boost. If you want to use the latest features you can still use Boost.Asio as long as you are happy to copy it over the top of your Boost distribution. If you don’t want to do this, use Asio rather than Boost.Asio.

Can Asio and Boost.Asio coexist in the same program?

Yes. Since they use different namespaces there should be no conflicts, although obviously the types themselves are not interchangeable. (In case you’re wondering why you might want to do this, consider a situation where a program is using third party libraries that are also using Asio internally.)

Home | Download | Documentation | Source | Mailing List | Blog