Skip to content

Commit

Permalink
Sync from upstream.
Browse files Browse the repository at this point in the history
  • Loading branch information
@grafikrobot
grafikrobot committed Aug 9, 2024
2 parents 70dc8a7 + 3ead949 commit 18b4126
Show file tree
Hide file tree
Showing 84 changed files with 380 additions and 1,122 deletions.
1 change: 1 addition & 0 deletions doc/Jamfile.v2
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ doxygen autodoc
\"BOOST_RV_REF_END=&&\" \\
\"BOOST_FWD_REF(T)=T&&\" \\
\"BOOST_INTERPROCESS_FORCEINLINE=inline\" \\
\"op_nullptr_t=std::nullptr_t\" \\
"

<xsl:param>"boost.doxygen.reftitle=Boost.Interprocess Header Reference"
Expand Down
176 changes: 61 additions & 115 deletions doc/interprocess.qbk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@
[def BOOST_INTERPROCESS_RETHROW throw;]
[def BOOST_INTERPROCESS_CATCH_END]

[def test::get_process_id_name() "MySharedMemory"]
[def test::get_process_id_name() "MyName"]
[def argv[2] "MyName"]



[section:intro Introduction]
Expand Down Expand Up @@ -3195,29 +3197,29 @@ To use a managed shared memory, you must include the following header:
[c++]

//1. Creates a new shared memory object
// called "MySharedMemory".
// called "MyName".
//2. Maps the whole object to this
// process' address space.
//3. Constructs some objects in shared memory
// to implement managed features.
//!! If anything fails, throws interprocess_exception
//
managed_shared_memory segment ( create_only
, "MySharedMemory" //Shared memory object name
, 65536); //Shared memory object size in bytes
, "MyName" //Shared memory object name
, 65536); //Shared memory object size in bytes


[c++]

//1. Opens a shared memory object
// called "MySharedMemory".
// called "MyName".
//2. Maps the whole object to this
// process' address space.
//3. Obtains pointers to constructed internal objects
// to implement managed features.
//!! If anything fails, throws interprocess_exception
//
managed_shared_memory segment (open_only, "MySharedMemory");//Shared memory object name
managed_shared_memory segment (open_only, "MyName"); //Shared memory object name


[c++]
Expand All @@ -3228,8 +3230,8 @@ To use a managed shared memory, you must include the following header:
//!! If anything fails, throws interprocess_exception
//
managed_shared_memory segment ( open_or_create
, "MySharedMemory" //Shared memory object name
, 65536); //Shared memory object size in bytes
, "MyName" //Shared memory object name
, 65536); //Shared memory object size in bytes


When the `managed_shared_memory` object is destroyed, the shared memory
Expand Down Expand Up @@ -4418,7 +4420,7 @@ through a message queue and duplicated in another buffer:

[endsect]

[section:allocators_containers Allocators, containers and memory allocation algorithms]
[section:allocators_containers Allocators and memory allocation algorithms]

[section:allocator_introduction Introduction to Interprocess allocators]

Expand All @@ -4429,7 +4431,7 @@ To achieve this, [*Boost.Interprocess] makes use of managed memory segment's
memory allocation algorithms to build several memory allocation schemes, including
general purpose and node allocators.

