boost/asio/handler_alloc_hook.hpp

   1 //
   2 // handler_alloc_hook.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2014 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10
  11 #ifndef BOOST_ASIO_HANDLER_ALLOC_HOOK_HPP
  12 #define BOOST_ASIO_HANDLER_ALLOC_HOOK_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19 #include <cstddef>
  20
  21 #include <boost/asio/detail/push_options.hpp>
  22
  23 namespace boost {
  24 namespace asio {
  25
  26 /// Default allocation function for handlers.
  27 /**
  28  * Asynchronous operations may need to allocate temporary objects. Since
  29  * asynchronous operations have a handler function object, these temporary
  30  * objects can be said to be associated with the handler.
  31  *
  32  * Implement asio_handler_allocate and asio_handler_deallocate for your own
  33  * handlers to provide custom allocation for these temporary objects.
  34  *
  35  * The default implementation of these allocation hooks uses <tt>::operator
  36  * new</tt> and <tt>::operator delete</tt>.
  37  *
  38  * @note All temporary objects associated with a handler will be deallocated
  39  * before the upcall to the handler is performed. This allows the same memory to
  40  * be reused for a subsequent asynchronous operation initiated by the handler.
  41  *
  42  * @par Example
  43  * @code
  44  * class my_handler;
  45  *
  46  * void* asio_handler_allocate(std::size_t size, my_handler* context)
  47  * {
  48  *   return ::operator new(size);
  49  * }
  50  *
  51  * void asio_handler_deallocate(void* pointer, std::size_t size,
  52  *     my_handler* context)
  53  * {
  54  *   ::operator delete(pointer);
  55  * }
  56  * @endcode
  57  */
  58 BOOST_ASIO_DECL void* asio_handler_allocate(
  59     std::size_t size, ...);
  60
  61 /// Default deallocation function for handlers.
  62 /**
  63  * Implement asio_handler_allocate and asio_handler_deallocate for your own
  64  * handlers to provide custom allocation for the associated temporary objects.
  65  *
  66  * The default implementation of these allocation hooks uses <tt>::operator
  67  * new</tt> and <tt>::operator delete</tt>.
  68  *
  69  * @sa asio_handler_allocate.
  70  */
  71 BOOST_ASIO_DECL void asio_handler_deallocate(
  72     void* pointer, std::size_t size, ...);
  73
  74 } // namespace asio
  75 } // namespace boost
  76
  77 #include <boost/asio/detail/pop_options.hpp>
  78
  79 #if defined(BOOST_ASIO_HEADER_ONLY)
  80 # include <boost/asio/impl/handler_alloc_hook.ipp>
  81 #endif // defined(BOOST_ASIO_HEADER_ONLY)
  82
  83 #endif // BOOST_ASIO_HANDLER_ALLOC_HOOK_HPP