Add more documentation and examples uses_allocator usage.

Author: igaztanaga

doc/interprocess.qbk

@@ -5167,7 +5167,9 @@ To place any of these containers in managed memory segments, we must
 define the allocator template parameter with a [*Boost.Interprocess] allocator
 so that the container allocates the values in the managed memory segment.
 To place the container itself in shared memory, we construct it
-in the managed memory segment just like any other object with [*Boost.Interprocess]:
+in the managed memory segment just like any other object with [*Boost.Interprocess].
+Note how these containers also support the uses-allocator protocol that simplifies
+usage due to the implicit allocator passing protocol:
 
 [import ../example/doc_cont.cpp]
 [doc_cont]
@@ -5263,7 +5265,9 @@ and those strings need to be placed in shared memory. Shared memory strings requ
 an allocator in their constructors so this usually makes object insertion a bit more
 complicated.
 
-Here is an example that shows how to put a multi index container in shared memory:
+Here is an example that shows how to put a multi index container in shared memory. Note
+also how MultiIndex supports the [link interprocess.managed_memory_segment_object_construction.uses_allocator uses-allocator construction]
+so that allocator arguments can be automatically propagated into internal allocator-aware components:
 
 [import ../example/doc_multi_index.cpp]
 [doc_multi_index]
@@ -6853,7 +6857,8 @@ thank them:
 
 [section:release_notes_boost_1_91_00 Boost 1.91 Release]
 
-* Adds uses-allocator-construction (for types where `boost::container::uses_allocator<T>::value == true`), in the following utilities:
+* Adds [link interprocess.managed_memory_segment_object_construction.uses_allocator uses-allocator construction]
+   (for types where `boost::container::uses_allocator<T>::value == true`), in the following utilities:
    * Segment managers in their `construct` methods
    * Allocators
 

example/doc_complex_map_uses_allocator.cpp

@@ -15,6 +15,7 @@
 #include <boost/container/map.hpp>
 #include <boost/container/vector.hpp>
 #include <boost/container/string.hpp>
+//=#include <functional>
 //<-
 #include "../test/get_process_id_name.hpp"
 //->

example/doc_cont.cpp

@@ -62,6 +62,15 @@ int main ()
    // . . .
    //When done, destroy and delete vector from the segment
    segment.destroy<MyVector>("MyVector");
+
+   //Note that you can take advantage of the uses-allocator protocol and avoid
+   //explicitly passing the allocator parameter ("construct" will detect the container
+   //is compatible with the protocol and initialize the allocator accordingly:
+   myvector = segment.construct<MyVector>("MyVector") (begVal,endVal);
+
+   //Alternative destroy function that takes the pointer instead of the name
+   segment.destroy_ptr(myvector);
+
    return 0;
 }
 //]

example/doc_multi_index.cpp

@@ -38,6 +38,8 @@ typedef boost::container::basic_string<char, std::char_traits<char>, char_alloca
 //Data to insert in shared memory
 struct employee
 {
+   typedef char_allocator allocator_type; //enables uses-allocator protocol
+
    int         id;
    int         age;
    shm_string  name;
@@ -85,7 +87,7 @@ int main ()
    //Create shared memory
    managed_shared_memory segment(create_only,test::get_process_id_name(), 65536);
 
-   //Construct the multi_index in shared memory
+   //Construct the multi_index in shared memory (classic construction)
    employee_set *es = segment.construct<employee_set>
       ("My MultiIndex Container")            //Container's name in shared memory
       ( employee_set::ctor_args_list()
@@ -96,6 +98,19 @@ int main ()
    es->insert(employee(0,31, "Joe", ca));
    es->insert(employee(1,27, "Robert", ca));
    es->insert(employee(2,40, "John", ca));
+   segment.destroy_ptr(es);
+
+   //Now re-construct it using the uses-allocator protocol
+   es = segment.construct<employee_set>
+      ("My MultiIndex Container")       //Container's name in shared memory
+      ( employee_set::ctor_args_list() );    //Allocator parameters is implicit
+
+   //Now emplace elements (more natural, the allocator is implicitly propagated)
+   es->emplace(0,31, "Joe");
+   es->emplace(1,27, "Robert");
+   es->emplace(2,40, "John");
+   segment.destroy_ptr(es);
+
    return 0;
 }
 //]