feedc0de/boost_endian
1
0
Fork 0
forked from boostorg/endian
Code Pull Requests Activity

Add design patterns section

Browse Source
This commit is contained in:
Beman
2014-12-31 09:57:16 -05:00
parent 25143c6b9a
commit 4669f1b04b
1 changed files with 52 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
doc/index.html
View File

@ -186,14 +186,18 @@ integers. The types may be aligned.</p>
<h2><a name="Choosing">Choosing</a> between conversion functions, buffer types,
and arithmetic types</h2>
<p>The best approach to endianness for a particular use case depends on interactions between
the approach characteristics and
the application needs.</p>
<p>The best approach to endianness for a particular application depends on the interaction between
the application&#39;s needs and the characteristics of each of the three (conversion
functions, buffer types, or arithmetic types) approaches.</p>
<p><b>Recommendation:</b> If you are uncertain, new to endianness, concerned
about security, concerned about reliability, or don&#39;t want to invest time making
engineering trade-offs, use the <a href="arithmetic.html">endian arithmetic types</a>. They are safer, easier
to use, and your code will be easier to maintain.</p>
<p><b>Recommendation:</b> If you are new to endianness, uncertain, or don&#39;t want to invest
the time to
study
engineering trade-offs, use <a href="arithmetic.html">endian arithmetic types</a>. They are safe, easy
to use, and easy to maintain. Use the
<a href="#Anticipating-need"> <i>
anticipating need</i></a> design pattern locally around performance hot spots like lengthy loops,
if needed.&nbsp; </p>
<h3><a name="Characteristics">Characteristics</a></h3>
@ -292,6 +296,46 @@ needed they are often very useful and workarounds are painful. For example,</p>
</blockquote>
<h3><a name="Design-patterns">Design patterns</a></h3>
<p>Applications often traffic in endian data as records or packets containing
multiple endian data elements. For simplicity, we will just call them records.</p>
<p>If desired endianness differs from native endianness, a conversion has to be
performed. When should that conversion occur? Three design patterns have
evolved.</p>
<h4><a name="As-needed">Convert only as needed</a> (i.e. lazy)</h4>
<p>This pattern defers conversion to the point in the code where the data
element is actually used.</p>
<p>This pattern is appropriate when which endian element is actually used varies
greatly according to record content or other circumstances</p>
<h4><a name="Anticipating-need">Convert in anticipation of need</a></h4>
<p>This pattern performs conversion to native endianness in anticipation of use,
such as immediately after reading records. If needed, conversion to the output
endianness is performed after all possible needs have passed, such as just
before writing records.</p>
<p>One implementation of this pattern is to create a proxy record with
endianness converted to native in a read function, and expose only that proxy to
the rest of the implementation. If a write function, if needed, handles the
conversion from native to the desired output endianness.</p>
<p>This pattern is appropriate when all endian elements in a record are
typically used regardless of record content or other circumstances</p>
<h4>Convert generally only as needed, but locally in anticipation of need</h4>
<p>This pattern in general defers conversion but does
anticipatory conversion for specific local needs.</p>
<p>This pattern is particularly appropriate when coupled with the endian buffer
or arithmetic types.</p>
<h3><a name="Use-cases">Use cases</a></h3>
<h4><a name="Porting-endian-unaware-codebase">Porting endian unaware codebase</a></h4>
@ -825,7 +869,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and
Vitaly Budovski,.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->31 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38637" --></p>
<p>© Copyright Beman Dawes, 2011, 2013</p>
<p>Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>