diff --git a/README.md b/README.md index 039a8274..57bb507e 100644 --- a/README.md +++ b/README.md @@ -105,20 +105,30 @@ It's recommended to keep the default configuration for the options ending with ` | __io_by_cpu*__ | bool | false | The flag indicating if the CPU handles IO. | | __reserved_key_start_bit__ | int | 0 | The start bit offset of reserved key in the 64 bit | +- Fore more details refer to [`struct HashTableOptions`](https://github.com/NVIDIA-Merlin/HierarchicalKV/blob/master/include/merlin_hashtable.cuh#L60). + #### Reserved Keys -- The keys of `0xFFFFFFFFFFFFFFFD`, `0xFFFFFFFFFFFFFFFE`, and `0xFFFFFFFFFFFFFFFF` are reserved for internal using. -- Call set options.reserved_key_start_bit to change the reserved keys if the default one conflicted with your keys. - The valid range of reserved_key_start_bit is [0, 62] and the default value is 0, meaning the default reserved keys. - reserved_key_start_bit = 1 means using the insignificant bits 1 and 2 as the keys as the reserved keys, - in binary format, it looks like 111~11xx0, and the index 0 bit is 0 and all the other bits are positive, in this case the new reserved keys are - `FFFFFFFFFFFFFFFE`, `0xFFFFFFFFFFFFFFFC`, `0xFFFFFFFFFFFFFFF8`, and `0xFFFFFFFFFFFFFFFA` - reserved_key_start_bit = 2, in binary format, it looks like 111~11xx10, bit offset 0 are always 0 for any reserved_key_start_bit != 0, +- By default, the keys of `0xFFFFFFFFFFFFFFFD`, `0xFFFFFFFFFFFFFFFE`, and `0xFFFFFFFFFFFFFFFF` are reserved for internal using. + change `options.reserved_key_start_bit` if you want to use the above keys. + `reserved_key_start_bit` has a valid range from 0 to 62. The default value is 0, which is the above default reserved keys. When `reserved_key_start_bit` is set to any value other than 0, the least significant bit (bit 0) is always `0` for any reserved key. + +- Setting `reserved_key_start_bit = 1`: + - This setting reserves the two least significant bits 1 and 2 for the reserved keys. + - In binary, the last four bits range from `1000` to `1110`. Here, the least significant bit (bit 0) is always `0`, and bits from 3 to 63 are set to `1`. + - The new reserved keys in hexadecimal representation are as follows: + - `0xFFFFFFFFFFFFFFFE` + - `0xFFFFFFFFFFFFFFFC` + - `0xFFFFFFFFFFFFFFF8` + - `0xFFFFFFFFFFFFFFFA` + +- Setting `reserved_key_start_bit = 2`: + - This configuration reserves bits 2 and 3 as reserved keys. + - The binary representation for the last five bits ranges from `10010` to `11110`, with the least significant bit (bit 0) always set to `0`, and bits from 4 to 63 are set to `1`. + - if you change the reserved_key_start_bit, you should use same value for save/load - For more detail, please refer to [`init_reserved_keys`](https://github.com/search?q=repo%3ANVIDIA-Merlin%2FHierarchicalKV%20init_reserved_keys&type=code). -For more detail, please refer to [`struct HashTableOptions`](https://github.com/NVIDIA-Merlin/HierarchicalKV/blob/master/include/merlin_hashtable.cuh#L60). + For more detail, please refer to [`init_reserved_keys`](https://github.com/search?q=repo%3ANVIDIA-Merlin%2FHierarchicalKV%20init_reserved_keys&type=code) ### How to use: - ```cpp #include "merlin_hashtable.cuh" @@ -153,6 +163,7 @@ int main(int argc, char *argv[]) } ``` + ### Usage restrictions - The `key_type` must be `int64_t` or `uint64_t`.