From 5407a099d3e80370c5fa67358582966a7b035f11 Mon Sep 17 00:00:00 2001 From: Beman Date: Tue, 16 Dec 2014 11:45:22 -0500 Subject: [PATCH] Add use cases --- doc/index.html | 67 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 11 deletions(-) diff --git a/doc/index.html b/doc/index.html index 1c520f1..4a25bd1 100644 --- a/doc/index.html +++ b/doc/index.html @@ -74,9 +74,10 @@ floating point numbers, and user-defined types.

  • Data portability. The Endian library supports binary data exchange, via either external media or network transmission, regardless of platform endianness.
     
    • -
  • Program portability. POSIX/BSD based, POSIX/non-BSD based, and - Windows based operating systems traditionally supply libraries with - non-portable functions to perform endian conversion. The Endian library is +
  • Program portability. POSIX-based and + Windows-based operating systems traditionally supply libraries with + non-portable functions to perform endian conversion. There are at least four + non-compatible sets of functions in common use. The Endian library is portable across all C++ platforms.
     
    • @@ -168,15 +169,17 @@ integers. The types may be aligned.

    Choosing between endian conversion functions, endian buffer types, and endian arithmetic types

    -

    Which approach to endianness is best depends on the interaction between -approach characteristics and -application needs.

    +

    The best approach to endianness depends on interaction between +the approach characteristics and +the application needs.

    + +

    Approach characteristics

    The characteristics that differentiate the approaches are the endianness invariants, conversion explicitness, arithmetic operations, sizes available, and alignment requirements.

    -

    Endianness invariants

    +

    Endianness invariants

    @@ -194,7 +197,7 @@ That makes these types easy to use and programs easy to maintain.

    -

    Conversion explicitness

    +

    Conversion explicitness

    @@ -208,7 +211,7 @@ to hoist conversions out of inner loops can bring a performance penalty.

    -

    Arithmetic operations

    +

    Arithmetic operations

    @@ -225,7 +228,7 @@ are very easy to use if lots of arithmetic is involved.

    -

    Sizes available

    +

    Sizes available

    @@ -238,7 +241,7 @@ factor, using sizes tailored to application needs can be useful.

    -

    Alignments available

    +

    Alignments available

    @@ -267,6 +270,48 @@ needed they are often very useful and workarounds are painful. For example,

    +

    Use cases

    + +

    Program portability use case

    + +

    An existing large codebase runs on little-endian Linux systems. It already +deals with endianness via +Linux provided +functions. Because of a business merger, the codebase has to be quickly +modified for Windows and possibly other operating systems, while still +supporting Linux. The codebase is reliable and the programmers are all +well-aware of endian issues.

    + +

    These factors all argue for an endian conversion +approach that just mechanically changes the calls to htobe32, +etc. to boost::endian::native_to_big, etc. and replaces <endian.h> +with <boost/endian/conversion.hpp>.

    + +

    Reliability and arithmetic-speed use case

    + +

    A new, complex, multi-threaded application is to be developed that must run +on little endian machines, but do big endian network I/O. The developers believe +computational speed for endian variable is critical but have seen numerous bugs +result from inability to reason about endian conversion state. They are also +worried that future maintenance changes could inadvertently introduce a lot of +slow conversions if full-blown endian arithmetic types are used.

    + +

    The endian buffers approach is made-to-order for +this use case.

    + +

    Reliability and ease-of-use use case

    + +

    A new, complex, multi-threaded application is to be developed that must run +on little endian machines, but do big endian network I/O. The developers believe +computational speed for endian variables is not critical but have seen +numerous bugs result from inability to reason about endian conversion state. +They are also concerned about ease-of-use both during development and long-term +maintenance.

    + +

    Removing concern about conversion speed and adding concern about ease-of-use +tips the balance strongly in favor the endian +arithmetic approach.

    +

    Built-in support for Intrinsics

    Supply compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics. The library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release