#Pseudo-Random and Hashing

#define FIO_RAND
#include "fio-stl.h"

A non-cryptographic pseudo-random generator plus RiskyHash and Stable Hash. The PRNG is seeded from system jitter (getrusage, clocks) and hashed with RiskyHash. It is faster and more random than typical rand() implementations, but do not use it for cryptography — use fio_rand_bytes_secure for that.

RiskyHash is an ephemeral, non-cryptographic hash family that may change between releases. Stable Hash is frozen and safe for persistent data. RiskyHash 256/512 and HMAC variants are also provided.

#Pseudo-Random Functions

#fio_rand64

SFUNC uint64_t fio_rand64(void);

Returns 64 pseudo-random bits.

#fio_rand128

SFUNC fio_u128 fio_rand128(void);

Returns 128 pseudo-random bits as a fio_u128.

#fio_rand_bytes

SFUNC void fio_rand_bytes(void *target, size_t len);

Fills target with len pseudo-random bytes.

#fio_rand_bytes_secure

SFUNC int fio_rand_bytes_secure(void *target, size_t len);

Fills target with len cryptographically secure random bytes from the system CSPRNG (arc4random_buf on BSD/macOS, /dev/urandom fallback elsewhere). Returns 0 on success, -1 on failure.

Use this for keys, nonces, and anything security-sensitive.

#fio_rand_reseed

SFUNC void fio_rand_reseed(void);

Rotates the PRNG state with fresh entropy. Call after fork to avoid duplicated sequences.

#Risky / Stable Hash

#FIO_USE_STABLE_HASH_WHEN_CALLING_RISKY_HASH

#define FIO_USE_STABLE_HASH_WHEN_CALLING_RISKY_HASH 0

When set to 1, fio_risky_hash redirects to fio_stable_hash.

#fio_risky_hash

SFUNC uint64_t fio_risky_hash(const void *buf, size_t len, uint64_t seed);

64-bit RiskyHash v.3. Ephemeral — hash values may change in future releases. Good for hash-map keys, not for storage.

#fio_risky_ptr

FIO_IFUNC uint64_t fio_risky_ptr(void *ptr);

Fast entropy mix for pointer values.

#fio_risky_num

FIO_IFUNC uint64_t fio_risky_num(uint64_t number, uint64_t seed);

Fast entropy mix for integer values.

#fio_stable_hash

SFUNC uint64_t fio_stable_hash(const void *data, size_t len, uint64_t seed);

64-bit Stable Hash. Frozen after 1.0; safe for on-disk or cross-system use.

#fio_stable_hash128

SFUNC void fio_stable_hash128(void *restrict dest,
                              const void *restrict data,
                              size_t len,
                              uint64_t seed);

Writes a 128-bit Stable Hash into dest (16 bytes).

#fio_risky256

SFUNC fio_u256 fio_risky256(const void *data, uint64_t len);

256-bit RiskyHash. Based on the A3 (Zero-Copy ILP) design: two 512-bit states, 128 bytes per iteration, multiply-fold with cross-lane mixing. Returns a fio_u256.

#fio_risky512

SFUNC fio_u512 fio_risky512(const void *data, uint64_t len);

512-bit RiskyHash. The first 256 bits are identical to fio_risky256; the rest come from an extra squeeze round.

#fio_risky256_hmac

SFUNC fio_u256 fio_risky256_hmac(const void *key,
                                 uint64_t key_len,
                                 const void *msg,
                                 uint64_t msg_len);

RFC 2104 HMAC using fio_risky256 as the hash, 64-byte block size. Keys longer than 64 bytes are hashed first. Securely zeros intermediates.

Note: the underlying hash is non-cryptographic; standard HMAC security proofs do not apply. Use Blake2 for cryptographic HMAC.

#fio_risky512_hmac

SFUNC fio_u512 fio_risky512_hmac(const void *key,
                                 uint64_t key_len,
                                 const void *msg,
                                 uint64_t msg_len);

Same construction as fio_risky256_hmac, but with fio_risky512 and a 64-byte digest.

#Example

#define FIO_RAND
#include "fio-stl.h"

int main(void) {
  printf("rand64: %016llX\n", (unsigned long long)fio_rand64());

  uint8_t key[32];
  fio_rand_bytes_secure(key, sizeof(key));

  uint64_t h = fio_stable_hash("hello", 5, 0);
  printf("stable: %016llX\n", (unsigned long long)h);

  fio_u256 r = fio_risky256("hello", 5);
  printf("risky256: %016llX...\n",
         (unsigned long long)r.u64[0]);
  return 0;
}