Support 32-bit MUM

Author: eldruin

.github/workflows/build.yml

@@ -173,6 +173,13 @@ jobs:
           command: test
           args: --target=${{ matrix.TARGET }} --workspace
 
+      - name: Test 32-bit mum
+        if: matrix.rust != '1.36.0' && matrix.TARGET != 'x86_64-unknown-linux-musl' # musl-gcc is not installed
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --target=${{ matrix.TARGET }} --workspace --features comparison/mum32bit
+
       - name: Test MSRV
         if: matrix.rust == '1.36.0' || matrix.TARGET == 'x86_64-unknown-linux-musl'
         uses: actions-rs/cargo@v1
@@ -186,6 +193,12 @@ jobs:
         run: |
           cargo test --target=${{ matrix.TARGET }}
 
+      - name: Test MSRV comparison 32-bit mum
+        if: matrix.rust == '1.36.0' && matrix.TARGET != 'x86_64-unknown-linux-musl' # musl-gcc is not installed
+        working-directory: ./comparison
+        run: |
+          cargo test --target=${{ matrix.TARGET }} --features mum32bit
+
       - name: Build examples
         uses: actions-rs/cargo@v1
         if: contains(matrix.TARGET, 'x86_64')
@@ -224,7 +237,7 @@ jobs:
       - name: Run cargo-tarpaulin
         uses: actions-rs/[email protected]
         with:
-          args: '--workspace --out Lcov -- --test-threads 1'
+          args: '--workspace -- --test-threads 1'
 
       - name: upload to Coveralls
         uses: coverallsapp/github-action@master

.tarpaulin.toml

@@ -0,0 +1,8 @@
+[default_coverage]
+features = ""
+
+[mum32bit_coverage]
+features = "comparison/mum32bit"
+
+[report]
+out = ["Lcov"]

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 - Ported `final3` algorithm version.
+- Enable better performance on 32-bit systems via the `mum32bit` feature.
 - Benchmarks.
 
 ### Changed

Cargo.toml

@@ -28,6 +28,9 @@ metrohash = "1"
 fnv = "1"
 twox-hash = "1"
 
+[features]
+mum32bit = []
+
 [workspace]
 members = ["comparison"]
 

README.md

