[/
 / Copyright (c) 2003-2010 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:allocation Custom Memory Allocation]

Many asynchronous operations need to allocate an object to store state
associated with the operation. For example, a Win32 implementation needs
`OVERLAPPED`-derived objects to pass to Win32 API functions.

Furthermore, programs typically contain easily identifiable chains of
asynchronous operations. A half duplex protocol implementation (e.g. an HTTP
server) would have a single chain of operations per client (receives followed
by sends). A full duplex protocol implementation would have two chains
executing in parallel. Programs should be able to leverage this knowledge to
reuse memory for all asynchronous operations in a chain.

Given a copy of a user-defined `Handler` object `h`, if the implementation
needs to allocate memory associated with that handler it will execute the code:

  void* pointer = asio_handler_allocate(size, &h);

Similarly, to deallocate the memory it will execute:

  asio_handler_deallocate(pointer, size, &h);

These functions are located using argument-dependent lookup. The implementation
provides default implementations of the above functions in the `asio` namespace:

  void* asio_handler_allocate(size_t, ...);
  void asio_handler_deallocate(void*, size_t, ...);

which are implemented in terms of `::operator new()` and `::operator delete()`
respectively.

The implementation guarantees that the deallocation will occur before the
associated handler is invoked, which means the memory is ready to be reused for
any new asynchronous operations started by the handler.

The custom memory allocation functions may be called from any user-created
thread that is calling a library function. The implementation guarantees that,
for the asynchronous operations included the library, the implementation will
not make concurrent calls to the memory allocation functions for that handler.
The implementation will insert appropriate memory barriers to ensure correct
memory visibility should allocation functions need to be called from different
threads.

Custom memory allocation support is currently implemented for all asynchronous
operations with the following exceptions:

* Asynchronous SSL operations.

[heading See Also]

[link boost_asio.reference.asio_handler_allocate asio_handler_allocate],
[link boost_asio.reference.asio_handler_deallocate asio_handler_deallocate],
[link boost_asio.examples.allocation custom memory allocation example].

[endsect]