Click here to Skip to main content
15,917,631 members
Articles / General Programming / Threads

Mutable/Promotable Recursive Mutex

Rate me:
Please Sign up or sign in to vote.
4.00/5 (2 votes)
24 Dec 2012CPOL5 min read 20.5K   163   10   3
Extension of boost::upgrade_mutex

Headers fix.

"Knowledge is limited. Imagination encircles the world." A.E.


This is a library.

I designed a new class of mutex: mutable_recursive_mutex.

It is an extension of: <a title="boost documentation" href="" target="_blank">boost::upgrade_mutex</a> and associated locks. This code is fully functional and tested against Windows7. While I was developing it I noticed a great increase of performances of my software. It became 10 times faster than if using standard mutex.

This can be easily explained : I have 12 threads using the same shared resource. They spend almost 90% of their time just reading data. With a standard locking all access would have been serialized... All these threads are occasional writers : main point.

Let me present you my solution.

I mean access are mutable : promotable and demotable.

For instance, one can begin with a shared access then change it to an exclusive and back to shared and finally releases the mutex.


  • 100% based on boost library it is an extension of boost::thread
  • No system's specific function called.
  • Fully recursive.
  • Possible to suspend/resume locking.
  • Fair Locking.
  • Optional : define a main thread : from a functional point of view this makes it uninterruptible.
  • All transitions are allowed when using associated locks : mutable_xxxxx_lock.
  • Should work on all platforms supported by boost library.

Note : I did not implement all the functions. Just needed (to me) ones. But if you like this, feel free to extend it.


  • mutable_unique_lock
  • mutable_shared_lock
  • mutable_suspend_lock
  • non member function : suspend_lock


Readers must be familiar with Boost Thread libraries and with c++. This is done for advanced users. I won't explain threading neither why locking a common resource is compulsory. There are very nice tutorials that explain it.

Using the code

It's a standard recursive mutex with some extra refinements.

And it works as following.

#include "mutable_recursive_mutex.hpp"

mutable_recursive_mutex my_mutex;

int _tmain(int argc, _TCHAR* argv[])
 // defines current thread as main thread.

 mutable_shared_lock read_lock(my_mutex);
 // do some read-only work
 mutable_unique_lock write_lock(my_mutex);
 // Now ask to promote your access to exclusive.
 // You can safely write data now.

 return 0;

Fair locking

This just means the thread that waited most to gets the ownership

Main Thread

If used, this thread bypasses the fair locking and it will always take the ownership.

It has been designed to process in priority the most important data.

More the system guarantees the integrity of data when moving from shared to unique (and back).

Except if “suspend/resumeis called.


The purpose of this lock is to release the mutex regardless of its state and locking recursion level.

It is mainly designed to be able to stop the application without risking a dead-lock.

Just like other states the “suspended” state is recursive.

When entering “suspended” state all the other locking/unlocking functions are deactivated. The only working functions are :

  • suspend
  • resume
 mutable_suspend_lock lock(my_mutex);
 // current has released the mutex



All subsequent calls to :

  • <span lang="en-US">my_mutex.</span><span lang="en-US">lock()</span>
  • <span lang="en-US">my_mutex.</span><span lang="en-US">lock_shared()</span>
  • <span lang="en-US">my_mutex.</span><span lang="en-US">unlock()</span>
  • <span lang="en-US">my_mutex.</span><span lang="en-US">unlock_shared()</span>

are ignored. Recursion stack is not modified until the end of scope and/or call to : <span lang="en-US">my_mutex.</span><span lang="en-US">resume()</span>.

How it works

  • Thread states

I define 3 thread states plus one meta-state : lst_suspended.

typedef enum
} lock_state_t;

These states are stored in std::dequeue:

typedef std::deque<lock_state_t> thread_recursion_stack_t;

Each thread has its own stack :

boost::thread_specific_ptr<thread_recursion_stack_t> m_thread_states;

When a stack is created for thread the first element pushed on the stack is always : <span lang="en-US"> </span><span lang="en-US">lst_none</span>. Which means that the thread has none access to the mutex. It is similar to lst_suspended.

But lst_none is used once and only once. Unlike lst_suspended.

  • Promote

This is the heart of this work. When a thread wants to gain an exclusive access, promote function will be internally called.

It will first try to take the ownership. If it is refused (by upgrade_mutex). It will wait for a condition : m_promote_condition.

