bit_arch
Fast and efficient architecture-tuned bit operations.
Features
This crate implements safe wrappers around x86 instructions.
let int1_mask = 0b0011_1110; // saves 5 bits of int1
let int1_val = 37_u32; // 0b0010_0101 or 0b0010_0100 | 1
let int2_mask = 0b0000_0111;
let int2_val = 5_u32; // 0b0000_0101
let int1_packed = extract;
let int2_packed = extract;
// pack two u32s into one u8
let packed8 = as u8;
// do something with that like copy it into a struct field
// deposit only works on u32/u64
let packed32 = packed8 as u32;
// `| 1` recovers the one bit we ignored at the start of int1_mask
let extracted_int1 = deposit | 1;
let extracted_int2 = deposit;
assert_eq!;
assert_eq!;
It may look like just some bit shifts, but it's much more than that. Mask can be anything at all. Maybe you want to ignore bits 2, 7, and 31 of a u64 but keep the rest. That's not even the best part though; it's FAST.
Still not fast enough? You need to go a level lower. Below the abstract API of bit_arch is bit_arch::arch. Everyone knows double the "arch"es means double the performance:
let mask = 0xAC5;
let initial_val = 0xABC;
let packed = extract_u32;
let low_contiguous = extract_bitfield_u32;
let lowest_clear = isolate_lowest_clear_u32;
let new_mask = trailing_one_mask_u32;
let new_val = deposit_u32;
assert_eq!;
There is also one optional feature:
dynamic: Enables dynamic operation dispatch. This should only be used for testing or debugging! Using it in production will severely hurt performance. It also requiresstd.
By default, this crate depends on x86_intr. This will be removed when core::arch::x86_64 stabilizes _mm_popcnt_u32/_mm_popcnt_u64.
Performance
Assembly output has been carefully analyzed and is guaranteed to include the desired instructions. These instructions are listed below. Regardless, compiling with target-cpu=native has proven to greatly improved performance. Dropping from ~22.839 ns to ~521.33 ps for extract/deposit (or pext/pdep) roundtrips. That's a 44x improvement!
Architecture-Specific Details
Particularly operations in BMI 1/2, TBM, and ABM extensions. It implements most operations through a safe API. All supported operations are listed below:
x86_64 |
Target Feature | bit_arch::arch |
|---|---|---|
_andn_* |
bmi1 |
inverted_and_* |
_bextr_* |
bmi1, tbm |
extract_bitfield_* |
_blci_* |
tbm |
isolate_lowest_clear_* |
_blcic_* |
tbm |
set_lowest_clear_* |
_blcs_* |
tbm |
set_lowest_zero_* |
_blsfill_* |
tbm |
from_lowest_set_* |
_blsi_* |
bmi1 |
isolate_lowest_set_* |
_blsic_* |
tbm |
complement_lowest_set_* |
_blsmsk_* |
bmi1 |
through_lowest_set_* |
_blsr_* |
bmi1 |
clear_lowest_set_* |
_bzhi_* |
bmi2 |
zero_upper_* |
_lzcnt_* |
abm |
leading_zeros_* |
_pdep_* |
bmi2 |
deposit_* |
_pext_* |
bmi2 |
extract_* |
_popcnt* |
abm |
count_ones_** |
_t1mskc_* |
tbm |
trailing_one_mask_* |
_tzcnt_* |
bmi1 |
trailing_zeros_* |
_tzmskc_* |
tbm |
trailing_zero_mask_* |
[*] count_ones only uses the corresponding _popcnt* intrinsics if the popcnt_uint feature is enabled.
All functions defined in bit_arch::arch are completely safe and have optimized fallback paths. Despite this, there is a preferred higher level API that offers the same level of performance, but is generic over the type u32 or u64.
There are also more intrinsics listed below, but these don't have a high-level API in the crate. They may never get a abstraction either. They will recieve updates and will be maintained.
x86_64 |
Target Feature | bit_arch::arch |
|---|---|---|
_bextr2_* |
bmi1, tbm |
extract_bitfield_control_* |
_bswap* |
None | swap_bytes_* |
bittest* |
None | bit_test_* |
bittestandset* |
None | bit_test_set_* |
bittestandreset* |
None | bit_test_reset_* |
bittestandcomplement* |
None | bit_test_complement_* |
trailing_zeros also has an intrinsic only accessible from arch, trailing_zeros_u16.