<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Direct iostream formatting: vectorstream and bufferstream</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../interprocess.html" title="Chapter 9. Boost.Interprocess">
<link rel="prev" href="allocators_containers.html" title="Allocators, containers and memory allocation algorithms">
<link rel="next" href="interprocess_smart_ptr.html" title="Ownership smart pointers">
</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="allocators_containers.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="interprocess_smart_ptr.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.streams"></a><a class="link" href="streams.html" title="Direct iostream formatting: vectorstream and bufferstream"> Direct iostream formatting: vectorstream
and bufferstream</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="streams.html#interprocess.streams.vectorstream"> Formatting directly
in your character vector: vectorstream</a></span></dt>
<dt><span class="section"><a href="streams.html#interprocess.streams.bufferstream"> Formatting directly
in your character buffer: bufferstream</a></span></dt>
</dl></div>
<p>
Shared memory, memory-mapped files and all <span class="bold"><strong>Boost.Interprocess</strong></span>
mechanisms are focused on efficiency. The reason why shared memory is used
is that it's the fastest IPC mechanism available. When passing text-oriented
messages through shared memory, there is need to format the message. Obviously
C++ offers the iostream framework for that work.
</p>
<p>
Some programmers appreciate the iostream safety and design for memory formatting
but feel that the stringstream family is far from efficient not when formatting,
but when obtaining formatted data to a string, or when setting the string from
which the stream will extract data. An example:
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">//Some formatting elements
</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">my_text</span> <span class="special">=</span> <span class="string">"..."</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">number</span><span class="special">;</span>
<span class="comment">//Data reader
</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">istringstream</span> <span class="identifier">input_processor</span><span class="special">;</span>
<span class="comment">//This makes a copy of the string. If not using a
</span><span class="comment">//reference counted string, this is a serious overhead.
</span><span class="identifier">input_processor</span><span class="special">.</span><span class="identifier">str</span><span class="special">(</span><span class="identifier">my_text</span><span class="special">);</span>
<span class="comment">//Extract data
</span><span class="keyword">while</span><span class="special">(/*...*/){</span>
<span class="identifier">input_processor</span> <span class="special">>></span> <span class="identifier">number</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//Data writer
</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">output_processor</span><span class="special">;</span>
<span class="comment">//Write data
</span><span class="keyword">while</span><span class="special">(/*...*/){</span>
<span class="identifier">output_processor</span> <span class="special"><<</span> <span class="identifier">number</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//This returns a temporary string. Even with return-value
</span><span class="comment">//optimization this is expensive.
</span><span class="identifier">my_text</span> <span class="special">=</span> <span class="identifier">input_processor</span><span class="special">.</span><span class="identifier">str</span><span class="special">();</span>
</pre>
<p>
The problem is even worse if the string is a shared-memory string, because
to extract data, we must copy the data first from shared-memory to a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
and then to a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>. To encode data in a shared
memory string we should copy data from a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>
to a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> and then to the shared-memory string.
</p>
<p>
Because of this overhead, <span class="bold"><strong>Boost.Interprocess</strong></span>
offers a way to format memory-strings (in shared memory, memory mapped files
or any other memory segment) that can avoid all unneeded string copy and memory
allocation/deallocations, while using all iostream facilities. <span class="bold"><strong>Boost.Interprocess</strong></span>
<span class="bold"><strong>vectorstream</strong></span> and <span class="bold"><strong>bufferstream</strong></span>
implement vector-based and fixed-size buffer based storage support for iostreams
and all the formatting/locale hard work is done by standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_streambuf</span><span class="special"><></span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_iostream</span><span class="special"><></span></code> classes.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="interprocess.streams.vectorstream"></a><a class="link" href="streams.html#interprocess.streams.vectorstream" title="Formatting directly in your character vector: vectorstream"> Formatting directly
in your character vector: vectorstream</a>
</h3></div></div></div>
<p>
The <span class="bold"><strong>vectorstream</strong></span> class family (<span class="bold"><strong>basic_vectorbuf</strong></span>, <span class="bold"><strong>basic_ivectorstream</strong></span>
,<span class="bold"><strong>basic_ovectorstream</strong></span> and <span class="bold"><strong>basic_vectorstream</strong></span>)
is an efficient way to obtain formatted reading/writing directly in a character
vector. This way, if a shared-memory vector is used, data is extracted/written
from/to the shared-memory vector, without additional copy/allocation. We
can see the declaration of basic_vectorstream here:
</p>
<pre class="programlisting"><span class="comment">//!A basic_iostream class that holds a character vector specified by CharVector
</span><span class="comment">//!template parameter as its formatting buffer. The vector must have
</span><span class="comment">//!contiguous storage, like std::vector, boost::interprocess::vector or
</span><span class="comment">//!boost::interprocess::basic_string
</span><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">CharVector</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CharTraits</span> <span class="special">=</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">char_traits</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">CharVector</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">></span> <span class="special">></span>
<span class="keyword">class</span> <span class="identifier">basic_vectorstream</span>
<span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_iostream</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">CharVector</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">></span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">CharVector</span> <span class="identifier">vector_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span>
<span class="special"><</span><span class="keyword">typename</span> <span class="identifier">CharVector</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">char_type</span> <span class="identifier">char_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">int_type</span> <span class="identifier">int_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">pos_type</span> <span class="identifier">pos_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">off_type</span> <span class="identifier">off_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">traits_type</span> <span class="identifier">traits_type</span><span class="special">;</span>
<span class="comment">//!Constructor. Throws if vector_type default constructor throws.
</span> <span class="identifier">basic_vectorstream</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">openmode</span> <span class="identifier">mode</span>
<span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">in</span> <span class="special">|</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">out</span><span class="special">);</span>
<span class="comment">//!Constructor. Throws if vector_type(const Parameter &param) throws.
</span> <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Parameter</span><span class="special">></span>
<span class="identifier">basic_vectorstream</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Parameter</span> <span class="special">&</span><span class="identifier">param</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">openmode</span> <span class="identifier">mode</span>
<span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">in</span> <span class="special">|</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">out</span><span class="special">);</span>
<span class="special">~</span><span class="identifier">basic_vectorstream</span><span class="special">(){}</span>
<span class="comment">//!Returns the address of the stored stream buffer.
</span> <span class="identifier">basic_vectorbuf</span><span class="special"><</span><span class="identifier">CharVector</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>*</span> <span class="identifier">rdbuf</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="comment">//!Swaps the underlying vector with the passed vector.
</span> <span class="comment">//!This function resets the position in the stream.
</span> <span class="comment">//!Does not throw.
</span> <span class="keyword">void</span> <span class="identifier">swap_vector</span><span class="special">(</span><span class="identifier">vector_type</span> <span class="special">&</span><span class="identifier">vect</span><span class="special">);</span>
<span class="comment">//!Returns a const reference to the internal vector.
</span> <span class="comment">//!Does not throw.
</span> <span class="keyword">const</span> <span class="identifier">vector_type</span> <span class="special">&</span><span class="identifier">vector</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="comment">//!Preallocates memory from the internal vector.
</span> <span class="comment">//!Resets the stream to the first position.
</span> <span class="comment">//!Throws if the internals vector's memory allocation throws.
</span> <span class="keyword">void</span> <span class="identifier">reserve</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">vector_type</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size</span><span class="special">);</span>
<span class="special">};</span>
</pre>
<p>
The vector type is templatized, so that we can use any type of vector: <span class="bold"><strong>std::vector</strong></span>, <code class="computeroutput">boost::interprocess::vector</code>...
But the storage must be <span class="bold"><strong>contiguous</strong></span>, we can't
use a deque. We can even use <span class="bold"><strong>boost::interprocess::basic_string</strong></span>,
since it has a vector interface and it has contiguous storage. <span class="bold"><strong>We can't use std::string</strong></span>, because although some std::string
implementation are vector-based, others can have optimizations and reference-counted
implementations.
</p>
<p>
The user can obtain a const reference to the internal vector using <code class="computeroutput"><span class="identifier">vector_type</span> <span class="identifier">vector</span><span class="special">()</span> <span class="keyword">const</span></code> function
and he also can swap the internal vector with an external one calling <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">swap_vector</span><span class="special">(</span><span class="identifier">vector_type</span>
<span class="special">&</span><span class="identifier">vect</span><span class="special">)</span></code>. The swap function resets the stream position.
This functions allow efficient methods to obtain the formatted data avoiding
all allocations and data copies.
</p>
<p>
Let's see an example to see how to use vectorstream:
</p>
<p>
</p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">containers</span><span class="special">/</span><span class="identifier">vector</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">containers</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">allocators</span><span class="special">/</span><span class="identifier">allocator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">streams</span><span class="special">/</span><span class="identifier">vectorstream</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iterator</span><span class="special">></span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">segment_manager</span><span class="special">></span>
<span class="identifier">IntAllocator</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">allocator</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">segment_manager</span><span class="special">></span>
<span class="identifier">CharAllocator</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">IntAllocator</span><span class="special">></span> <span class="identifier">MyVector</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_string</span>
<span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">char_traits</span><span class="special"><</span><span class="keyword">char</span><span class="special">>,</span> <span class="identifier">CharAllocator</span><span class="special">></span> <span class="identifier">MyString</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_vectorstream</span><span class="special"><</span><span class="identifier">MyString</span><span class="special">></span> <span class="identifier">MyVectorStream</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span>
<span class="special">{</span>
<span class="comment">//Remove shared memory on construction and destruction
</span> <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
<span class="special">{</span>
<span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
<span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
<span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
<span class="identifier">managed_shared_memory</span> <span class="identifier">segment</span><span class="special">(</span>
<span class="identifier">create_only</span><span class="special">,</span>
<span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="comment">//segment name
</span> <span class="number">65536</span><span class="special">);</span> <span class="comment">//segment size in bytes
</span>
<span class="comment">//Construct shared memory vector
</span> <span class="identifier">MyVector</span> <span class="special">*</span><span class="identifier">myvector</span> <span class="special">=</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special"><</span><span class="identifier">MyVector</span><span class="special">>(</span><span class="string">"MyVector"</span><span class="special">)</span>
<span class="special">(</span><span class="identifier">IntAllocator</span><span class="special">(</span><span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">()));</span>
<span class="comment">//Fill vector
</span> <span class="identifier">myvector</span><span class="special">-></span><span class="identifier">reserve</span><span class="special">(</span><span class="number">100</span><span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
<span class="identifier">myvector</span><span class="special">-></span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span>
<span class="special">}</span>
<span class="comment">//Create the vectorstream. To create the internal shared memory
</span> <span class="comment">//basic_string we need to pass the shared memory allocator as
</span> <span class="comment">//a constructor argument
</span> <span class="identifier">MyVectorStream</span> <span class="identifier">myvectorstream</span><span class="special">(</span><span class="identifier">CharAllocator</span><span class="special">(</span><span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">()));</span>
<span class="comment">//Reserve the internal string
</span> <span class="identifier">myvectorstream</span><span class="special">.</span><span class="identifier">reserve</span><span class="special">(</span><span class="number">100</span><span class="special">*</span><span class="number">5</span><span class="special">);</span>
<span class="comment">//Write all vector elements as text in the internal string
</span> <span class="comment">//Data will be directly written in shared memory, because
</span> <span class="comment">//internal string's allocator is a shared memory allocator
</span> <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">max</span> <span class="special">=</span> <span class="identifier">myvector</span><span class="special">-></span><span class="identifier">size</span><span class="special">();</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">max</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
<span class="identifier">myvectorstream</span> <span class="special"><<</span> <span class="special">(*</span><span class="identifier">myvector</span><span class="special">)[</span><span class="identifier">i</span><span class="special">]</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//Auxiliary vector to compare original data
</span> <span class="identifier">MyVector</span> <span class="special">*</span><span class="identifier">myvector2</span> <span class="special">=</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special"><</span><span class="identifier">MyVector</span><span class="special">>(</span><span class="string">"MyVector2"</span><span class="special">)</span>
<span class="special">(</span><span class="identifier">IntAllocator</span><span class="special">(</span><span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">()));</span>
<span class="comment">//Avoid reallocations
</span> <span class="identifier">myvector2</span><span class="special">-></span><span class="identifier">reserve</span><span class="special">(</span><span class="number">100</span><span class="special">);</span>
<span class="comment">//Extract all values from the internal
</span> <span class="comment">//string directly to a shared memory vector.
</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">istream_iterator</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">it</span><span class="special">(</span><span class="identifier">myvectorstream</span><span class="special">),</span> <span class="identifier">itend</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">it</span><span class="special">,</span> <span class="identifier">itend</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(*</span><span class="identifier">myvector2</span><span class="special">));</span>
<span class="comment">//Compare vectors
</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">equal</span><span class="special">(</span><span class="identifier">myvector</span><span class="special">-></span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">myvector</span><span class="special">-></span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">myvector2</span><span class="special">-></span><span class="identifier">begin</span><span class="special">()));</span>
<span class="comment">//Create a copy of the internal string
</span> <span class="identifier">MyString</span> <span class="identifier">stringcopy</span> <span class="special">(</span><span class="identifier">myvectorstream</span><span class="special">.</span><span class="identifier">vector</span><span class="special">());</span>
<span class="comment">//Now we create a new empty shared memory string...
</span> <span class="identifier">MyString</span> <span class="special">*</span><span class="identifier">mystring</span> <span class="special">=</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special"><</span><span class="identifier">MyString</span><span class="special">>(</span><span class="string">"MyString"</span><span class="special">)</span>
<span class="special">(</span><span class="identifier">CharAllocator</span><span class="special">(</span><span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">()));</span>
<span class="comment">//...and we swap vectorstream's internal string
</span> <span class="comment">//with the new one: after this statement mystring
</span> <span class="comment">//will be the owner of the formatted data.
</span> <span class="comment">//No reallocations, no data copies
</span> <span class="identifier">myvectorstream</span><span class="special">.</span><span class="identifier">swap_vector</span><span class="special">(*</span><span class="identifier">mystring</span><span class="special">);</span>
<span class="comment">//Let's compare both strings
</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">stringcopy</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">mystring</span><span class="special">);</span>
<span class="comment">//Done, destroy and delete vectors and string from the segment
</span> <span class="identifier">segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">myvector2</span><span class="special">);</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">myvector</span><span class="special">);</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">mystring</span><span class="special">);</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="interprocess.streams.bufferstream"></a><a class="link" href="streams.html#interprocess.streams.bufferstream" title="Formatting directly in your character buffer: bufferstream"> Formatting directly
in your character buffer: bufferstream</a>
</h3></div></div></div>
<p>
As seen, vectorstream offers an easy and secure way for efficient iostream
formatting, but many times, we have to read or write formatted data from/to
a fixed size character buffer (a static buffer, a c-string, or any other).
Because of the overhead of stringstream, many developers (specially in embedded
systems) choose sprintf family. The <span class="bold"><strong>bufferstream</strong></span>
classes offer iostream interface with direct formatting in a fixed size memory
buffer with protection against buffer overflows. This is the interface:
</p>
<pre class="programlisting"><span class="comment">//!A basic_iostream class that uses a fixed size character buffer
</span><span class="comment">//!as its formatting buffer.
</span><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CharTraits</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">char_traits</span><span class="special"><</span><span class="identifier">CharT</span><span class="special">></span> <span class="special">></span>
<span class="keyword">class</span> <span class="identifier">basic_bufferstream</span>
<span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_iostream</span><span class="special"><</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">></span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span> <span class="comment">// Typedefs
</span> <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span>
<span class="special"><</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">char_type</span> <span class="identifier">char_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">int_type</span> <span class="identifier">int_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">pos_type</span> <span class="identifier">pos_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">off_type</span> <span class="identifier">off_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ios</span><span class="special"><</span><span class="identifier">char_type</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>::</span><span class="identifier">traits_type</span> <span class="identifier">traits_type</span><span class="special">;</span>
<span class="comment">//!Constructor. Does not throw.
</span> <span class="identifier">basic_bufferstream</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">openmode</span> <span class="identifier">mode</span>
<span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">in</span> <span class="special">|</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">out</span><span class="special">);</span>
<span class="comment">//!Constructor. Assigns formatting buffer. Does not throw.
</span> <span class="identifier">basic_bufferstream</span><span class="special">(</span><span class="identifier">CharT</span> <span class="special">*</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">length</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">openmode</span> <span class="identifier">mode</span>
<span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">in</span> <span class="special">|</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">out</span><span class="special">);</span>
<span class="comment">//!Returns the address of the stored stream buffer.
</span> <span class="identifier">basic_bufferbuf</span><span class="special"><</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">CharTraits</span><span class="special">>*</span> <span class="identifier">rdbuf</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="comment">//!Returns the pointer and size of the internal buffer.
</span> <span class="comment">//!Does not throw.
</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">CharT</span> <span class="special">*,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">></span> <span class="identifier">buffer</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="comment">//!Sets the underlying buffer to a new value. Resets
</span> <span class="comment">//!stream position. Does not throw.
</span> <span class="keyword">void</span> <span class="identifier">buffer</span><span class="special">(</span><span class="identifier">CharT</span> <span class="special">*</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">length</span><span class="special">);</span>
<span class="special">};</span>
<span class="comment">//Some typedefs to simplify usage
</span><span class="keyword">typedef</span> <span class="identifier">basic_bufferstream</span><span class="special"><</span><span class="keyword">char</span><span class="special">></span> <span class="identifier">bufferstream</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_bufferstream</span><span class="special"><</span><span class="keyword">wchar_t</span><span class="special">></span> <span class="identifier">wbufferstream</span><span class="special">;</span>
<span class="comment">// ...
</span></pre>
<p>
While reading from a fixed size buffer, <span class="bold"><strong>bufferstream</strong></span>
activates endbit flag if we try to read an address beyond the end of the
buffer. While writing to a fixed size buffer, <span class="bold"><strong>bufferstream</strong></span>
will active the badbit flag if a buffer overflow is going to happen and disallows
writing. This way, the fixed size buffer formatting through <span class="bold"><strong>bufferstream</strong></span>
is secure and efficient, and offers a good alternative to sprintf/sscanf
functions. Let's see an example:
</p>
<p>
</p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">streams</span><span class="special">/</span><span class="identifier">bufferstream</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iterator</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstddef</span><span class="special">></span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span>
<span class="special">{</span>
<span class="comment">//Remove shared memory on construction and destruction
</span> <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
<span class="special">{</span>
<span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
<span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
<span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
<span class="comment">//Create shared memory
</span> <span class="identifier">managed_shared_memory</span> <span class="identifier">segment</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span>
<span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="comment">//segment name
</span> <span class="number">65536</span><span class="special">);</span>
<span class="comment">//Fill data
</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">data</span><span class="special">;</span>
<span class="identifier">data</span><span class="special">.</span><span class="identifier">reserve</span><span class="special">(</span><span class="number">100</span><span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
<span class="identifier">data</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">BufferSize</span> <span class="special">=</span> <span class="number">100</span><span class="special">*</span><span class="number">5</span><span class="special">;</span>
<span class="comment">//Allocate a buffer in shared memory to write data
</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">my_cstring</span> <span class="special">=</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="string">"MyCString"</span><span class="special">)[</span><span class="identifier">BufferSize</span><span class="special">](</span><span class="number">0</span><span class="special">);</span>
<span class="identifier">bufferstream</span> <span class="identifier">mybufstream</span><span class="special">(</span><span class="identifier">my_cstring</span><span class="special">,</span> <span class="identifier">BufferSize</span><span class="special">);</span>
<span class="comment">//Now write data to the buffer
</span> <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
<span class="identifier">mybufstream</span> <span class="special"><<</span> <span class="identifier">data</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//Check there was no overflow attempt
</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">good</span><span class="special">());</span>
<span class="comment">//Extract all values from the shared memory string
</span> <span class="comment">//directly to a vector.
</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">data2</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">istream_iterator</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">it</span><span class="special">(</span><span class="identifier">mybufstream</span><span class="special">),</span> <span class="identifier">itend</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">it</span><span class="special">,</span> <span class="identifier">itend</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">data2</span><span class="special">));</span>
<span class="comment">//This extraction should have ended will fail error since
</span> <span class="comment">//the numbers formatted in the buffer end before the end
</span> <span class="comment">//of the buffer. (Otherwise it would trigger eofbit)
</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">fail</span><span class="special">());</span>
<span class="comment">//Compare data
</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">equal</span><span class="special">(</span><span class="identifier">data</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">data2</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()));</span>
<span class="comment">//Clear errors and rewind
</span> <span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
<span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">seekp</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span><span class="special">::</span><span class="identifier">beg</span><span class="special">);</span>
<span class="comment">//Now write again the data trying to do a buffer overflow
</span> <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">m</span> <span class="special">=</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">size</span><span class="special">()*</span><span class="number">5</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">m</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
<span class="identifier">mybufstream</span> <span class="special"><<</span> <span class="identifier">data</span><span class="special">[</span><span class="identifier">i</span><span class="special">%</span><span class="number">5</span><span class="special">]</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//Now make sure badbit is active
</span> <span class="comment">//which means overflow attempt.
</span> <span class="identifier">assert</span><span class="special">(!</span><span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">good</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">mybufstream</span><span class="special">.</span><span class="identifier">bad</span><span class="special">());</span>
<span class="identifier">segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">my_cstring</span><span class="special">);</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
</p>
<p>
As seen, <span class="bold"><strong>bufferstream</strong></span> offers an efficient
way to format data without any allocation and extra copies. This is very
helpful in embedded systems, or formatting inside time-critical loops, where
stringstream extra copies would be too expensive. Unlike sprintf/sscanf,
it has protection against buffer overflows. As we know, according to the
<span class="bold"><strong>Technical Report on C++ Performance</strong></span>, it's
possible to design efficient iostreams for embedded platforms, so this bufferstream
class comes handy to format data to stack, static or shared memory buffers.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2005 - 2008 Ion Gaztanaga<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="allocators_containers.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="interprocess_smart_ptr.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
