8 stable releases
1.3.2 | Aug 2, 2023 |
---|---|
1.3.1 | Jan 22, 2023 |
1.2.0 | Oct 4, 2021 |
1.1.0 | Aug 3, 2021 |
0.1.0 | Feb 5, 2019 |
#319 in Algorithms
24,730 downloads per month
Used in 11 crates
(6 directly)
55KB
896 lines
cuid-rust
Cuids are "Collision-resistant ids optimized for horizontal scaling and binary search lookup performance."
This is a rust implementation of the CUID library, the original JavaScript implementation of which may be found here
Installation
In cargo.toml
cuid = "1.2.0"
Or install the binary:
> cargo install cuid
Usage
use cuid;
fn main() -> () {
println!("{}", cuid::cuid().unwrap());
println!("{}", cuid::slug().unwrap());
}
cuid
is safe to use across threads. When used in a multithreaded context, all
threads share the same atomic counter, which is used as a component of the
generated CUID.
This package also provides a binary if installed via cargo install
.
Its default behavior is to generate a CUID:
> cuid
ckmqrwysb0000iz5p4u1b79hd
You can also generate a slug:
> cuid --slug
4k0000dszy
See cuid --help
for more information.
Performance
Performance is one of the primary concerns of this library (see Benchmarking, below).
This implementation is currently about 20x faster than the reference JavaScript implementation.
It takes about 280 nanoseconds to generate a CUID, or 200 nanoseconds to generate a CUID slug, on relatively modern desktop hardware.
In a long-running process or thread, CUID generation is faster, since the system fingerprint is calculated once and then re-used for the lifetime of the process. In this case, CUID generation takes about 125 ns.
Tests
Tests can be run with
cargo test -p cuid
Some tests are ignored because they're slow. To run them:
cargo test -p cuid -- collisions::test --ignored --test-threads=1
Some tests require to be run in a single thread and are ignored by default. To run them:
cargo test -p cuid -- collisions::single_thread --ignored --test-threads=1
Benchmarking
Inline benchmarks are available when running with the nightly toolchain. There
are also criterion bnechmarks in benches/cuid.rs
.
If you're on a Linux system, it's recommended to run benchmarks with the
maximum possible priority, via nice
, in order to avoid confounding effects
from other processes running on the system:
$ nice -n -20 cargo bench
Note that you may need to run nice
as root:
sudo nice -n -20 su <username> -l -c "cd $PWD && cargo bench"
Dependencies
~2.5MB
~33K SLoC