libs/asio/doc/requirements/TimerService.qbk

   1 [/
   2  / Copyright (c) 2003-2014 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:TimerService Timer service requirements]
   9
  10 A timer service must meet the requirements for an [link
  11 boost_asio.reference.IoObjectService I/O object service], as well as the
  12 additional requirements listed below.
  13
  14 In the table below, `X` denotes a timer service class for time type `Time` and
  15 traits type `TimeTraits`, `a` denotes a value of type `X`, `b` denotes a value
  16 of type `X::implementation_type`, `t` denotes a value of type `Time`, `d`
  17 denotes a value of type `TimeTraits::duration_type`, `e` denotes a value of
  18 type `error_code`, and `h` denotes a value meeting [link
  19 boost_asio.reference.WaitHandler `WaitHandler`] requirements.
  20
  21 [table TimerService requirements
  22   [[expression] [return type] [assertion/note\npre/post-condition]]
  23   [
  24     [`a.destroy(b);`]
  25     []
  26     [
  27       From [link boost_asio.reference.IoObjectService IoObjectService]
  28       requirements. Implicitly cancels asynchronous wait operations, as if by
  29       calling `a.cancel(b, e)`.
  30     ]
  31   ]
  32   [
  33     [``
  34       a.cancel(b, e);
  35     ``]
  36     [`size_t`]
  37     [
  38       Causes any outstanding asynchronous wait operations to complete as soon
  39       as possible. Handlers for cancelled operations shall be passed the error
  40       code `error::operation_aborted`. Sets `e` to indicate success or failure.
  41       Returns the number of operations that were cancelled.
  42     ]
  43   ]
  44   [
  45     [`a.expires_at(b);`]
  46     [`Time`]
  47     []
  48   ]
  49   [
  50     [``
  51       a.expires_at(b, t, e);
  52     ``]
  53     [`size_t`]
  54     [
  55       Implicitly cancels asynchronous wait operations, as if by calling
  56       `a.cancel(b, e)`. Returns the number of operations that were cancelled.\n
  57       post: `a.expires_at(b) == t`.
  58     ]
  59   ]
  60   [
  61     [`a.expires_from_now(b);`]
  62     [`TimeTraits::duration_type`]
  63     [
  64       Returns a value equivalent to `TimeTraits::subtract(a.expires_at(b),
  65       TimeTraits::now())`.
  66     ]
  67   ]
  68   [
  69     [``
  70       a.expires_from_now(b, d, e);
  71     ``]
  72     [`size_t`]
  73     [
  74       Equivalent to `a.expires_at(b, TimeTraits::add(TimeTraits::now(), d), e)`.
  75     ]
  76   ]
  77   [
  78     [``
  79       a.wait(b, e);
  80     ``]
  81     [`error_code`]
  82     [
  83       Sets `e` to indicate success or failure. Returns `e`.\n
  84       post: `!!e || !TimeTraits::lt(TimeTraits::now(), a.expires_at(b))`.
  85     ]
  86   ]
  87   [
  88     [``
  89       a.async_wait(b, h);
  90     ``]
  91     []
  92     [
  93       Initiates an asynchronous wait operation that is performed via the
  94       `io_service` object `a.get_io_service()` and behaves according to [link
  95       boost_asio.reference.asynchronous_operations asynchronous operation]
  96       requirements.\n
  97       \n
  98       The handler shall be posted for execution only if the condition
  99       `!!ec || !TimeTraits::lt(TimeTraits::now(), a.expires_at(b))`
 100       holds, where `ec` is the error code to be passed to the handler.
 101     ]
 102   ]
 103 ]
 104
 105 [endsect]