MChecksum Library

Note

Mercury users should generally not have to directly use the MChecksum library as checksumming may be done within Mercury for small messages. For large payloads, however, if checksums are desired, users should then be responsible for calling MChecksum routines on the buffers.

Mchecksum is a library created in the context of Mercury for checksumming RPC headers as well as RPC function arguments. In Mercury, checksums are not computed for bulk data transfers and it is left upon the user to decide whether to verify transfers or not. Because mchecksum is a separate library, it can be independently used by applications to verify data integrity. Mchecksum provides a simple interface and uses a system of plugins to abstract and provide various hash methods.

Interface

A checksum object is created using the mchecksum_init() function with a valid hash method (see the available plugins section for a list of plugins and the hash_method format).

int mchecksum_init(const char *hash_method, mchecksum_object_t *checksum);

The checksum object is destroyed with a call to mchecksum_destroy().

int mchecksum_destroy(mchecksum_object_t checksum);

The checksum can be reset with mchecksum_reset(), which prevents an extra allocation when the checksum needs to be re-used.

int mchecksum_reset(mchecksum_object_t checksum);

The size of the checksum can be queried using the mchecksum_get_size() call.

size_t mchecksum_get_size(mchecksum_object_t checksum);

The computed checksum hash can be retrieved with a call to mchecksum_get(). If MCHECKSUM_FINALIZE is passed, the checksum is finalized and no more data can be added to that checksum, the only valid calls to follow are either mchecksum_reset() or mchecksum_destroy(). If MCHECKSUM_NOFINALIZE is passed, more data can be later added to this checksum.

int mchecksum_get(mchecksum_object_t checksum, void *buf, size_t size, int finalize);

The checksum is computed on a given piece of data by using the mchecksum_update() call. Note again that incremental update is allowed unless mchecksum_get() has been called with the MCHECKSUM_FINALIZE parameter.

int mchecksum_update(mchecksum_object_t checksum, const void *data, size_t size);

Available Plugins

Below is a list of the currently available plugins as well as corresponding initialization strings that must be passed to the mchecksum_init() call. Note that CRC32 and ADLER32 are available through the ZLIB library and CRC32C is available with and without SSE4.2 optimization. When using the ISA-L library, improved performance can be achieved for CRC16, CRC32C and CRC64 by using the PCLMULQDQ CPU instruction (when supported).

Plugin	Initialization Format
CRC16	crc16
CRC32	crc32
CRC32C	crc32c
CRC64	crc64
ADLER32	adler32

Performance Comparison

Below is a performance comparison of the hash methods defined through mchecksum, using non-SSE/SSE/ISA-L (v2.24.0) versions.

Example

The example below is given for illustration.

#include <mchecksum.h>
#include <stdlib.h>

#define BUF_SIZE 256

int
main(int argc, char *argv[])
{
    unsigned char buf[BUF_SIZE];
    unsigned int i;
    mchecksum_object_t checksum;
    void *hash = NULL;
    size_t hash_size;
    int ret = EXIT_SUCCESS;

    /* Initialize buf */
    for (i = 0; i < BUF_SIZE; i++)
        buf[i] = i;

    /* Initialize checksum */
    mchecksum_init("crc32c", &checksum);

    /* Update checksum */
    mchecksum_update(checksum, buf, BUF_SIZE);

    /* Get size of checksum and allocate buffer to store checksum */
    hash_size = mchecksum_get_size(checksum);
    hash = malloc(hash_size);

    /* Get checksum and finalize it */
    mchecksum_get(checksum, hash, hash_size, MCHECKSUM_FINALIZE);

    /* Use checksum */
    ...

    /* Destroy checksums and free hash buffers */
    mchecksum_destroy(checksum);
    free(hash);

    return ret;
}