1[/ 2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:allocation Custom Memory Allocation] 9 10Many asynchronous operations need to allocate an object to store state 11associated with the operation. For example, a Win32 implementation needs 12`OVERLAPPED`-derived objects to pass to Win32 API functions. 13 14Furthermore, programs typically contain easily identifiable chains of 15asynchronous operations. A half duplex protocol implementation (e.g. an HTTP 16server) would have a single chain of operations per client (receives followed 17by sends). A full duplex protocol implementation would have two chains 18executing in parallel. Programs should be able to leverage this knowledge to 19reuse memory for all asynchronous operations in a chain. 20 21Given a copy of a user-defined `Handler` object `h`, if the implementation 22needs to allocate memory associated with that handler it will obtain an 23allocator using the `get_associated_allocator` function. For example: 24 25 boost::asio::associated_allocator_t<Handler> a = boost::asio::get_associated_allocator(h); 26 27The associated allocator must satisfy the standard Allocator requirements. 28 29By default, handlers use the standard allocator (which is implemented in terms 30of `::operator new()` and `::operator delete()`). The allocator may be 31customised for a particular handler type by specifying a nested type 32`allocator_type` and member function `get_allocator()`: 33 34 class my_handler 35 { 36 public: 37 // Custom implementation of Allocator type requirements. 38 typedef my_allocator allocator_type; 39 40 // Return a custom allocator implementation. 41 allocator_type get_allocator() const noexcept 42 { 43 return my_allocator(); 44 } 45 46 void operator()() { ... } 47 }; 48 49In more complex cases, the `associated_allocator` template may be partially 50specialised directly: 51 52 namespace boost { namespace asio { 53 54 template <typename Allocator> 55 struct associated_allocator<my_handler, Allocator> 56 { 57 // Custom implementation of Allocator type requirements. 58 typedef my_allocator type; 59 60 // Return a custom allocator implementation. 61 static type get(const my_handler&, 62 const Allocator& a = Allocator()) noexcept 63 { 64 return my_allocator(); 65 } 66 }; 67 68 } } // namespace boost::asio 69 70The implementation guarantees that the deallocation will occur before the 71associated handler is invoked, which means the memory is ready to be reused for 72any new asynchronous operations started by the handler. 73 74The custom memory allocation functions may be called from any user-created 75thread that is calling a library function. The implementation guarantees that, 76for the asynchronous operations included the library, the implementation will 77not make concurrent calls to the memory allocation functions for that handler. 78The implementation will insert appropriate memory barriers to ensure correct 79memory visibility should allocation functions need to be called from different 80threads. 81 82[heading See Also] 83 84[link boost_asio.reference.associated_allocator associated_allocator], 85[link boost_asio.reference.get_associated_allocator get_associated_allocator], 86[link boost_asio.examples.cpp03_examples.allocation custom memory allocation example (C++03)], 87[link boost_asio.examples.cpp11_examples.allocation custom memory allocation example (C++11)]. 88 89[endsect] 90