title: Example of how to use boost upgradeable mutexes
body: <p>I have a multithreaded server application that needs mutex locks over some shared memory.</p>
  
  <p>The shared memory are basically sTL maps etc.</p>
  
  <p>Much of the time I'm just reading from the map.
  But, I also need to occasionally add to it.</p>
  
  <p>e.g.
      typedef std::map MessageMap;
      MessageMap msgmap;
      boost:shared_mutex access_;</p>
  
  <pre><code>void ProcessMessage(Message* message)
  {
    //  Access message... read some stuff from it  message-&gt;...
  
    UUID id = message-&gt;GetSessionID();
  
    // Need to obtain a lock here. (shared lock? multiple readers)
    // How is that done?
    boost::interprocess::scoped_lock(access_);
  
    // Do some readonly stuff with msgmap
    MessageMap::iterator it = msgmap.find();
    // 
  
    // Do some stuff...
  
    // Ok, after all that I decide that I need to add an entry to the map.
    // how do I upgrade the shared lock that I currently have?
    boost::interprocess::upgradable_lock
  
  
    // And then later forcibly release the upgrade lock or upgrade and shared lock if I'm not looking
    // at the map anymore.
    // I like the idea of using scoped lock in case an exception is thrown, I am sure that
    // all locks are released.
  }
  </code></pre>
  
  <p>EDIT:
  I might be confusing the different lock types.</p>
  
  <p>Whats the difference between shared/upgrade and exclusive.
  i.e. I don't understand the explanation.
  It sounds like if you just want to allow lots of readers, a shared access is all you want to obtain.  And to write to your shared memory you just need upgrade access.  Or do you need exclusive?  The explanation in boost is anything but clear.</p>
  
  <p>Is upgrade access obtained because you might write.  But shared means you definately won't write is that what it means?</p>
  
  <p>EDIT: Let me explain what I'm wanting to do with a little more clarity.  I'm not yet happy with the answers.</p>
  
  <p>Here is the example all over again but with an example of some code that I'm using as well.
  Just an illustration, not the actual code.</p>
  
  <pre><code>typedef boost::shared_mutex Mutex;
  typedef boost::shared_lock&lt;Mutex&gt; ReadLock;
  typedef boost::unique_lock&lt;Mutex&gt; WriteLock;
  Mutex mutex;
  typedef map&lt;int, int&gt; MapType;    // Your map type may vary, just change the typedef
  MapType mymap;
  
  void threadoolthread() // There could be 10 of these.
  {   
      // Add elements to map here
      int k = 4;   // assume we're searching for keys equal to 4
      int v = 0;   // assume we want the value 0 associated with the key of 4
  
      ReadLock read(mutex); // Is this correct?
      MapType::iterator lb = mymap.lower_bound(k);
      if(lb != mymap.end() &amp;&amp; !(mymap.key_comp()(k, lb-&gt;first)))
      {
          // key already exists
      }
      else
      {
          // Acquire an upgrade lock yes?  How do I upgrade the shared lock that I already        have?
          // I think then sounds like I need to upgrade the upgrade lock to exclusive is that correct as well?
  
          // Assuming I've got the exclusive lock, no other thread in the thread pool will be able to insert.
          // the key does not exist in the map
          // add it to the map
          {
            WriteLock write(mutex, boost::adopt_lock_t());  // Is this also correct?
            mymap.insert(lb, MapType::value_type(k, v));    // Use lb as a hint to insert,
                                                          // so it can avoid another lookup
          }
          // I'm now free to do other things here yes?  what kind of lock do I have here, if any?  does the readlock still exist?
      }
  </code></pre>