From 4669f1b04bfab6b3c8441597f34a5f62544d476a Mon Sep 17 00:00:00 2001 From: Beman Date: Wed, 31 Dec 2014 09:57:16 -0500 Subject: [PATCH] Add design patterns section --- doc/index.html | 60 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/doc/index.html b/doc/index.html index 0ccac4e..d5a0f74 100644 --- a/doc/index.html +++ b/doc/index.html @@ -186,14 +186,18 @@ integers. The types may be aligned.

Choosing between conversion functions, buffer types, and arithmetic types

-

The best approach to endianness for a particular use case depends on interactions between -the approach characteristics and -the application needs.

+

The best approach to endianness for a particular application depends on the interaction between +the application's needs and the characteristics of each of the three (conversion +functions, buffer types, or arithmetic types) approaches.

-

Recommendation: If you are uncertain, new to endianness, concerned -about security, concerned about reliability, or don't want to invest time making -engineering trade-offs, use the endian arithmetic types. They are safer, easier -to use, and your code will be easier to maintain.

+

Recommendation: If you are new to endianness, uncertain, or don't want to invest +the time to +study +engineering trade-offs, use endian arithmetic types. They are safe, easy +to use, and easy to maintain. Use the + +anticipating need design pattern locally around performance hot spots like lengthy loops, +if needed. 

Characteristics

@@ -292,6 +296,46 @@ needed they are often very useful and workarounds are painful. For example,

+

Design patterns

+ +

Applications often traffic in endian data as records or packets containing +multiple endian data elements. For simplicity, we will just call them records.

+ +

If desired endianness differs from native endianness, a conversion has to be +performed. When should that conversion occur? Three design patterns have +evolved.

+ +

Convert only as needed (i.e. lazy)

+ +

This pattern defers conversion to the point in the code where the data +element is actually used.

+ +

This pattern is appropriate when which endian element is actually used varies +greatly according to record content or other circumstances

+ +

Convert in anticipation of need

+ +

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.

+ +

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.

+ +

This pattern is appropriate when all endian elements in a record are +typically used regardless of record content or other circumstances

+ +

Convert generally only as needed, but locally in anticipation of need

+ +

This pattern in general defers conversion but does +anticipatory conversion for specific local needs.

+ +

This pattern is particularly appropriate when coupled with the endian buffer +or arithmetic types.

+

Use cases

Porting endian unaware codebase

@@ -825,7 +869,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovski,.

Last revised: -17 December, 2014

+31 December, 2014

© Copyright Beman Dawes, 2011, 2013

Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt