libs/asio/doc/requirements/Handler.qbk

   1 [/
   2  / Copyright (c) 2003-2017 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:Handler Handlers]
   9
  10 A handler must meet the requirements of `CopyConstructible` types (C++ Std,
  11 20.1.3).
  12
  13 In the table below, `X` denotes a handler class, `h` denotes a value of `X`,
  14 `p` denotes a pointer to a block of allocated memory of type `void*`, `s`
  15 denotes the size for a block of allocated memory, and `f` denotes a function
  16 object taking no arguments.
  17
  18 [table Handler requirements
  19   [[expression] [return type] [assertion/note\npre/post-conditions]]
  20   [
  21     [``
  22       using boost::asio::asio_handler_allocate;
  23       asio_handler_allocate(s, &h);
  24     ``]
  25     [`void*`]
  26     [
  27       Returns a pointer to a block of memory of size `s`. The pointer must
  28       satisfy the same alignment requirements as a pointer returned by
  29       `::operator new()`. Throws `bad_alloc` on failure.\n\n The
  30       `asio_handler_allocate()` function is located using argument-dependent
  31       lookup. The function `boost::asio::asio_handler_allocate()` serves as a
  32       default if no user-supplied function is available.
  33     ]
  34   ]
  35   [
  36     [``
  37       using boost::asio::asio_handler_deallocate;
  38       asio_handler_deallocate(p, s, &h);
  39     ``]
  40     []
  41     [
  42       Frees a block of memory associated with a pointer `p`, of at least size
  43       `s`, that was previously allocated using `asio_handler_allocate()`.\n\n The
  44       `asio_handler_deallocate()` function is located using argument-dependent
  45       lookup. The function `boost::asio::asio_handler_deallocate()` serves as a
  46       default if no user-supplied function is available.
  47     ]
  48   ]
  49   [
  50     [``
  51       using boost::asio::asio_handler_invoke;
  52       asio_handler_invoke(f, &h);
  53     ``]
  54     []
  55     [
  56       Causes the function object `f` to be executed as if by calling `f()`.\n\n
  57       The `asio_handler_invoke()` function is located using argument-dependent
  58       lookup. The function `boost::asio::asio_handler_invoke()` serves as a
  59       default if no user-supplied function is available.
  60     ]
  61   ]
  62 ]
  63
  64 [endsect]