boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Synchronization mechanisms</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../interprocess.html" title="Chapter 14. Boost.Interprocess"> <link rel="prev" href="offset_ptr.html" title="Mapping Address Independent Pointer: offset_ptr"> <link rel="next" href="managed_memory_segments.html" title="Managed Memory Segments"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="offset_ptr.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../interprocess.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="managed_memory_segments.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="interprocess.synchronization_mechanisms"></a><a class="link" href="synchronization_mechanisms.html" title="Synchronization mechanisms">Synchronization mechanisms</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview">Synchronization mechanisms overview</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes">Mutexes</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions">Conditions</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores">Semaphores</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes">Sharable and Upgradable Mutexes</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions">Lock Transfers Through Move Semantics</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock">File Locks</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue">Message Queue</a></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview" title="Synchronization mechanisms overview">Synchronization mechanisms overview</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous">Named And Anonymous Synchronization Mechanisms</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types">Types Of Synchronization Mechanisms</a></dt> </dl></div> As mentioned before, the ability to shared memory between processes through memory mapped files or shared memory objects is not very useful if the access to that memory can't be effectively synchronized. This is the same problem that happens with thread-synchronization mechanisms, where heap memory and global variables are shared between threads, but the access to these resources needs to be synchronized typically through mutex and condition variables. Boost.Threads implements these synchronization utilities between threads inside the same process. Boost.Interprocess implements similar mechanisms to synchronize threads from different processes. <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous" title="Named And Anonymous Synchronization Mechanisms">Named And Anonymous Synchronization Mechanisms</a> </h4></div></div></div> Boost.Interprocess presents two types of synchronization objects: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Named utilities: When two processes want to create an object of such type, both processes must create or open an object using the same name. This is similar to creating or opening files: a process creates a file with using a <code class="computeroutput">fstream</code> with the name filename and another process opens that file using another <code class="computeroutput">fstream</code> with the same filename argument. Each process uses a different object to access to the resource, but both processes are using the same underlying resource. </li> <li class="listitem"> Anonymous utilities: Since these utilities have no name, two processes must share the same object through shared memory or memory mapped files. This is similar to traditional thread synchronization objects: Both processes share the same object. Unlike thread synchronization, where global variables and heap memory is shared between threads of the same process, sharing objects between two threads from different process can be only possible through mapped regions that map the same mappable resource (for example, shared memory or memory mapped files). </li> </ul></div> Each type has it's own advantages and disadvantages: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Named utilities are easier to handle for simple synchronization tasks, since both process don't have to create a shared memory region and construct the synchronization mechanism there. </li> <li class="listitem"> Anonymous utilities can be serialized to disk when using memory mapped objects obtaining automatic persistence of synchronization utilities. One could construct a synchronization utility in a memory mapped file, reboot the system, map the file again, and use the synchronization utility again without any problem. This can't be achieved with named synchronization utilities. </li> </ul></div> The main interface difference between named and anonymous utilities are the constructors. Usually anonymous utilities have only one constructor, whereas the named utilities have several constructors whose first argument is a special type that requests creation, opening or opening or creation of the underlying resource: <pre class="programlisting">using namespace boost::interprocess; //Create the synchronization utility. If it previously //exists, throws an error NamedUtility(create_only, ...) //Open the synchronization utility. If it does not previously //exist, it's created. NamedUtility(open_or_create, ...) //Open the synchronization utility. If it does not previously //exist, throws an error. NamedUtility(open_only, ...) </pre> On the other hand the anonymous synchronization utility can only be created and the processes must synchronize using other mechanisms who creates the utility: <pre class="programlisting">using namespace boost::interprocess; //Create the synchronization utility. AnonymousUtility(...) </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types" title="Types Of Synchronization Mechanisms">Types Of Synchronization Mechanisms</a> </h4></div></div></div> Apart from its named/anonymous nature, Boost.Interprocess presents the following synchronization utilities: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Mutexes (named and anonymous) </li> <li class="listitem"> Condition variables (named and anonymous) </li> <li class="listitem"> Semaphores (named and anonymous) </li> <li class="listitem"> Upgradable mutexes </li> <li class="listitem"> File locks </li> </ul></div> </div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes" title="Mutexes">Mutexes</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex">What's A Mutex?</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations">Mutex Operations</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes">Boost.Interprocess Mutex Types And Headers</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock">Scoped lock</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example">Anonymous mutex example</a></dt> <dt><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_named_example">Named mutex example</a></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex" title="What's A Mutex?">What's A Mutex?</a> </h4></div></div></div> Mutex stands for mutual exclusion and it's the most basic form of synchronization between processes. Mutexes guarantee that only one thread can lock a given mutex. If a code section is surrounded by a mutex locking and unlocking, it's guaranteed that only a thread at a time executes that section of code. When that thread unlocks the mutex, other threads can enter to that code region: <pre class="programlisting">//The mutex has been previously constructed lock_the_mutex(); //This code will be executed only by one thread //at a time. unlock_the_mutex(); </pre> A mutex can also be recursive or non-recursive: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Recursive mutexes can be locked several times by the same thread. To fully unlock the mutex, the thread has to unlock the mutex the same times it has locked it. </li> <li class="listitem"> Non-recursive mutexes can't be locked several times by the same thread. If a mutex is locked twice by a thread, the result is undefined, it might throw an error or the thread could be blocked forever. </li> </ul></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations" title="Mutex Operations">Mutex Operations</a> </h4></div></div></div> All the mutex types from Boost.Interprocess implement the following operations: <div class="sidebar"> <div class="titlepage"></div> void lock() </div> Effects: The calling thread tries to obtain ownership of the mutex, and if another thread has ownership of the mutex, it waits until it can obtain the ownership. If a thread takes ownership of the mutex the mutex must be unlocked by the same thread. If the mutex supports recursive locking, the mutex must be unlocked the same number of times it is locked. Throws: interprocess_exception on error. <div class="sidebar"> <div class="titlepage"></div> bool try_lock() </div> Effects: The calling thread tries to obtain ownership of the mutex, and if another thread has ownership of the mutex returns immediately. If the mutex supports recursive locking, the mutex must be unlocked the same number of times it is locked. Returns: If the thread acquires ownership of the mutex, returns true, if the another thread has ownership of the mutex, returns false. Throws: interprocess_exception on error. <div class="sidebar"> <div class="titlepage"></div> bool timed_lock(const boost::posix_time::ptime &abs_time) </div> Effects: The calling thread will try to obtain exclusive ownership of the mutex if it can do so in until the specified time is reached. If the mutex supports recursive locking, the mutex must be unlocked the same number of times it is locked. Returns: If the thread acquires ownership of the mutex, returns true, if the timeout expires returns false. Throws: interprocess_exception on error. <div class="sidebar"> <div class="titlepage"></div> void unlock() </div> Precondition: The thread must have exclusive ownership of the mutex. Effects: The calling thread releases the exclusive ownership of the mutex. If the mutex supports recursive locking, the mutex must be unlocked the same number of times it is locked. Throws: An exception derived from interprocess_exception on error. <div class="important"><table border="0" summary="Important"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> <th align="left">Important</th> </tr> <tr><td align="left" valign="top"> <code class="computeroutput">boost::posix_time::ptime</code> absolute time points used by Boost.Interprocess synchronization mechanisms are UTC time points, not local time points </td></tr> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes" title="Boost.Interprocess Mutex Types And Headers">Boost.Interprocess Mutex Types And Headers</a> </h4></div></div></div> Boost.Interprocess offers the following mutex types: <pre class="programlisting">#include <boost/interprocess/sync/interprocess_mutex.hpp> </pre> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_mutex.html" title="Class interprocess_mutex">interprocess_mutex</a></code>: A non-recursive, anonymous mutex that can be placed in shared memory or memory mapped files. </li></ul></div> <pre class="programlisting">#include <boost/interprocess/sync/interprocess_recursive_mutex.hpp> </pre> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_r_idp66640512.html" title="Class interprocess_recursive_mutex">interprocess_recursive_mutex</a></code>: A recursive, anonymous mutex that can be placed in shared memory or memory mapped files. </li></ul></div> <pre class="programlisting">#include <boost/interprocess/sync/named_mutex.hpp> </pre> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> <code class="computeroutput"><a class="link" href="../boost/interprocess/named_mutex.html" title="Class named_mutex">named_mutex</a></code>: A non-recursive, named mutex. </li></ul></div> <pre class="programlisting">#include <boost/interprocess/sync/named_recursive_mutex.hpp> </pre> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> <code class="computeroutput"><a class="link" href="../boost/interprocess/named_recursive_mutex.html" title="Class named_recursive_mutex">named_recursive_mutex</a></code>: A recursive, named mutex. </li></ul></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock" title="Scoped lock">Scoped lock</a> </h4></div></div></div> It's very important to unlock a mutex after the process has read or written the data. This can be difficult when dealing with exceptions, so usually mutexes are used with a scoped lock, a class that can guarantee that a mutex will always be unlocked even when an exception occurs. To use a scoped lock just include: <pre class="programlisting">#include <boost/interprocess/sync/scoped_lock.hpp> </pre> Basically, a scoped lock calls unlock() in its destructor, and a mutex is always unlocked when an exception occurs. Scoped lock has many constructors to lock, try_lock, timed_lock a mutex or not to lock it at all. <pre class="programlisting">using namespace boost::interprocess; //Let's create any mutex type: MutexType mutex; { //This will lock the mutex scoped_lock<MutexType> lock(mutex); //Some code //The mutex will be unlocked here } { //This will try_lock the mutex scoped_lock<MutexType> lock(mutex, try_to_lock); //Check if the mutex has been successfully locked if(lock){ //Some code } //If the mutex was locked it will be unlocked } { boost::posix_time::ptime abs_time = ... //This will timed_lock the mutex scoped_lock<MutexType> lock(mutex, abs_time); //Check if the mutex has been successfully locked if(lock){ //Some code } //If the mutex was locked it will be unlocked } </pre> For more information, check the <code class="computeroutput"><a class="link" href="../boost/interprocess/scoped_lock.html" title="Class template scoped_lock">scoped_lock's reference</a></code>. <div class="important"><table border="0" summary="Important"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> <th align="left">Important</th> </tr> <tr><td align="left" valign="top"> <code class="computeroutput">boost::posix_time::ptime</code> absolute time points used by Boost.Interprocess synchronization mechanisms are UTC time points, not local time points </td></tr> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example" title="Anonymous mutex example">Anonymous mutex example</a> </h4></div></div></div> Imagine that two processes need to write traces to a cyclic buffer built in shared memory. Each process needs to obtain exclusive access to the cyclic buffer, write the trace and continue. To protect the cyclic buffer, we can store a process shared mutex in the cyclic buffer. Each process will lock the mutex before writing the data and will write a flag when ends writing the traces (<code class="computeroutput">doc_anonymous_mutex_shared_data.hpp</code> header): <pre class="programlisting">#include <boost/interprocess/sync/interprocess_mutex.hpp> struct shared_memory_log { enum { NumItems = 100 }; enum { LineSize = 100 }; shared_memory_log() : current_line(0) , end_a(false) , end_b(false) {} //Mutex to protect access to the queue boost::interprocess::interprocess_mutex mutex; //Items to fill char items[NumItems][LineSize]; int current_line; bool end_a; bool end_b; }; </pre> This is the process main process. Creates the shared memory, constructs the cyclic buffer and start writing traces: <pre class="programlisting">#include <boost/interprocess/shared_memory_object.hpp> #include <boost/interprocess/mapped_region.hpp> #include <boost/interprocess/sync/scoped_lock.hpp> #include "doc_anonymous_mutex_shared_data.hpp" #include <iostream> #include <cstdio> using namespace boost::interprocess; int main () { try{ //Remove shared memory on construction and destruction struct shm_remove { shm_remove() { shared_memory_object::remove("MySharedMemory"); } ~shm_remove(){ shared_memory_object::remove("MySharedMemory"); } } remover; //Create a shared memory object. shared_memory_object shm (create_only //only create ,"MySharedMemory" //name ,read_write //read-write mode ); //Set size shm.truncate(sizeof(shared_memory_log)); //Map the whole shared memory in this process mapped_region region (shm //What to map ,read_write //Map it as read-write ); //Get the address of the mapped region void * addr = region.get_address(); //Construct the shared structure in memory shared_memory_log * data = new (addr) shared_memory_log; //Write some logs for(int i = 0; i < shared_memory_log::NumItems; ++i){ //Lock the mutex scoped_lock<interprocess_mutex> lock(data->mutex); std::sprintf(data->items[(data->current_line++) % shared_memory_log::NumItems] ,"%s_%d", "process_a", i); if(i == (shared_memory_log::NumItems-1)) data->end_a = true; //Mutex is released here } //Wait until the other process ends while(1){ scoped_lock<interprocess_mutex> lock(data->mutex); if(data->end_b) break; } } catch(interprocess_exception &ex){ std::cout << ex.what() << std::endl; return 1; } return 0; } </pre> The second process opens the shared memory, obtains access to the cyclic buffer and starts writing traces: <pre class="programlisting">#include <boost/interprocess/shared_memory_object.hpp> #include <boost/interprocess/mapped_region.hpp> #include <boost/interprocess/sync/scoped_lock.hpp> #include "doc_anonymous_mutex_shared_data.hpp" #include <iostream> #include <cstdio> using namespace boost::interprocess; int main () { //Remove shared memory on destruction struct shm_remove { ~shm_remove(){ shared_memory_object::remove("MySharedMemory"); } } remover; //Open the shared memory object. shared_memory_object shm (open_only //only create ,"MySharedMemory" //name ,read_write //read-write mode ); //Map the whole shared memory in this process mapped_region region (shm //What to map ,read_write //Map it as read-write ); //Get the address of the mapped region void * addr = region.get_address(); //Construct the shared structure in memory shared_memory_log * data = static_cast<shared_memory_log*>(addr); //Write some logs for(int i = 0; i < 100; ++i){ //Lock the mutex scoped_lock<interprocess_mutex> lock(data->mutex); std::sprintf(data->items[(data->current_line++) % shared_memory_log::NumItems] ,"%s_%d", "process_a", i); if(i == <span class="special