Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r79612 - trunk/libs/interprocess/doc
From: igaztanaga_at_[hidden]
Date: 2012-07-19 16:59:37


Author: igaztanaga
Date: 2012-07-19 16:59:36 EDT (Thu, 19 Jul 2012)
New Revision: 79612
URL: http://svn.boost.org/trac/boost/changeset/79612

Log:
Ticket #7152
Text files modified:
   trunk/libs/interprocess/doc/interprocess.qbk | 160 ++++++++++++++++++++++-----------------
   1 files changed, 91 insertions(+), 69 deletions(-)

Modified: trunk/libs/interprocess/doc/interprocess.qbk
==============================================================================
--- trunk/libs/interprocess/doc/interprocess.qbk (original)
+++ trunk/libs/interprocess/doc/interprocess.qbk 2012-07-19 16:59:36 EDT (Thu, 19 Jul 2012)
@@ -109,7 +109,7 @@
 
 [*Boost.Interprocess] offers offset_ptr smart pointer family
 as an offset pointer that stores the distance between the address of
-the offset pointer itself and the address of the pointed object.
+the offset pointer itself and the address of the pointed object.
 When offset_ptr is placed in a shared memory segment, it
 can point safely objects stored in the same shared
 memory segment, even if the segment is mapped in
@@ -490,7 +490,7 @@
          , ShmSize/2 //Offset from the beginning of shm
          , ShmSize-ShmSize/2 //Length of the region
          );
-
+
       //Get the address of the region
       region.get_address();
 
@@ -799,7 +799,7 @@
          , FileSize/2 //Offset from the beginning of shm
          , FileSize-FileSize/2 //Length of the region
          );
-
+
       //Get the address of the region
       region.get_address();
 
@@ -1135,7 +1135,7 @@
    mapped_region region
       ( shm //Memory-mappable object
       , read_write //Access mode
- );
+ );
 
    //This address can be different in each process
    void *addr = region.get_address();
@@ -1175,7 +1175,7 @@
    //...
 
    structure s;
-
+
    //Assign the address of "integer1" to "ptr".
    //"ptr" will store internally "-4":
    // (char*)&s.integer1 - (char*)&s.ptr;
@@ -1214,7 +1214,7 @@
    using namespace boost::interprocess;
 
    offset_ptr<char> ptr;
-
+
    //Pointing to the next byte of it's own address
    //marks the smart pointer as null.
    ptr = (char*)&ptr + 1;
@@ -1278,7 +1278,7 @@
 
 * 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.
-
+
 * 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
