title: When to use `asio_handler_invoke`?
body: <p><strong>Question</strong></p>
  
  <p>When is it necessary to use <code>asio_handler_invoke</code> to achieve something that cannot be done by simply wrapping the handler?</p>
  
  <p>A canonical example that demonstrates a case where <code>asio_handler_invoke</code> is required would be ideal.</p>
  
  <p><strong>Background</strong></p>
  
  <p>The boost asio docs contain an example of <em>how</em> to use <code>asio_handler_invoke</code> <a href="http://www.boost.org/doc/libs/1_48_0/doc/html/boost_asio/example/invocation/prioritised_handlers.cpp" rel="noreferrer">here</a>, but I don't think it is a compelling example of <em>why</em> you would use the invocation handler. In that example it appears you could make changes like the following (and remove the <code>asio_handler_invoke</code>) and achieve an identical result: </p>
  
  <pre><code>template &lt;typename Arg1&gt;
  void operator()(Arg1 arg1)
  {
    queue_.add(priority_, std::bind(handler_, arg1));
  }
  </code></pre>
  
  <p>Similarly, in my answer relating to <a href="https://stackoverflow.com/a/32856299/424153">handler tracking</a> it similarly appears unnecessary to use <code>asio_handler_invoke</code>, despite <a href="https://stackoverflow.com/a/31456292/424153">Tanner Sansbury's</a> answer suggesting using the invocation hook as a solution.</p>
  
  <p><a href="http://boost.2283326.n4.nabble.com/boost-asio-reason-for-asio-handler-invoke-td2574233.html" rel="noreferrer">This thread</a> on the boost user group provides some more information - but I don't understand the significance.</p>
  
  <p>From what I have seen, it appears <code>asio_handler_invoke</code> is always called like <code>asio_handler_invoke(h, &amp;h)</code>, which doesn't appear to make much sense. In what cases would the arguments not be (essentially) copies of the same object?</p>
  
  <p>A final point - I only ever call <code>io_service::run()</code> from a single thread, so it may be I'm missing something obvious that comes from experience in a multi-threaded loop.</p>