# BitFields API: Type-Safe Bit Packing for Lock-Free Data Structures

DevFeed: [BitFields API: Type-Safe Bit Packing for Lock-Free Data Structures](<https://devfeed.tech/articles/bitfields-api-type-safe-bit-packing-for-lock-free-data-structures-22396.md>)

Original publisher: [Read original article](<http://rocksdb.org/blog/2025/12/31/bit-fields-api.html>)

Author: Peter Dillinger

Published: 2025-12-31T00:00:00Z

Content type: tutorial

Language: en

Sources: [RocksDB](<https://devfeed.tech/sources/rocksdb.md>)

Topics: [rocksdb](<https://devfeed.tech/topics/rocksdb.md>), [C++](<https://devfeed.tech/topics/c-plus-plus.md>), [Data structures](<https://devfeed.tech/topics/data-structures.md>), [Cache](<https://devfeed.tech/topics/cache.md>), [Code](<https://devfeed.tech/topics/code.md>)

Tags: [atomic](<https://devfeed.tech/tags/atomic.md>), [blog](<https://devfeed.tech/tags/blog.md>), [c-plus-plus](<https://devfeed.tech/tags/c-plus-plus.md>), [cache](<https://devfeed.tech/tags/cache.md>), [concurrent](<https://devfeed.tech/tags/concurrent.md>), [efficiency](<https://devfeed.tech/tags/efficiency.md>), [implementation](<https://devfeed.tech/tags/implementation.md>), [lock-free](<https://devfeed.tech/tags/lock-free.md>)

## AI overview

This article introduces RocksDB's BitFields API, a type-safe, zero-overhead C++ abstraction for packing multiple logical fields into atomic variables. It explains how the API helps manage packed state and describes its use in the essentially lock-free HyperClockCache.

## Source excerpt

Modern concurrent data structures increasingly rely on atomic operations to avoid the overhead of locking. A valuable but under-utilized technique for maximizing the effectiveness of atomic operations is bit packing--fitting multiple logical fields into a single atomic variable for algorithmic simplicity and efficiency. However, language support for bit packing does not guarantee dense packing, and manually managing bit manipulation quickly becomes error-prone, especially when dealing with complex state machines. To address this in RocksDB, we have developed a reusable BitFields API, a type-safe, zero-overhead abstraction for bit packing in C++. This works in conjunction with clean wrappers for std::atomic for powerful and relatively safe bit-packing of atomic data. For broader use, a variant of the code has been proposed for adding to folly. The Problem: Managing Packed Bit Fields Consider HyperClockCache, an essentially lock-free cache implementation in RocksDB, which was refactored to use this BitFields API. It is a hash table built on slots that can each hold a cache entry and relevant metadata. For atomic simplicity and efficiency, all the essential metadata for each slot is packed into a single 64-bit value: The reference count and eviction metadata are together encoded into acquire and release counters, 30 bits each. The possible states of {empty, under construction/destruction, occupied+visible, and occupied+invisible} are encoded into three state bits (instead of two, for easier decoding and manipulation). A hit bit is used for secondary cache integration. Traditionally, you might write code like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 // Old approach: manual bit manipulation constexpr uint64_t kAcquireCounterShift = 0; constexpr uint64_t kReleaseCounterShift = 30; constexpr uint64_t kCounterMask = 0x3FFFFFFF; constexpr uint64_t kHitBitShift = 60; constexpr uint64_t k