@@ -17,7 +17,14 @@ used in `no_std` environments) and has no dependencies (except the traits from `
 The generated hashes are equal (see tests) as of the version stated [here][original-version]
 although the speed varies ([PRs are welcome][issue-tracker]).
 
-### Usage
+## Crate features
+
+By default this crate uses 128-bit integer multiplications.
+To restrict that to 64 bits you can enable the feature `mum32bit`. This offers better
+performance on 32-bit architectures.
+Beware that this feature produces different results.
+
+## Usage
 
 This crate provides free functions as well as implementations of the `Hasher`, `Rng` and
 `SeedableRng` traits.

comparison/Cargo.toml

@@ -19,6 +19,9 @@ twox-hash = "1"
 cc = "1"
 cmake = "0.1"
 
+[features]
+mum32bit = ["wyhash/mum32bit"]
+
 [[bench]]
 name = "bench"
 harness = false

comparison/build.rs

@@ -7,4 +7,5 @@ fn main() {
     println!("cargo:rustc-link-search=native={}", dst.display());
     println!("cargo:rustc-link-lib=static=original_v1");
     println!("cargo:rustc-link-lib=static=original_final3");
+    println!("cargo:rustc-link-lib=static=original_final3_32bit_mum");
 }

comparison/original/CMakeLists.txt

@@ -23,5 +23,9 @@ add_library(original_final3
     ${CMAKE_CURRENT_SOURCE_DIR}/lib_final3.c
     ${CMAKE_CURRENT_BINARY_DIR}/wyhash_final3.h)
 
-install(TARGETS original_v1 original_final3 DESTINATION .)
+add_library(original_final3_32bit_mum
+    ${CMAKE_CURRENT_SOURCE_DIR}/lib_final3_32bit_mum.c
+    ${CMAKE_CURRENT_BINARY_DIR}/wyhash_final3.h)
+
+install(TARGETS original_v1 original_final3 original_final3_32bit_mum DESTINATION .)
 

comparison/original/lib_final3_32bit_mum.c

@@ -0,0 +1,11 @@
+#define WYHASH_32BIT_MUM 1
+#include "wyhash_final3.h"
+
+uint64_t c_wyhash_final3_32bit_mum(const void* key, size_t len, uint64_t seed,
+    const uint64_t* secret) {
+    return wyhash(key, len, seed, secret);
+}
+
+uint64_t c_wyrng_final3_32bit_mum(uint64_t *s) {
+    return wyrand(s);
+}

comparison/src/lib.rs

@@ -19,5 +19,14 @@ pub mod ffi {
         ) -> c_ulonglong;
 
         pub fn c_wyrng_final3(seed: *mut c_ulonglong) -> c_ulonglong;
+
+        pub fn c_wyhash_final3_32bit_mum(
+            data: *const c_void,
+            length: c_ulonglong,
+            seed: c_ulonglong,
+            secret: *const c_ulonglong,
+        ) -> c_ulonglong;
+
+        pub fn c_wyrng_final3_32bit_mum(seed: *mut c_ulonglong) -> c_ulonglong;
     }
 }

comparison/tests/back_to_back_hash.rs

@@ -1,4 +1,8 @@
-use comparison::ffi::{c_wyhash_final3, c_wyhash_v1};
+#[cfg(not(feature = "mum32bit"))]
+use comparison::ffi::c_wyhash_final3;
+#[cfg(feature = "mum32bit")]
+use comparison::ffi::c_wyhash_final3_32bit_mum;
+use comparison::ffi::c_wyhash_v1;
 use core::hash::Hasher;
 use libc::{c_ulonglong, c_void};
 use wyhash::{final3, v1};
@@ -31,44 +35,53 @@ mod v1_tests {
     }
 }
 
-mod final3_tests {
-    use super::*;
-
-    #[test]
-    fn function_test() {
-        let secret = final3::make_secret(0);
-        let mut data = [0; 256];
-        for i in 0..data.len() {
-            data[i] = i as u8;
-            let original = unsafe {
-                c_wyhash_final3(
-                    data.as_ptr() as *const c_void,
-                    i as u64,
-                    i as u64,
-                    secret.as_ptr() as *const c_ulonglong,
-                )
-            };
-            assert_eq!(original, final3::wyhash(&data[..i], i as u64, secret));
+macro_rules! final3_tests {
+    ($c_function: ident) => {
+        #[test]
+        fn function_test() {
+            let secret = final3::make_secret(0);
+            let mut data = [0; 256];
+            for i in 0..data.len() {
+                data[i] = i as u8;
+                let original = unsafe {
+                    $c_function(
+                        data.as_ptr() as *const c_void,
+                        i as u64,
+                        i as u64,
+                        secret.as_ptr() as *const c_ulonglong,
+                    )
+                };
+                assert_eq!(original, final3::wyhash(&data[..i], i as u64, secret));
+            }
         }
-    }
 
-    #[test]
-    fn core_hasher() {
-        let secret = final3::make_secret(0);
-        let mut data = [0; 256];
-        for i in 0..data.len() {
-            data[i] = i as u8;
-            let mut hasher = final3::WyHash::new(i as u64, secret);
-            hasher.write(&data[..i]);
-            let original = unsafe {
-                c_wyhash_final3(
-                    data.as_ptr() as *const c_void,
-                    i as u64,
-                    i as u64,
-                    secret.as_ptr() as *const c_ulonglong,
-                )
-            };
-            assert_eq!(original, hasher.finish());
+        #[test]
+        fn core_hasher() {
+            let secret = final3::make_secret(0);
+            let mut data = [0; 256];
+            for i in 0..data.len() {
+                data[i] = i as u8;
+                let mut hasher = final3::WyHash::new(i as u64, secret);
+                hasher.write(&data[..i]);
+                let original = unsafe {
+                    $c_function(
+                        data.as_ptr() as *const c_void,
+                        i as u64,
+                        i as u64,
+                        secret.as_ptr() as *const c_ulonglong,
+                    )
+                };
+                assert_eq!(original, hasher.finish());
+            }
         }
-    }
+    };
+}
+
+mod final3_tests {
+    use super::*;
+    #[cfg(not(feature = "mum32bit"))]
+    final3_tests!(c_wyhash_final3);
+
+    #[cfg(feature = "mum32bit")]
+    final3_tests!(c_wyhash_final3_32bit_mum);
 }

comparison/tests/back_to_back_prng.rs

@@ -1,4 +1,8 @@
-use comparison::ffi::{c_wyrng_final3, c_wyrng_v1};
+#[cfg(not(feature = "mum32bit"))]
+use comparison::ffi::c_wyrng_final3;
+#[cfg(feature = "mum32bit")]
+use comparison::ffi::c_wyrng_final3_32bit_mum;
+use comparison::ffi::c_wyrng_v1;
 use rand::{RngCore, SeedableRng};
 use wyhash::v1::wyrng as wyrng_v1;
 use wyhash::v1::WyRng as WyRngV1;
@@ -103,4 +107,9 @@ macro_rules! impl_tests {
 }
 
 impl_tests!(v1, WyRngV1, wyrng_v1, c_wyrng_v1);
+
+#[cfg(not(feature = "mum32bit"))]
 impl_tests!(final3, WyRng, wyrng, c_wyrng_final3);
+
+#[cfg(feature = "mum32bit")]
+impl_tests!(final3, WyRng, wyrng, c_wyrng_final3_32bit_mum);

src/final3/functions.rs

@@ -1,6 +1,25 @@
 use crate::v1::functions::{read32, read64, P0, P1};
 use core::cmp::Ordering;
 
+#[cfg(feature = "mum32bit")]
+#[inline]
+fn wyrotate(x: u64) -> u64 {
+    (x >> 32) | (x << 32)
+}
+
+#[cfg(feature = "mum32bit")]
+#[inline]
+fn wymum(a: u64, b: u64) -> u64 {
+    let hh = (a >> 32) * (b >> 32);
+    let hl = (a >> 32) * (b & 0xFFFF_FFFF);
+    let lh = (a & 0xFFFF_FFFF) * (b >> 32);
+    let ll = (a & 0xFFFF_FFFF) * (b & 0xFFFF_FFFF);
+    let a = wyrotate(hl) ^ hh;
+    let b = wyrotate(lh) ^ ll;
+    a ^ b
+}
+
+#[cfg(not(feature = "mum32bit"))]
 #[inline]
 fn wymum(a: u64, b: u64) -> u64 {
     let r = u128::from(a) * u128::from(b);

src/lib.rs

@@ -18,6 +18,13 @@
 //! [original]: https://github.com/wangyi-fudan/wyhash
 //! [original-version]: https://github.com/eldruin/wyhash-rs/blob/master/comparison/original/CMakeLists.txt
 //!
+//! ## Crate features
+//!
+//! By default this crate uses 128-bit integer multiplications.
+//! To restrict that to 64 bits you can enable the feature `mum32bit`. This offers better
+//! performance on 32-bit architectures.
+//! Beware that this feature produces different the results.
+//!
 //! ## Usage (see also examples folder)
 //!
 //! For the hashing function you can use either the free function or the
@@ -32,7 +39,7 @@
 //! let seed = 3;
 //! let hash = wyhash(&data, seed, make_secret(seed));
 //!
-//! assert_eq!(0xebd4_9a0a_d010_78ce, hash);
+//! println!("{:x}", hash); // prints ebd49a0ad01078ce
 //! ```
 //!
 //! ### `Hasher` trait usage
@@ -47,7 +54,7 @@
 //! let mut hasher = WyHash::new(4, secret);
 //! hasher.write(&[0, 1, 2]);
 //!
-//! assert_eq!(0x8301_42a2_4404_5ff4, hasher.finish());
+//! println!("{:x}", hasher.finish()); // prints 830142a244045ff4
 //! ```
 //!
 //! ### `wyrng` function usage
@@ -61,8 +68,8 @@
 //! let mut seed = 3;
 //! let random_number = wyrng(&mut seed);
 //!
-//! assert_eq!(0x3e9_9a77_2750_dcbe, random_number);
-//! assert_eq!(0xa0761d6478bd6432, seed);
+//! println!("{:x}", random_number); // prints 3e99a772750dcbe
+//! println!("{:x}", seed); //prints a0761d6478bd6432
 //! ```
 //!
 //! ### `RngCore` trait usage
@@ -74,7 +81,7 @@
 //! use wyhash::WyRng;
 //!
 //! let mut rng = WyRng::default();
-//! assert_eq!(0x111c_b3a7_8f59_a58e, rng.next_u64());
+//! println!("{:x}", rng.next_u64()); // prints 111cb3a78f59a58e
 //! ```
 //!
 //! ### `SeedableRng` trait usage
@@ -88,11 +95,11 @@
 //! // Seeds are 8-byte long.
 //! let seed = [0, 1, 2, 3, 4, 5, 6, 7];
 //! let mut rng1 = WyRng::from_seed(seed);
-//! assert_eq!(0xd730_1357_74c6_ae31, rng1.next_u64());
+//! println!("{:x}", rng1.next_u64()); // prints d730135774c6ae31
 //!
 //! // Alternatively you can also use this convenience method:
 //! let mut rng2 = WyRng::seed_from_u64(3);
-//! assert_eq!(0x3e9_9a77_2750_dcbe, rng2.next_u64());
+//! println!("{:x}", rng2.next_u64()); // prints 3e99a772750dcbe
 //! ```
 
 #![doc(html_root_url = "https://docs.rs/wyhash/0.5.0")]

tests/integration.rs

@@ -12,7 +12,12 @@ fn v1_default_constructed() {
 
 #[test]
 fn final3_default_constructed() {
+    #[cfg(not(feature = "mum32bit"))]
+    let expected = 0x22a2_d5db_3856_770f;
+    #[cfg(feature = "mum32bit")]
+    let expected = 0x6a2c_d506_62d4_cdf1;
+
     let mut hasher = final3::WyHash::default();
     hasher.write(&[0]);
-    assert_eq!(0x22a2_d5db_3856_770f, hasher.finish());
+    assert_eq!(expected, hasher.finish());
 }