@@ -1468,7 +1468,7 @@
    {
       //This will lock the mutex
       scoped_lock<MutexType> lock(mutex);
-
+
       //Some code
 
       //The mutex will be unlocked here
@@ -1477,26 +1477,26 @@
    {
       //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
    }
 
@@ -2103,7 +2103,7 @@
    {
       //This will call lock_sharable()
       sharable_lock<MutexType> lock(mutex);
-
+
       //Some code
 
       //The mutex will be unlocked here
@@ -2112,10 +2112,10 @@
    {
       //This won't lock the mutex()
       sharable_lock<MutexType> lock(mutex, defer_lock);
-
+
       //Lock it on demand. This will call lock_sharable()
       lock.lock();
-
+
       //Some code
 
       //The mutex will be unlocked here
@@ -2124,20 +2124,20 @@
    {
       //This will call try_lock_sharable()
       sharable_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 call timed_lock_sharable()
       scoped_lock<MutexType> lock(mutex, abs_time);
-
+
       //Check if the mutex has been successfully locked
       if(lock){
          //Some code
@@ -2148,7 +2148,7 @@
    {
       //This will call lock_upgradable()
       upgradable_lock<MutexType> lock(mutex);
-
+
       //Some code
 
       //The mutex will be unlocked here
@@ -2157,10 +2157,10 @@
    {
       //This won't lock the mutex()
       upgradable_lock<MutexType> lock(mutex, defer_lock);
-
+
       //Lock it on demand. This will call lock_upgradable()
       lock.lock();
-
+
       //Some code
 
       //The mutex will be unlocked here
@@ -2169,20 +2169,20 @@
    {
       //This will call try_lock_upgradable()
       upgradable_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 call timed_lock_upgradable()
       scoped_lock<MutexType> lock(mutex, abs_time);
-
+
       //Check if the mutex has been successfully locked
       if(lock){
          //Some code
@@ -2710,7 +2710,7 @@
       //The sharable lock is automatically released by
       //sh_lock's destructor
    }
-
+
 [c++]
 
    #include <boost/interprocess/sync/file_lock.hpp>
@@ -3025,7 +3025,7 @@
 
    * See [link interprocess.customizing_interprocess.custom_interprocess_alloc Writing a new memory
       allocation algorithm] for more details about memory algorithms.
-
+
 * *IndexType* is the type of index that will be used to store the name-object
    association (for example, a map, a hash-map, or an ordered vector).
 
@@ -3187,7 +3187,7 @@
 
    fixed_managed_shared_memory segment (open_only ,"MyFixedAddressSharedMemory" //Shared memory object name
       ,(void*)0x30000000 //Mapping address
-
+
 [endsect]
 
 [section:windows_managed_memory_common_shm Using native windows shared memory]
@@ -3425,7 +3425,7 @@
    MyType *ptr = managed_memory_segment.construct_it<MyType>("Name")[count](it1, it2...);
 
    //!Tries to find a previously created object. If not present, allocates and constructs
- //!an array of objects of type MyType (throwing version). Each object receives
+ //!an array of objects of type MyType (throwing version). Each object receives
    //!parameters returned with the expression (*it1++, *it2++,... )
    MyType *ptr = managed_memory_segment.find_or_construct_it<MyType>("Name")[count](it1, it2...);
 
@@ -3531,7 +3531,7 @@
 [c++]
 
    MyType *ptr = managed_shared_memory.find_or_construct<MyType>("Name")[count](par1, par2...);
-
+
 at the same time, but only one process will create the object and the other will
 obtain a pointer to the created object.
 
@@ -4222,7 +4222,7 @@
 [c++]
 
    #include <boost/interprocess/managed_external_buffer.hpp>
-
+
 Let's see an example of the use of managed_external_buffer:
 
 [import ../example/doc_managed_external_buffer.cpp]
@@ -4996,14 +4996,14 @@
 [c++]
 
    #include <boost/interprocess/containers/vector.hpp>
-
+
 * [*boost:interprocess::deque] is the implementation of `std::deque` ready
    to be used in managed memory segments like shared memory. To use it include:
 
 [c++]
 
    #include <boost/interprocess/containers/deque.hpp>
-
+
 * [classref boost::interprocess::list list] is the implementation of `std::list` ready
    to be used in managed memory segments like shared memory. To use it include:
 
@@ -5017,7 +5017,7 @@
 [c++]
 
    #include <boost/interprocess/containers/slist.hpp>
-
+
 * [classref boost::interprocess::set set]/
    [classref boost::interprocess::multiset multiset]/
    [classref boost::interprocess::map map]/
@@ -5044,7 +5044,7 @@
 
    #include <boost/interprocess/containers/flat_set.hpp>
    #include <boost/interprocess/containers/flat_map.hpp>
-
+
 * [classref boost::interprocess::basic_string basic_string]
    is the implementation of `std::basic_string` ready
    to be used in managed memory segments like shared memory.
@@ -5056,7 +5056,7 @@
 [c++]
 
    #include <boost/interprocess/containers/string.hpp>
-
+
 All these containers have the same default arguments as standard
 containers and they can be used with other, non [*Boost.Interprocess]
 allocators (std::allocator, or boost::pool_allocator, for example).
@@ -5212,17 +5212,17 @@
 
    simple_seq_fit memory layout:
 
- main extra allocated free_block_1 allocated free_block_2 allocated free_block_3
+ main extra allocated free_block_1 allocated free_block_2 allocated free_block_3
        header header block ctrl usr block ctrl usr block ctrl usr
       _________ _____ _________ _______________ _________ _______________ _________ _______________
      | || || || | || || | || || | |
      |free|ctrl||extra|| ||next|size| mem || ||next|size| mem || ||next|size| mem |
      |_________||_____||_________||_________|_____||_________||_________|_____||_________||_________|_____|
- | | | | | | |
- |_>_>_>_>_>_>_>_>_>_>_>_>_| |_>_>_>_>_>_>_>_>_>_>_>_>_| |_>_>_>_>_>_>_>_>_>_>_>_| |
+ | | | | | | |
+ |_>_>_>_>_>_>_>_>_>_>_>_>_| |_>_>_>_>_>_>_>_>_>_>_>_>_| |_>_>_>_>_>_>_>_>_>_>_>_| |
                                    | |
                                    |_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<_<__|
-
+
 When a user requests N bytes of memory, the allocator
 traverses the free block list looking for a block large
 enough. If the "mem" part of the block has the same
@@ -5273,13 +5273,13 @@
 [c++]
 
    rbtree_best_fit memory layout:
-
+
       main allocated block free block allocated block free block
- header
- _______________ _______________ _________________________________ _______________ _________________________________
- | || | || | | || | || | | |
- | main header ||next|prev| mem ||next|prev|left|right|parent| mem ||next|prev| mem ||next|prev|left|right|parent| mem |
- |_______________||_________|_____||_________|_________________|_____||_________|_____||_________|_________________|_____|
+ header
+ _______________ _______________ _________________________________ _______________ _________________________________
+ | || | || | | || | || | | |
+ | main header ||next|prev| mem ||next|prev|left|right|parent| mem ||next|prev| mem ||next|prev|left|right|parent| mem |
+ |_______________||_________|_____||_________|_________________|_____||_________|_____||_________|_________________|_____|
 
 
 This allocation algorithm is pretty fast and scales well with big shared memory
@@ -5301,7 +5301,7 @@
 For allocations bigger than 8 bytes the memory overhead is exactly the same.
 This is the default allocation algorithm in [*Boost.Interprocess] managed memory
 segments.
-
+
 [endsect]
 
 [endsect]
@@ -5324,10 +5324,10 @@
    //Some formatting elements
    std::string my_text = "...";
    int number;
-
+
    //Data reader
    std::istringstream input_processor;
-
+
    //This makes a copy of the string. If not using a
    //reference counted string, this is a serious overhead.
    input_processor.str(my_text);
@@ -5336,15 +5336,15 @@
    while(/*...*/){
       input_processor >> number;
    }
-
+
    //Data writer
    std::ostringstream output_processor;
-
+
    //Write data
    while(/*...*/){
       output_processor << number;
    }
-
+
    //This returns a temporary string. Even with return-value
    //optimization this is expensive.
    my_text = input_processor.str();
@@ -5465,7 +5465,7 @@
       typedef typename std::basic_ios<char_type, CharTraits>::pos_type pos_type;
       typedef typename std::basic_ios<char_type, CharTraits>::off_type off_type;
       typedef typename std::basic_ios<char_type, CharTraits>::traits_type traits_type;
-
+
       //!Constructor. Does not throw.
       basic_bufferstream(std::ios_base::openmode mode
                         = std::ios_base::in | std::ios_base::out);
@@ -5485,7 +5485,7 @@
       //!Sets the underlying buffer to a new value. Resets
       //!stream position. Does not throw.
       void buffer(CharT *buffer, std::size_t length);
- };
+ };
 
    //Some typedefs to simplify usage
    typedef basic_bufferstream<char> bufferstream;
@@ -5587,7 +5587,7 @@
    //!offset_ptr<void>, the internal pointer will be offset_ptr<T>).
    template<class T, class Deleter>
    class scoped_ptr;
-
+
 `scoped_ptr<>` comes handy to implement *rollbacks* with exceptions: if an exception
 is thrown or we call `return` in the scope of `scoped_ptr<>` the deleter is
 automatically called so that *the deleter can be considered as a rollback* function.
@@ -5819,7 +5819,7 @@
 [c++]
 
    Layout of the memory segment:
- ____________ __________ ____________________________________________
+ ____________ __________ ____________________________________________
    | | | |
    | memory | reserved | The memory algorithm will return portions |
    | algorithm | | of the rest of the segment. |
@@ -6114,7 +6114,7 @@
    of these containers when you know beforehand how much data you will insert.
    However in these containers iterators are invalidated in insertions so this
    substitution is only effective in some applications.
-
+
 * Use a [*Boost.Interprocess] pooled allocator for node containers, because pooled
    allocators call `allocate()` only when the pool runs out of nodes. This is pretty
    efficient (much more than the current default general-purpose algorithm) and this
@@ -6187,7 +6187,7 @@
    * If it's not an node index: Take the name stored near the object and erase
       the index entry calling `erase(const key &). This can require element reordering
       if the index is a balanced tree, an ordered vector...
-
+
 * Call the destructor of the object (many if it's an array).
 
 * Deallocate the memory buffer containing the name, metadata and the object itself
@@ -6261,7 +6261,7 @@
 
       //!Increases managed memory in extra_size bytes more
       void grow(std::size_t extra_size);
- /*...*/
+ /*...*/
    };
 
 Let's see the public typedefs to define:
@@ -6356,7 +6356,7 @@
    //using a user-defined memory allocation algorithm
    basic_managed_shared_memory<char,
                             ,my_algorithm
- ,flat_map_index>
+ ,flat_map_index>
       my_managed_shared_memory;
 
 [endsect]
@@ -6383,7 +6383,7 @@
       (create_only
       ,"/MySharedMemory" //segment name
       ,65536); //segment size in bytes
-
+
    //Obtain the segment manager
    managed_shared_memory::segment_manager *segment_mngr
       = segment.get_segment_manager();
@@ -6465,7 +6465,7 @@
 
 The `key_type` typedef of the passed `index_traits` will be a specialization of the
 following class:
-
+
 [c++]
 
    //!The key of the named allocation information index. Stores a to
@@ -6496,7 +6496,7 @@
 define the index type. The *segment_manager* will be the type of the segment manager that
 will manage the index. `segment_manager` will define interesting internal types like
 `void_pointer` or `mutex_family`.
-
+
 * The constructor of the customized index type must take a pointer to segment_manager
   as constructor argument:
 
@@ -6560,7 +6560,7 @@
                                  char,
                                  rbtree_best_fit<mutex_family>,
                                  my_index_type
- >
+ >
       my_managed_shared_memory;
 
 [endsect]
@@ -6570,6 +6570,26 @@
 
 [section:acknowledgements_notes Acknowledgements, notes and links]
 
+[section:notes Notes]
+
+[section:notes_windows Notes for Windows users]
+
+[*Boost.Interprocess] uses the COM library to implement some features and initializes
+the COM library with concurrency model `COINIT_APARTMENTTHREADED`.
+If the COM library was already initialized by the calling thread for other model, [*Boost.Interprocess]
+handles this gracefully and uses COM calls for the already initialized model. If for some reason, you
+might want [*Boost.Interprocess] to initialize the COM library with another model, define the macro
+`BOOST_INTERPROCESS_WINDOWS_COINIT_MODEL` before including [*Boost.Interprocess] to one of these values:
+
+* `COINIT_APARTMENTTHREADED_BIPC`
+* `COINIT_MULTITHREADED_BIPC`
+* `COINIT_DISABLE_OLE1DDE_BIPC`
+* `COINIT_SPEED_OVER_MEMORY_BIPC`
+
+[endsect]
+
+[endsect]
+
 [section:thanks_to Thanks to...]
 
 [section:thanks_to_people People]
@@ -6596,9 +6616,9 @@
 
 * Thanks to [*Olaf Krzikalla] for his Intrusive library. I have taken some ideas to
    improve red black tree implementation from his library.
-
+
 * Thanks to [*Daniel James] for his unordered_map/set family and his help with allocators.
- His great unordered implementation has been a reference to design exception safe containers.
+ His great unordered implementation has been a reference to design exception safe containers.
 
 * Thanks to [*Howard Hinnant] for his amazing help, specially explaining allocator swapping,
    move semantics and for developing upgradable mutex and lock transfer features.
@@ -6620,6 +6640,8 @@
 * Synchronous and asynchronous flushing for `mapped_region::flush`.
 * Source & ABI breaking: Removed `get_offset` method from `mapped_region` as
    it has no practical utility and `m_offset` member was not for anything else.
+* Fixed bug
+ [@https://svn.boost.org/trac/boost/ticket/7152 #7152],
 
 [endsect]
 
@@ -6918,10 +6940,10 @@
    pointers.
 
 * (multi)map/(multi)set now reuse memory from old nodes in the assignment operator.
-
+
 * [*ABI breaking]: Implemented node-containers based on intrusive containers.
    This saves code size, since many instantiations share the same algorithms.
-
+
 * Corrected code to be compilable with Visual C++ 8.0.
 
 * Added function to zero free memory in memory algorithms and the segment manager.
@@ -6997,7 +7019,7 @@
 
 * [*ABI breaking]: Reimplemented and optimized small string optimization. The narrow
    string class has zero byte overhead with an internal 11 byte buffer in 32 systems!
-
+
 * Added move semantics to containers. Improves
    performance when using containers of containers.
 


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk