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

Click here to view the latest version of this page.
PrevUpHomeNext

Using Boost.Asio

Supported Platforms

The following platforms and compilers have been 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:

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

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

Macros

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

Macro

Description

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++, 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_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 Mac OS X 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_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_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_SOCKET_STREAMBUF_MAX_ARITY

Determines the maximum number of arguments that may be passed to the basic_socket_streambuf class template's connect member function. Defaults to 5.

BOOST_ASIO_SOCKET_IOSTREAM_MAX_ARITY

Determines the maximum number of arguments that may be passed to the basic_socket_iostream class template's constructor and connect member function. Defaults to 5.

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.

Mailing List

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


PrevUpHomeNext