doc/html/boost_asio/reference/asio_handler_invoke.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>asio_handler_invoke</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../reference.html" title="Reference">
   9 <link rel="prev" href="asio_handler_deallocate.html" title="asio_handler_deallocate">
  10 <link rel="next" href="asio_handler_invoke/overload1.html" title="asio_handler_invoke (1 of 2 overloads)">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="asio_handler_deallocate.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="asio_handler_invoke/overload1.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_asio.reference.asio_handler_invoke"></a><a class="link" href="asio_handler_invoke.html" title="asio_handler_invoke">asio_handler_invoke</a>
  28 </h3></div></div></div>
  29 <p>
  30         <a class="indexterm" name="idp89502624"></a>
  31 Default invoke function for handlers.
  32       </p>
  33 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
  34     <span class="keyword">typename</span> <span class="identifier">Function</span><span class="special">&gt;</span>
  35 <span class="keyword">void</span> <a class="link" href="asio_handler_invoke/overload1.html" title="asio_handler_invoke (1 of 2 overloads)">asio_handler_invoke</a><span class="special">(</span>
  36     <span class="identifier">Function</span> <span class="special">&amp;</span> <span class="identifier">function</span><span class="special">,</span>
  37     <span class="special">...</span> <span class="special">);</span>
  38   <span class="emphasis"><em>&#187; <a class="link" href="asio_handler_invoke/overload1.html" title="asio_handler_invoke (1 of 2 overloads)">more...</a></em></span>
  39
  40 <span class="keyword">template</span><span class="special">&lt;</span>
  41     <span class="keyword">typename</span> <span class="identifier">Function</span><span class="special">&gt;</span>
  42 <span class="keyword">void</span> <a class="link" href="asio_handler_invoke/overload2.html" title="asio_handler_invoke (2 of 2 overloads)">asio_handler_invoke</a><span class="special">(</span>
  43     <span class="keyword">const</span> <span class="identifier">Function</span> <span class="special">&amp;</span> <span class="identifier">function</span><span class="special">,</span>
  44     <span class="special">...</span> <span class="special">);</span>
  45   <span class="emphasis"><em>&#187; <a class="link" href="asio_handler_invoke/overload2.html" title="asio_handler_invoke (2 of 2 overloads)">more...</a></em></span>
  46 </pre>
  47 <p>
  48         Completion handlers for asynchronous operations are invoked by the <a class="link" href="io_service.html" title="io_service"><code class="computeroutput"><span class="identifier">io_service</span></code></a>
  49         associated with the corresponding object (e.g. a socket or deadline_timer).
  50         Certain guarantees are made on when the handler may be invoked, in particular
  51         that a handler can only be invoked from a thread that is currently calling
  52         <code class="computeroutput"><span class="identifier">run</span><span class="special">()</span></code>
  53         on the corresponding <a class="link" href="io_service.html" title="io_service"><code class="computeroutput"><span class="identifier">io_service</span></code></a> object. Handlers may
  54         subsequently be invoked through other objects (such as <a class="link" href="io_service__strand.html" title="io_service::strand"><code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">strand</span></code></a> objects) that provide additional
  55         guarantees.
  56       </p>
  57 <p>
  58         When asynchronous operations are composed from other asynchronous operations,
  59         all intermediate handlers should be invoked using the same method as the
  60         final handler. This is required to ensure that user-defined objects are not
  61         accessed in a way that may violate the guarantees. This hooking function
  62         ensures that the invoked method used for the final handler is accessible
  63         at each intermediate step.
  64       </p>
  65 <p>
  66         Implement asio_handler_invoke for your own handlers to specify a custom invocation
  67         strategy.
  68       </p>
  69 <p>
  70         This default implementation invokes the function object like so:
  71       </p>
  72 <pre class="programlisting"><span class="identifier">function</span><span class="special">();</span>
  73 </pre>
  74 <p>
  75         If necessary, the default implementation makes a copy of the function object
  76         so that the non-const operator() can be used.
  77       </p>
  78 <h5>
  79 <a name="boost_asio.reference.asio_handler_invoke.h0"></a>
  80         <span class="phrase"><a name="boost_asio.reference.asio_handler_invoke.example"></a></span><a class="link" href="asio_handler_invoke.html#boost_asio.reference.asio_handler_invoke.example">Example</a>
  81       </h5>
  82 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">my_handler</span><span class="special">;</span>
  83
  84 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Function</span><span class="special">&gt;</span>
  85 <span class="keyword">void</span> <span class="identifier">asio_handler_invoke</span><span class="special">(</span><span class="identifier">Function</span> <span class="identifier">function</span><span class="special">,</span> <span class="identifier">my_handler</span><span class="special">*</span> <span class="identifier">context</span><span class="special">)</span>
  86 <span class="special">{</span>
  87   <span class="identifier">context</span><span class="special">-&gt;</span><span class="identifier">strand_</span><span class="special">.</span><span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">function</span><span class="special">);</span>
  88 <span class="special">}</span>
  89 </pre>
  90 <h5>
  91 <a name="boost_asio.reference.asio_handler_invoke.h1"></a>
  92         <span class="phrase"><a name="boost_asio.reference.asio_handler_invoke.requirements"></a></span><a class="link" href="asio_handler_invoke.html#boost_asio.reference.asio_handler_invoke.requirements">Requirements</a>
  93       </h5>
  94 <p>
  95         <span class="emphasis"><em>Header: </em></span><code class="literal">boost/asio/handler_invoke_hook.hpp</code>
  96       </p>
  97 <p>
  98         <span class="emphasis"><em>Convenience header: </em></span><code class="literal">boost/asio.hpp</code>
  99       </p>
 100 </div>
 101 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 102 <td align="left"></td>
 103 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2017 Christopher M. Kohlhoff<p>
 104         Distributed under the Boost Software License, Version 1.0. (See accompanying
 105         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 106       </p>
 107 </div></td>
 108 </tr></table>
 109 <hr>
 110 <div class="spirit-nav">
 111 <a accesskey="p" href="asio_handler_deallocate.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="asio_handler_invoke/overload1.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 112 </div>
 113 </body>
 114 </html>