Component bdlde_crc32c [Package bdlde]

Provide utilities to calculate the CRC32-C checksum of a dataset. More...

Namespaces
namespace	bdlde

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Support for Hardware Acceleration
  • Performance
  • Usage
    • Example 1: Computing and updating a checksum

Purpose:

Provide utilities to calculate the CRC32-C checksum of a dataset.

Classes:

bdlde::Crc32c	calculates CRC32-C checksum
bdlde::Crc32c_Impl	calculates CRC32-C checksum with alternative impl.

See also:

Component bdlde_crc32

Description:

This component defines a struct, bdlde::Crc32c that dramatically accelerates (as opposite to the bdlde::Crc32 component) calculation of a CRC32-C checksum (a cyclic redundancy check, comprised of 32 bits, that uses the Castagnoli polynomial), using a hardware-accelerated implementation if supported or a software implementation otherwise. It additionally defines the struct bdlde::Crc32c_Impl to expose alternative implementations that should not be used other than to test and benchmark. Note that a CRC32-C checksum is a strong and fast technique for determining whether or not a message was received without errors. Also note that a CRC-32 checksum does not aid in error correction and is not naively useful in any sort of cryptography application.

Thread Safety:

Thread safe.

Support for Hardware Acceleration:

Hardware-accelerated implementation is enabled at compile time when building on a supported architecture with a compatible compiler. In addition, runtime checks are performed to detect whether the running platform has the required hardware support:

• x86: SSE4.2 instructions are required
• sparc: runtime check is detected by the is_sparc_crc32c_avail system call

Performance:

See the test driver for this component in the .t.cpp to compare performance of the hardware-accelerated and software implementations against various alternative implementations that compute a 32-bit CRC checksum.

Usage:

This section illustrates intended use of this component.

Example 1: Computing and updating a checksum:

The following code illustrates how to calculate and update a CRC32-C checksum for a message over the course of building the full message.

First, prepare a message.

  bsl::string message = "This is a test message.";

Now, generate a checksum for message.

  unsigned int checksum = bdlde::Crc32c::calculate(message.c_str(),
                                                   message.size());

Finally, if we learn that our message has grown by another chunk and we want to compute the checksum of the original message plus the new chunk, let's update the checksum by using it as a starting point.

  // New chunk
  bsl::string newChunk = "This is a chunk appended to original message";
  message += newChunk;

  // Update checksum using previous value as starting point
  checksum = bdlde::Crc32c::calculate(newChunk.c_str(),
                                      newChunk.size(),
                                      checksum);