Module stateful_supplier 

StatefulSupplier Types

Provides stateful supplier implementations that generate and return values without taking input while allowing mutable internal state.

Overview

A StatefulSupplier is a functional abstraction equivalent to FnMut() -> T: it generates values without accepting input and may update its own internal state between calls. It is useful for counters, sequences, generators, and memoized computations.

For stateless factories and constants that only need Fn() -> T, use Supplier.

Core Design Principles

1. Returns Ownership: StatefulSupplier returns T (not &T) to avoid lifetime issues
2. Uses &mut self: Typical scenarios (counters, generators) require state modification
3. Separate stateless API: Supplier covers lock-free stateless factories, while StatefulSupplier covers stateful generation

Three Implementations

• BoxStatefulSupplier<T>: Single ownership using Box<dyn FnMut() -> T>. Zero overhead, cannot be cloned. Best for one-time use and builder patterns.

• ArcStatefulSupplier<T>: Thread-safe shared ownership using Arc<Mutex<dyn FnMut() -> T + Send>>. Can be cloned and sent across threads. Higher overhead due to locking.

• RcStatefulSupplier<T>: Single-threaded shared ownership using Rc<RefCell<dyn FnMut() -> T>>. Can be cloned but not sent across threads. Lower overhead than ArcStatefulSupplier.

Comparison with Other Functional Abstractions

Type	Input	Output	self	Modifies?	Use Case
Supplier	None	T	&mut	Yes	Factory
Consumer	&T	()	&mut	Yes	Observer
Predicate	&T	bool	&self	No	Filter
Function	&T	R	&self	No	Transform

Examples

Basic Counter

use qubit_function::{BoxStatefulSupplier, StatefulSupplier};

let mut counter = 0;
let mut supplier = BoxStatefulSupplier::new(move || {
    counter += 1;
    counter
});

assert_eq!(supplier.get(), 1);
assert_eq!(supplier.get(), 2);
assert_eq!(supplier.get(), 3);

Method Chaining

use qubit_function::{BoxStatefulSupplier, StatefulSupplier};

let mut pipeline = BoxStatefulSupplier::new(|| 10)
    .map(|x| x * 2)
    .map(|x| x + 5);

assert_eq!(pipeline.get(), 25);

Thread-safe Sharing

use qubit_function::{ArcStatefulSupplier, StatefulSupplier};
use std::sync::{Arc, Mutex};
use std::thread;

let counter = Arc::new(Mutex::new(0));
let counter_clone = Arc::clone(&counter);

let supplier = ArcStatefulSupplier::new(move || {
    let mut c = counter_clone.lock().unwrap();
    *c += 1;
    *c
});

let mut s1 = supplier.clone();
let mut s2 = supplier.clone();

let h1 = thread::spawn(move || s1.get());
let h2 = thread::spawn(move || s2.get());

let v1 = h1.join().unwrap();
let v2 = h2.join().unwrap();

assert!(v1 != v2);
assert_eq!(*counter.lock().unwrap(), 2);

Author

Haixing Hu

Structs

ArcStatefulSupplier

Thread-safe shared ownership supplier.

BoxStatefulSupplier

Box-based single ownership supplier.

RcStatefulSupplier

Single-threaded shared ownership supplier.

Traits

FnStatefulSupplierOps

Extension trait providing supplier operations for closures

StatefulSupplier

Supplier trait: generates and returns values without input.