interprocess.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 1,625 行 · 第 1/5 页

[/
 / Copyright (c) 2007 Ion Gaztanaga
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[library Boost.Interprocess
    [quickbook 1.3]
    [authors [Gaztañaga, Ion]]
    [copyright 2005- 2007 Ion Gaztañaga]
    [id interprocess]
    [dirname interprocess]
    [purpose Interprocess communication utilities]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
]

[section:intro Introduction]

[*Boost.Interprocess] simplifies the use of common interprocess communication
and synchronization mechanisms and offers a wide range of them:

* Shared memory.
* Memory-mapped files.
* Semaphores, mutexes, condition variables and upgradable mutex types to place
  them in shared memory and memory mapped files.
* Named versions of those synchronization objects, similar to UNIX/Windows
  sem_open/CreateSemaphore API.
* File locking.
* Relative pointers.
* Message queues.

[*Boost.Interprocess] also offers higher-level interprocess mechanisms to allocate
dynamically portions of a shared memory or a memory mapped file (in general,
to allocate portions of a fixed size memory segment). Using these mechanisms,
[*Boost.Interprocess] offers useful tools to construct C++ objects, including 
STL-like containers, in shared memory and memory mapped files:

* Dynamic creation of anonymous and named objects in a shared memory or memory
  mapped file.
* STL-like containers compatible with shared memory/memory-mapped files.
* STL-like allocators ready for shared memory/memory-mapped files implementing
  several memory allocation patterns (like pooling).

[section:introduction_building_interprocess Building Boost.Interprocess]

There is no need to compile [*Boost.Interprocess], since it's
a header only library. Just include your Boost header directory in your
compiler include path.

[*Boost.Interprocess] depends on
[@http://www.boost.org/libs/date_time/ [*Boost.DateTime]], which needs
separate compilation. However, the subset used by [*Boost.Interprocess] does
not need any separate compilation so the user can define `BOOST_DATE_TIME_NO_LIB`
to avoid Boost from trying to automatically link the [*Boost.DateTime].

In POSIX systems, [*Boost.Interprocess] uses pthread system calls to implement
classes like mutexes, condition variables, etc... In some operating systems,
these POSIX calls are implemented in separate libraries that are not automatically
linked by the compiler. For example, in some Linux systems POSIX pthread functions
are implemented in `librt.a` library, so you might need to add that library
when linking an executable or shared library that uses [*Boost.Interprocess].
If you obtain linking errors related to those pthread functions, please revise
your system's documentation to know which library implements them.

[endsect]

[section:tested_compilers Tested compilers]

[*Boost.Interprocess] has been tested in the following compilers/platforms:

*  Visual 7.1 Windows XP
*  Visual 8.0 Windows XP
*  GCC 4.1.1 MinGW
*  GCC 3.4.4 Cygwin
*  Intel 9.1 Windows XP
*  GCC 4.1.2 Linux
*  GCC 3.4.3 Solaris 11
*  GCC 4.0 MacOs 10.4.1

[endsect]

[endsect]

[section:quick_guide Quick Guide for the Impatient]

[section:qg_memory_pool Using shared memory as a pool of unnamed memory blocks]

You can just allocate a portion of a shared memory segment, copy the 
message to that buffer, send the offset of that portion of shared 
memory to another process, and you are done. Let's see the example:

[import ../example/doc_ipc_messageA.cpp]
[doc_ipc_messageA]

In receiver process one just could write the following lines:

[import ../example/doc_ipc_messageB.cpp]
[doc_ipc_messageB]

[endsect]

[section:qg_named_interprocess Creating named shared memory objects]

You want to create objects in a shared memory segment, giving a string name to them so that 
any other process can find, use and delete them from the segment when the objects are not 
needed anymore. Just write in one process:

[import ../example/doc_named_allocA.cpp]
[doc_named_allocA]

In other process execute the following:

[import ../example/doc_named_allocB.cpp]
[doc_named_allocB]

[endsect]

[section:qg_offset_ptr Using an offset smart pointer for shared memory]

[*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.  
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 
different base addresses in different processes.

This allows placing objects with pointer members 
in shared memory. For example, if we want to create 
a linked list in shared memory:

[import ../example/doc_offset_ptr.cpp]
[doc_offset_ptr]

To help with basic data structures, [*Boost.Interprocess] offers containers like vector,
list, map, so you can avoid these manual data structures just like with standard containers.

[endsect]

[section:qg_interprocess_container Creating vectors in shared memory]

[*Boost.Interprocess] allows creating complex objects in shared memory and memory
mapped files. For example, we can construct STL-like containers in shared memory.
To do this, we just need to create a special (managed) shared memory segment,
declare a [*Boost.Interprocess] allocator and construct the vector in shared memory
just if it was any other object. Just execute this first process:

[import ../example/doc_contA.cpp]
[doc_contA]

After this process is executed we can search the constructed vector and use it with
STL algorithms:

[import ../example/doc_contB.cpp]
[doc_contB]

[endsect]

[section:qg_interprocess_map Creating maps in shared memory]

Just like a vector, [*Boost.Interprocess] allows creating maps in
shared memory and memory mapped files. The only difference is that
like standard associative containers, [*Boost.Interprocess]'s map needs
also the comparison functor when an allocator is passed in the constructor:

[import ../example/doc_map.cpp]
[doc_map]

For a more advanced example including containers of containers, see the section
[link interprocess.allocators_containers.containers_explained.containers_of_containers Containers of containers].

[endsect]

[endsect]

[section:some_basic_explanations Some basic explanations]

[section:processes_and_threads Processes And Threads]

[*Boost.Interprocess] does not work only with processes but also with threads.
[*Boost.Interprocess] synchronization mechanisms can synchronize threads 
from different processes, but also threads from the same process.

[endsect]

[section:sharing_information Sharing information between processes]

In the traditional programming model an operating system has multiple processes
running and each process has its own address space. To share information between
processes we have several alternatives:

* Two processes share information using a [*file]. To access to the data, each
  process uses the usual file read/write mechanisms. When updating/reading
  a file shared between processes, we need some sort of synchronization, to
  protect readers from writers.

* Two processes share information that resides in the [*kernel] of the operating
  system. This is the case, for example, of traditional message queues. The
  synchronization is guaranteed by the operating system kernel.

* Two processes can share a [*memory] region. This is the case of classical
  shared memory or memory mapped files. Once the processes set up the
  memory region, the processes can read/write the data like any
  other memory segment without calling the operating system's kernel. This
  also requires some kind of manual synchronization between processes.

[endsect]

[section:persistence Persistence Of Interprocess Mechanisms]

One of the biggest issues with interprocess communication mechanisms is the lifetime
of the interprocess communication mechanism.
It's important to know when an interprocess communication mechanism disappears from the
system. In [*Boost.Interprocess], we can have 3 types of persistence:

* [*Process-persistence]: The mechanism lasts until all the processes that have
  opened the mechanism close it, exit or crash.

* [*Kernel-persistence]: The mechanism exists until the kernel of the operating
  system reboots or the mechanism is explicitly deleted.

* [*Filesystem-persistence]: The mechanism exists until the mechanism is explicitly
  deleted.

Some native POSIX and Windows IPC mechanisms have different persistence so it's
difficult to achieve portability between Windows and POSIX native mechanisms. 
[*Boost.Interprocess] classes have the following persistence:

[table Boost.Interprocess Persistence Table
   [[Mechanism] [Persistence]]
   [[Shared memory]                 [Kernel or Filesystem]]
   [[Memory mapped file]            [Filesystem]]
   [[Process-shared mutex types]    [Process]]
   [[Process-shared semaphore]      [Process]]
   [[Process-shared condition]      [Process]]
   [[File lock]                     [Process]]
   [[Message queue]                 [Kernel or Filesystem]]
   [[Named mutex]                   [Kernel or Filesystem]]
   [[Named semaphore]               [Kernel or Filesystem]]
   [[Named condition]               [Kernel or Filesystem]]
]

As you can see, [*Boost.Interprocess] defines some mechanisms with "Kernel or Filesystem"
persistence. This is because POSIX allows this possibility to native interprocess
communication implementations. One could, for example, implement
shared memory using memory mapped files and obtain filesystem persistence (for example,
there is no proper known way to emulate kernel persistence with a user library
for Windows shared memory using native shared memory,
or process persistence for POSIX shared memory, so the only portable way is to 
define "Kernel or Filesystem" persistence).

[endsect]

[section:names Names Of Interprocess Mechanisms]

Some interprocess mechanisms are anonymous objects created in shared memory or
memory-mapped files but other interprocess mechanisms need a name or identifier
so that two unrelated processes can use the same interprocess mechanism object.
Examples of this are shared memory, named mutexes and named semaphores (for example,
native windows CreateMutex/CreateSemaphore API family).

The name used to identify an interprocess mechanism is not portable, even between
UNIX systems. For this reason, [*Boost.Interprocess] limits this name to a C++ variable
identifier or keyword:

*Starts with a letter, lowercase or uppercase, such as a letter from a to z or from
 A to Z. Examples: ['Sharedmemory, sharedmemory, sHaReDmEmOrY...]
*Can include letters, underscore, or digits. Examples: ['shm1, shm2and3, ShM3plus4...]

[endsect]


[section:constructors_destructors_and_resource_lifetime
   Constructors, destructors and lifetime of Interprocess named resources]

Named [*Boost.Interprocess] resources (shared memory, memory mapped files,
named mutexes/conditions/semaphores) have kernel or filesystem persistency.
This means that even if all processes that have opened those resources
end, the resource will still be accessible to be opened again and the resource
can only be destructed via an explicit to their static member `remove` function.
This behavior can be easily understood, since it's the same mechanism used
by functions controlling file opening/creation/erasure:

[table Boost.Interprocess-Filesystem Analogy
   [[Named Interprocess resource] [Corresponding std file]  [Corresponding POSIX operation]]
   [[Constructor]                 [std::fstream constructor][open]]
   [[Destructor]                  [std::fstream destructor] [close]]
   [[Member `remove`]             [None. `std::remove`]     [unlink]]
]

Now the correspondence between POSIX and Boost.Interprocess
regarding shared memory and named semaphores:

[table Boost.Interprocess-POSIX shared memory
   [[`shared_memory_object` operation] [POSIX operation]]
   [[Constructor]                      [shm_open]]
   [[Destructor]                       [close]]
   [[Member `remove`]                  [shm_unlink]]
]

[table Boost.Interprocess-POSIX named semaphore
   [[`named_semaphore` operation]      [POSIX operation]]
   [[Constructor]                      [sem_open]]
   [[Destructor]                       [close]]
   [[Member `remove`]                  [sem_unlink]]
]

The most important property is that [*destructors of named resources
don't remove the resource from the system], they only liberate resources
allocated by the system for use by the process for the named resource.
[*To remove the resource from the system the programmer must use
`remove`].

[endsect]

[endsect]

[section:sharedmemorybetweenprocesses Sharing memory between processes]

[section:sharedmemory Shared memory]