ExkPasswd.Buffer (ExkPasswd v0.2.0)

View Source

Stateful buffered random number generator for batch operations.

This module provides a more efficient way to generate random numbers when performing many operations by pre-allocating a buffer of cryptographically secure random bytes and consuming them as needed.

Performance

By reducing the number of :crypto.strong_rand_bytes/1 syscalls, this can provide 2-3x speedup for batch password generation.

Security

All random bytes come from :crypto.strong_rand_bytes/1, maintaining cryptographic security. The buffer is simply a performance optimization to batch syscalls.

Examples

iex> state = ExkPasswd.Buffer.new(1000)
...> {value, new_state} = ExkPasswd.Buffer.random_integer(state, 100)
...> is_integer(value)
true
iex> is_struct(new_state, ExkPasswd.Buffer)
true

iex> state = ExkPasswd.Buffer.new(1000)
...> {index, new_state} = ExkPasswd.Buffer.random_index(state, 10)
...> is_integer(index)
true
iex> is_struct(new_state, ExkPasswd.Buffer)
true

Summary

Types

t()

Functions

new(buffer_size \\ 10000)

Create a new buffered random generator.

random_boolean(state)

Generate a random boolean value.

random_digit(state)

Generate a random digit (0-9).

random_element(state, list)

Select a random element from a list.

random_index(state, count)

Generate a random index for selecting from a list.

random_integer(state, max)

Generate a random integer in the range [0, max).

Types

t()

@type t() :: %ExkPasswd.Buffer{
  buffer: binary(),
  buffer_size: pos_integer(),
  offset: non_neg_integer()
}

Functions

new(buffer_size \\ 10000)

@spec new(pos_integer()) :: t()

Create a new buffered random generator.

Parameters

  • buffer_size - Size of random byte buffer in bytes (default: 10,000)

Returns

A new Buffer state struct

Examples

iex> state = ExkPasswd.Buffer.new()
...> is_struct(state, ExkPasswd.Buffer)
true

iex> state = ExkPasswd.Buffer.new(5000)
...> state.buffer_size
5000

random_boolean(state)

@spec random_boolean(t()) :: {boolean(), t()}

Generate a random boolean value.

Returns a tuple of {boolean, new_state}.

Parameters

  • state - Current Buffer state

Returns

Tuple of {boolean, new_state}

Examples

iex> state = ExkPasswd.Buffer.new()
...> {value, _new_state} = ExkPasswd.Buffer.random_boolean(state)
...> is_boolean(value)
true

random_digit(state)

@spec random_digit(t()) :: {non_neg_integer(), t()}

Generate a random digit (0-9).

Returns a tuple of {digit, new_state}.

Parameters

  • state - Current Buffer state

Returns

Tuple of {digit, new_state} where digit is in range [0, 9]

Examples

iex> state = ExkPasswd.Buffer.new()
...> {digit, new_state} = ExkPasswd.Buffer.random_digit(state)
...> is_integer(digit)
true
iex> is_struct(new_state, ExkPasswd.Buffer)
true

random_element(state, list)

@spec random_element(t(), [term(), ...]) :: {term(), t()}

Select a random element from a list.

Returns a tuple of {element, new_state}.

Parameters

  • state - Current Buffer state
  • list - Non-empty list to select from

Returns

Tuple of {element, new_state}

Examples

iex> state = ExkPasswd.Buffer.new()
...> {elem, _new_state} = ExkPasswd.Buffer.random_element(state, [1, 2, 3])
...> elem in [1, 2, 3]
true

random_index(state, count)

@spec random_index(t(), pos_integer()) :: {non_neg_integer(), t()}

Generate a random index for selecting from a list.

Equivalent to random_integer/2 but with clearer semantics for list indexing.

Parameters

  • state - Current Buffer state
  • count - Number of items in the list

Returns

Tuple of {index, new_state} where index is in range [0, count)

Examples

iex> state = ExkPasswd.Buffer.new()
...> {index, new_state} = ExkPasswd.Buffer.random_index(state, 10)
...> is_integer(index)
true
iex> is_struct(new_state, ExkPasswd.Buffer)
true

random_integer(state, max)

@spec random_integer(t(), pos_integer()) :: {non_neg_integer(), t()}

Generate a random integer in the range [0, max).

Returns a tuple of {random_integer, new_state}.

Parameters

  • state - Current Buffer state
  • max - Upper bound (exclusive)

Returns

Tuple of {random_integer, new_state}

Examples

iex> state = ExkPasswd.Buffer.new()
...> {value, new_state} = ExkPasswd.Buffer.random_integer(state, 100)
...> is_integer(value)
true
iex> is_struct(new_state, ExkPasswd.Buffer)
true