The condition is signaled each time a thread unlocks. Then all other threads are woken-up and try again to take the ownership.

Let see at it now:

void mutable_recursive_mutex::promote(thread_recursion_stack_t * stack)
 boost::thread::id thread_id = boost::this_thread::get_id();
 boost::mutex helper_mutex;
 boost::unique_lock<boost::mutex> helper_lock(helper_mutex);
 bool bnotify = (stack->front() == lst_shared);

 boost::unique_lock<boost::mutex> promote_lock(m_promote_mutex);
 if (m_is_main_thread_id_assigned && (thread_id == m_main_thread_id))
 if (bnotify) 
 while (true)
  if (m_waiting_promote_threads.front() == thread_id)
   bnotify = false;
   if (m_mutex.try_lock())
  if (bnotify)
  bnotify = false; 

The only purpose of helper_lock and helper_mutex is to make “m_promote_condition.wait(helper_lock);” working. They lock nothing at all.

if (m_is_main_thread_id_assigned && (thread_id == m_main_thread_id))

This is the fair locking subsystem with main thread.
If one looks at the whole code he will see that promote function is called from following states :

  • lst_none
  • lst_shared
  • lst_suspended (similar in this case to lst_none)

When it's lst_shared one can't say we will get the lock immediately. Thus the shared access is released. And the rule is when an access is released the condition must be signaled.

  • The promote_lock problem

=> For speed reason I take it as late as possible.
=> If I had left this work like this. It would have beed at deadlock risk. Let me explain where is the problem and how I solved it. The issue is only about the 2 following lines:


These 2 lines may drive to a deadlock because they are not executed atomically. More, most of boost library is done in user space and calls OS specific functions that do atomic work.

So if you don't want to develop at kernel level and without external help the problem has no solution.

I simply solved it by using a thread that signals the condition periodically : this is the external help. Look at : unlock_thread:

void mutable_recursive_mutex::unlock_thread()
 boost::chrono::milliseconds ms(100);
  while (true)
   boost::unique_lock<boost::mutex> promote_lock(m_promote_mutex);
   if (!m_waiting_promote_threads.empty())
 } catch (boost::thread_interrupted)

How to

If you plan to use Fair locking and/or "Main Thread" please define : FAIR_LOCKING

1) One that wants to use these classes must be able to answer following questions:

  • Do I have a thread on which everything is based on ?
  • Or are they all equivalent ?

Answer will tell you if you need to define a "main thread". I don't recommend to change "main thread" even if it is safe.

I strongly recommend to define the "main thread" one for good !

2) Policy

From a general point of view looping threads should look like this. Thanks to Espen Harlinn (who told me to clarify this point):

void std_thread()
 boost::chrono::milliseconds ms(20);
 // right place to define if needed
 while (true)
  mutable_shared_lock read_lock(my_mutex);

This way, work can begin in parallel as long as possible. This may increase the performances.

And when needed ask to promote it an exclusive. This is done using:

mutable_unique_lock write_lock(my_mutex);

3) Tips and tricks

One should pay attention to this: asking for promotion is time expensive. Thus the point is : where can I the most lately ask for a promotion. And avoid as far as possible to do it multiple times.

Whatever, once a thread acquires a unique lock, while remaining in the scope of this lock other unique lock requests are very fast (for this thread) : the mutex knows that the thread has a unique access. I'll just update the recursion stack.

Please note: this solution provides more features than a standard recursive but there is price to pay : it's time consuming.

Sample project

If asked I can make a sample project.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Software Developer
France (Metropolitan) France (Metropolitan)
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

QuestionAll threads should begin with taking a shared access?? Pin
Espen Harlinn20-Dec-12 12:47
professionalEspen Harlinn20-Dec-12 12:47 
AnswerRe: All threads should begin with taking a shared access?? Pin
jmolivieri20-Dec-12 22:21
jmolivieri20-Dec-12 22:21 
GeneralRe: All threads should begin with taking a shared access?? Pin
Espen Harlinn21-Dec-12 1:55
professionalEspen Harlinn21-Dec-12 1:55 
jmolivieri wrote:
I'm french.

With English as a second, or third, language it's harder to write decent articles, and we need to spend more time ensuring that we're actually getting the intended message across to the reader.
Espen Harlinn
Principal Architect, Software - Goodtech Projects & Services AS

Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.