title: When is it a good idea to use std::promise over the other std::thread mechanisms?
body: <p>I am trying to establish some heuristics to help me decide the appropriate <code>std::thread</code> class to use.</p>
  
  <p>As I understand it, from highest level (simplest to use, but least flexible) to lowest level, we have:</p>
  
  <ol>
  <li>std::async with/std::future (std::shared_future) (when you want to execute on a one-time throw-away producer-thread async)</li>
  <li>std::packaged_task (when you want to assign a producer, but defer the call to the thread)</li>
  <li>std::promise (???)</li>
  </ol>
  
  <p>I think I have a decent grasp of <strong>when to use</strong> the first two, but am still unclear about <code>std::promise</code>.</p>
  
  <p><code>std::future</code> in conjunction with a <code>std::async</code> call, effectively transforms a producing callback/functor/lambda to an asynchronous call (which returns immediately, by definition).  A singular consumer can call <code>std::future::get()</code>, a blocking call, to get its results back.</p>
  
  <p><code>std::shared_future</code> is just a version which allows for multiple consumers.</p>
  
  <p>If you want to bind a <code>std::future</code> value with a producer callback, <strong>but want to defer the actual invocation to a later time (when you associate the task to a spawning thread)</strong>, <code>std::packaged_task</code> is the right choice.  But now, since the corresponding <code>std::future</code> to the <code>std::package_task</code> could, in the general case, be accessed by multiple-threads, we may have to take care to use a <code>std::mutex</code>.  Note that with <code>std::async</code>, in the first case, we don't have to worry about locking.</p>
  
  <p>Having read <a href="https://stackoverflow.com/a/12335206/975129">some interesting links on promise</a>, I think I understand its mechanisms and how to set them up, but my question is, <strong>when would you choose to use a promise over the other three?</strong>  </p>
  
  <p><em>I'm looking more for an application-level answer, like a rule-of-thumb (fill the ??? in 3. above), as opposed to the answer in the link (eg use std::promise to implement some library mechanism), so I can more easily explain how to choose the proper class to a beginning user of <code>std::thread</code>.</em></p>
  
  <p>In other words, it would be nice to have an useful example of what I can do with a <code>std::promise</code> that <strong>cannot</strong> be done with the other mechanisms.</p>
  
  <p><strong>ANSWER</strong></p>
  
  <p>A <code>std::future</code> is a strange beast: in general, you cannot modify its value directly.</p>
  
  <p>Three producers which can modify its value are:</p>
  
  <ol>
  <li><code>std::async</code> through an asynchronous callback, which will return a <code>std::future</code> instance.</li>
  <li><code>std::packaged_task</code>, which, when passed to a thread, will invoke its callback thereby updating the <code>std::future</code> instance associated with that <code>std::packaged_task</code>.  This mechanism allows for early binding of a producer, but a later invocation.</li>
  <li><code>std::promise</code>, which allows one to modify its associated <code>std::future</code> through its <code>set_value()</code> call.  With this direct control over mutating a <code>std::future</code>, we must ensure that that the design is thread-safe if there are multiple producers (use <code>std::mutex</code> as necessitated).</li>
  </ol>
  
  <p>I think <a href="https://stackoverflow.com/a/14283834/975129">SethCarnegie's answer</a>: </p>
  
  <blockquote>
    <p>An easy way to think of it is that you can either set a future by
    returning a value or by using a promise. future has no set method;
    that functionality is provided by promise.</p>
  </blockquote>
  
  <p>helps clarify when to use a promise.  But we have to keep in mind that a <code>std::mutex</code> may be necessary, as the promise might be accessible from different threads, depending on usage.</p>
  
  <p>Also, <a href="https://stackoverflow.com/a/11004368/975129">David's Rodriguez's answer</a> is also excellent:</p>
  
  <blockquote>
    <p>The consumer end of the communication channel would use a std::future
    to consume the datum from the shared state, while the producer thread
    would use a std::promise to write to the shared state.</p>
  </blockquote>
  
  <p>But as an alternative, why not simply just use a <code>std::mutex</code> on a stl container of results, and one thread or a threadpool of producers to act on the container?  What does using <code>std::promise</code>, instead, buy me, besides some extra readability vs a stl container of results?  </p>
  
  <p>The control appears to be better in the <code>std::promise</code> version:</p>
  
  <ol>
  <li>wait() will block on a given future until the result is produced</li>
  <li>if there is only one producer thread, a mutex is not necessary</li>
  </ol>
  
  <p><em>The following google-test passes both helgrind and drd, confirming that with a single producer, and with the use of wait(), a mutex is not needed.</em></p>
  
  <p><strong>TEST</strong></p>
  
  <pre><code>static unsigned MapFunc( std::string const&amp; str ) 
  { 
      if ( str=="one" ) return 1u; 
      if ( str=="two" ) return 2u; 
      return 0u;
  }
  
  TEST( Test_future, Try_promise )
  {
      typedef std::map&lt;std::string,std::promise&lt;unsigned&gt;&gt;  MAP; 
      MAP          my_map;
  
      std::future&lt;unsigned&gt; f1 = my_map["one"].get_future();
      std::future&lt;unsigned&gt; f2 = my_map["two"].get_future();
  
      std::thread{ 
          [ ]( MAP&amp; m )
          { 
              m["one"].set_value( MapFunc( "one" ));
              m["two"].set_value( MapFunc( "two" ));
          }, 
        std::ref( my_map ) 
      }.detach();
  
      f1.wait();
      f2.wait();
  
      EXPECT_EQ( 1u, f1.get() );
      EXPECT_EQ( 2u, f2.get() );
  }
  </code></pre>