Crate hypercounter 

An atomic, lock-free, hash map-like counter structure.

It uses papaya::HashMap under the hood to provide concurrent access to multiple keys at once, allowing for efficient counting without the need for locks.

Notes Before Use

• Operations on atomics are always wrapping on overflow.

Getting Started

To install this library, run the following command:

cargo add hypercounter

That’s it! To start using it, create a new HyperCounter instance:

use std::sync::atomic::{AtomicUsize, Ordering};
use hypercounter::HyperCounter;

let counter: HyperCounter<String, AtomicUsize> = HyperCounter::new();

counter.fetch_add("example_key".to_string(), 1, Ordering::Relaxed);
counter.fetch_sub("example_key".to_string(), 1, Ordering::Relaxed);

Keys are automatically removed when their associated counter reaches zero. Neither inserts nor removals are needed explicitly. If you want to remove a key manually, however, you can do so using HyperCounter::swap() to swap the value with 0.

let previous_value = counter.swap("example_key".to_string(), 0, Ordering::Relaxed);

Supported Operations

The following atomic operations are supported:

• HyperCounter::load(): Atomically loads the current value for a given key.
• HyperCounter::swap(): Atomically swaps the value for a given key.
• HyperCounter::fetch_add(): Atomically adds a value to the counter for a given key.
• HyperCounter::fetch_sub(): Atomically subtracts a value from the counter for a given key.
• HyperCounter::fetch_and(): Atomically performs a bitwise AND operation on the counter for a given key.
• HyperCounter::fetch_nand(): Atomically performs a bitwise NAND operation on the counter for a given key.
• HyperCounter::fetch_or(): Atomically performs a bitwise OR operation on the counter for a given key.
• HyperCounter::fetch_xor(): Atomically performs a bitwise XOR operation on the counter for a given key.
• HyperCounter::fetch_max(): Atomically sets the counter for a given key to the maximum of the current value and the provided value.
• HyperCounter::fetch_min(): Atomically sets the counter for a given key to the minimum of the current value and the provided value.

Benchmarking

There’s a simple benchmark example included in the examples directory. You can run it using:

cargo run --example bench

This will execute a series of single-threaded benchmarks and print the operations per second for various scenarios.

Structs

HyperCounter