[*Boost.Interprocess] STL compatible allocators are configurable via template parameters.
[*Boost.Interprocess] allocators are configurable via template parameters.
Allocators define their `pointer` typedef based on the `void_pointer` typedef of the segment manager
passed as template argument. When this `segment_manager::void_pointer` is a relative pointer,
(for example, `offset_ptr<void>`) the user can place these allocators in
Expand Down Expand Up @@ -5008,7 +5010,9 @@ An example using [classref boost::interprocess::cached_adaptive_pool cached_adap

[endsect]

[section:containers_explained Interprocess and containers in managed memory segments]
[endsect]

[section:containers_explained Containers in managed memory segments]

[section:stl_container_requirements Container requirements for Boost.Interprocess allocators]

Expand All @@ -5017,7 +5021,8 @@ interface and if they define their internal *pointer* typedef as a relative poin
they can be used to place STL containers in shared memory, memory mapped files or
in a user defined memory segment.

However, as Scott Meyers mentions in his Effective STL
Originally, in C++98 and C++03, this *pointer* typedef was useless.
As Scott Meyers mentions in his Effective STL
book, Item 10, ['"Be aware of allocator conventions and
restrictions"]:

Expand Down Expand Up @@ -5049,94 +5054,47 @@ mapped files with [*Boost.Interprocess] can't make any of these assumptions, so:
* Containers' internal pointers should be of the type allocator::pointer
and containers may not assume allocator::pointer is a raw pointer.

* All objects must be constructed-destroyed via
allocator::construct and allocator::destroy functions.

[endsect]

[section:containers STL containers in managed memory segments]

Unfortunately, many STL implementations use raw pointers
for internal data and ignore allocator pointer typedefs
and others suppose at some point that the allocator::typedef
is T*. This is because in practice,
there wasn't need of allocators with a pointer typedef
different from T* for pooled/node memory
allocators.

Until STL implementations handle allocator::pointer typedefs
in a generic way, [*Boost.Interprocess] offers the following classes:

* [*boost:interprocess::vector] is the implementation of `std::vector` ready
to be used in managed memory segments like shared memory. To use it include:

[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:

[c++]

#include <boost/interprocess/containers/list.hpp>

* [classref boost::interprocess::slist slist] is the implementation of SGI's `slist` container (singly linked list) ready
to be used in managed memory segments like shared memory. To use it include:

[c++]

#include <boost/interprocess/containers/slist.hpp>

* [classref boost::interprocess::set set]/
[classref boost::interprocess::multiset multiset]/
[classref boost::interprocess::map map]/
[classref boost::interprocess::multimap multimap] family is the implementation of
std::set/multiset/map/multimap family ready
to be used in managed memory segments like shared memory. To use them include:
This was in theory fixed in C++11, when `std::pointer_traits` utilities were introduced
and standard library containers added support for them. However, due to ABI
concerns and low user demand, some implementations still
don't fully support ['fancy pointer] types like
`boost::interprocess:offset_ptr`. Those implementations still use raw pointers
in some containers for internal data or iterator implementations.

[c++]
This non-portable situation is described in
[@https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0773r0.html ['"P0773R0: Towards meaningful fancy pointers"] ]

#include <boost/interprocess/containers/set.hpp>
#include <boost/interprocess/containers/map.hpp>
[:['Can we use offset fancy pointer types to enable safe sharing of memory regions?]]
[:['Yes; but the requirements on vendors are unclear, and there are pitfalls for the programmer.]]
[:['Scenario (A), offset pointers, has only one tenable solution, "continue to partly support."]]

* [classref boost::interprocess::flat_set flat_set]/
[classref boost::interprocess::flat_multiset flat_multiset]/
[classref boost::interprocess::flat_map flat_map]/
[classref boost::interprocess::flat_multimap flat_multimap] classes are the
adaptation and extension of Andrei Alexandrescu's famous AssocVector class
from Loki library, ready for the shared memory. These classes offer the same
functionality as `std::set/multiset/map/multimap` implemented with an ordered vector,
which has faster lookups than the standard ordered associative containers
based on red-black trees, but slower insertions. To use it include:

[c++]
[endsect]

#include <boost/interprocess/containers/flat_set.hpp>
#include <boost/interprocess/containers/flat_map.hpp>
[section:containers Portable containers in managed memory segments]

* [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.
It's implemented using a vector-like contiguous storage, so
it has fast c string conversion and can be used with the
[link interprocess.streams.vectorstream vectorstream] iostream formatting classes.
To use it include:
[important Since [*Boost.Container] was created from [*Boost.Interprocess] in 2011, this library has mantained
several <boost/interprocess/containers/.hpp> headers for backwards compatibility. Those headers are now deprecated
and will be removed in a future Boost version. Users should directly use [*Boost.Container] headers]

[c++]
Due to the described partial support from Standard Library implementations [*Boost.Interprocess]
highly recommends using [*Boost.Container] containers, which are guaranteed to work with [*Boost.Interprocess]

#include <boost/interprocess/containers/string.hpp>
The following [*Boost.Container] containers are compatible with [*Boost.Interprocess]:

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).
* `deque`
* `devector`
* `flat_map/multimap`
* `flat_set/multiset`
* `list`
* `map/multimap`
* `set/multiset`
* `slist`
* `small_vector`
* `stable_vector`
* `static_vector`
* `string`
* `vector`

To place any of these containers in managed memory segments, we must
define the allocator template parameter with a [*Boost.Interprocess] allocator
Expand Down Expand Up @@ -5187,27 +5145,6 @@ Let's see an example:

[endsect]

[section:containers_and_move Move semantics in Interprocess containers]

[*Boost.Interprocess] containers support move semantics, which means that the contents
of a container can be moved from a container to another one, without any copying. The
contents of the source container are transferred to the target container and the source
container is left in default-constructed state.

When using containers of containers, we can also use move-semantics to insert
objects in the container, avoiding unnecessary copies.


To transfer the contents of a container to another one, use
`boost::move()` function, as shown in the example. For more details
about functions supporting move-semantics, see the reference section of
Boost.Interprocess containers:

[import ../example/doc_move_containers.cpp]
[doc_move_containers]

[endsect]

[section:containers_of_containers Containers of containers]

When creating containers of containers, each container needs an allocator.
Expand Down Expand Up @@ -5265,8 +5202,6 @@ with raw pointers.

[endsect]

[endsect]

[section:memory_algorithms Memory allocation algorithms]

[section:simple_seq_fit simple_seq_fit: A simple shared memory management algorithm]
Expand Down Expand Up @@ -6830,10 +6765,21 @@ thank them:

[section:release_notes Release Notes]

[section:release_notes_boost_1_87_00 Boost 1.87 Release]

* Deprecated `<boost/interprocess/containers/*.hpp>` headers. They were the original source of [*Boost.Container] in 2011, but no longer maintained.
As a long transition, Boost.Interprocess has maintained those headers for compatibility. They will be removed in a future Boost release.

* Fixed bugs:
* [@https://github.com/boostorg/interprocess/issues/210 GitHub #210 (['"Bug in boost::interprocess::ipcdetail::sync_handles::obtain_mutex"])].
* [@https://github.com/boostorg/interprocess/issues/192 GitHub #192 (['"managed_windows_shared_memory crash on destruction"])].

[endsect]

[section:release_notes_boost_1_86_00 Boost 1.86 Release]

* Fixed bugs:
* [@https://github.com/boostorg/interprocess/pull/191 GitHub #191 (['"vectorstream: support file sizes larger than INT_MAX "])].
* [@https://github.com/boostorg/interprocess/pull/191 GitHub #191 (['"vectorstream: support file sizes larger than INT_MAX"])].
* [@https://github.com/boostorg/interprocess/pull/198 GitHub #198 (['"Minor fixes for documentation of offset_ptr"])].
* [@https://github.com/boostorg/interprocess/pull/202 GitHub #202 (['"Allow to map message_queue in anonymous memory"])].
* [@https://github.com/boostorg/interprocess/pull/207 GitHub #207 (['"cmake: link system libraries"])].
Expand Down
13 changes: 8 additions & 5 deletions example/comp_doc_anonymous_conditionA.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
#include <iostream>
#include <cstdio>
#include "doc_anonymous_condition_shared_data.hpp"
//<-
#include "../test/get_process_id_name.hpp"
//->

using namespace boost::interprocess;

Expand All @@ -24,18 +27,18 @@ int main ()
//Erase previous shared memory and schedule erasure on exit
struct shm_remove
{
shm_remove() { shared_memory_object::remove("MySharedMemory"); }
~shm_remove(){ shared_memory_object::remove("MySharedMemory"); }
shm_remove() { shared_memory_object::remove(test::get_process_id_name()); }
~shm_remove(){ shared_memory_object::remove(test::get_process_id_name()); }
} remover;
//<-
(void)remover;
//->

//Create a shared memory object.
shared_memory_object shm
(create_only //only create
,"MySharedMemory" //name
,read_write //read-write mode
(create_only //only create
, test::get_process_id_name() //name
, read_write //read-write mode
);
BOOST_INTERPROCESS_TRY{
//Set size
Expand Down
5 changes: 4 additions & 1 deletion example/comp_doc_anonymous_conditionB.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
#include <iostream>
#include <cstring>
#include "doc_anonymous_condition_shared_data.hpp"
//<-
#include "../test/get_process_id_name.hpp"
//->

using namespace boost::interprocess;

Expand All @@ -23,7 +26,7 @@ int main ()
//Create a shared memory object.
shared_memory_object shm
(open_only //only create
,"MySharedMemory" //name
, test::get_process_id_name() //name
,read_write //read-write mode
);

Expand Down
13 changes: 8 additions & 5 deletions example/comp_doc_anonymous_mutexA.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
#include "doc_anonymous_mutex_shared_data.hpp"
#include <iostream>
#include <cstdio>
//<-
#include "../test/get_process_id_name.hpp"
//->

using namespace boost::interprocess;

Expand All @@ -24,18 +27,18 @@ int main ()
//Remove shared memory on construction and destruction
struct shm_remove
{
shm_remove() { shared_memory_object::remove("MySharedMemory"); }
~shm_remove(){ shared_memory_object::remove("MySharedMemory"); }
shm_remove() { shared_memory_object::remove(test::get_process_id_name()); }
~shm_remove(){ shared_memory_object::remove(test::get_process_id_name()); }
} remover;
//<-
(void)remover;
//->

//Create a shared memory object.
shared_memory_object shm
(create_only //only create
,"MySharedMemory" //name
,read_write //read-write mode
(create_only //only create
, test::get_process_id_name() //name
, read_write //read-write mode
);

//Set size
Expand Down
Loading

0 comments on commit 18b4126

Please sign in to comment.