bdlde_crc32c

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

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);