feat: add wrap-around and time-based iteration support

Iterator cycling features for workloads exceeding keyspace size:

- Add duration_ms to SamplingConfig for time-based iteration limits
- RandomIter cycles when limit > range_size (e.g., 1M requests on 100K keys)
- SequentialIter auto-enables wrap_around when duration_ms is set
- FilterContext tracks start_time_ms and checks both count and duration limits

New tests for multi-threaded wrap-around behavior:
- test_random_cycling_limit_exceeds_keyspace
- test_random_cycling_multithreaded
- test_random_duration_based_cycling / _multithreaded
- test_sequential_duration_based / _multithreaded
- test_partitioned_with_limit / _multithreaded_disjoint
- test_delete_iter_single_pass
- test_limit_with_duration_limit_wins
- test_duration_with_limit_duration_wins

Documentation updates with examples for:
- Wrap-around mode (.wrap_around())
- Cycling with limit > keyspace
- Time-based iteration (duration_ms)

Author: zvi-code

src/config.rs

@@ -68,6 +68,11 @@ pub struct SamplingConfig {
     /// Maximum number of items to return. None = unlimited.
     pub limit: Option<u64>,
 
+    /// Duration limit for iteration (in milliseconds). None = unlimited.
+    /// When set, iteration continues until the duration expires.
+    /// Combines with `limit` - iteration stops when either is reached.
+    pub duration_ms: Option<u64>,
+
     /// Probabilistic sampling ratio (0.0-1.0).
     /// Each matching item has this probability of being returned.
     /// 1.0 = return all matching, 0.5 = return ~50% of matching.
@@ -92,6 +97,7 @@ impl SamplingConfig {
         Self {
             set_ratio: None,
             limit: None,
+            duration_ms: None,
             sample_probability: 1.0,
             seed: None,
             distribution: AccessDistribution::Uniform,
@@ -117,6 +123,16 @@ impl SamplingConfig {
         self
     }
 
+    /// Set duration limit for iteration (in milliseconds).
+    ///
+    /// Iteration will continue (with wraparound) until the duration expires.
+    /// This enables time-based workloads like "run for 60 seconds".
+    #[inline]
+    pub const fn with_duration_ms(mut self, duration_ms: u64) -> Self {
+        self.duration_ms = Some(duration_ms);
+        self
+    }
+
     /// Set probabilistic sampling (each item has `prob` chance of being returned).
     ///
     /// Use this to randomly sample a percentage of the keyspace.
@@ -164,6 +180,7 @@ impl SamplingConfig {
     #[inline]
     pub fn has_sampling(&self) -> bool {
         self.limit.is_some() 
+            || self.duration_ms.is_some()
             || self.sample_probability < 1.0 
             || self.set_ratio.is_some()
             || !matches!(self.distribution, AccessDistribution::Uniform)
@@ -224,28 +241,52 @@ pub struct FilterContext {
     pub(crate) sampling: SamplingConfig,
     rng: fastrand::Rng,
     yielded: u64,
+    /// Start time for duration-based iteration (milliseconds since UNIX epoch).
+    start_time_ms: Option<u64>,
 }
 
 impl FilterContext {
     /// Create a new filter context.
     #[inline]
     pub fn new(filter: BitFilter, sampling: SamplingConfig) -> Self {
         let rng = sampling.make_rng();
+        let start_time_ms = sampling.duration_ms.map(|_| Self::current_time_ms());
         Self {
             filter,
             sampling,
             rng,
             yielded: 0,
+            start_time_ms,
         }
     }
 
-    /// Check if we should continue iterating (respects limit).
+    /// Get current time in milliseconds since UNIX epoch.
+    #[inline]
+    fn current_time_ms() -> u64 {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    /// Check if we should continue iterating (respects limit and duration).
     #[inline]
     pub fn check_limit(&self) -> bool {
-        match self.sampling.limit {
-            Some(limit) => self.yielded < limit,
-            None => true,
+        // Check count limit
+        if let Some(limit) = self.sampling.limit {
+            if self.yielded >= limit {
+                return false;
+            }
         }
+        // Check duration limit
+        if let (Some(duration_ms), Some(start_time_ms)) = (self.sampling.duration_ms, self.start_time_ms) {
+            let elapsed = Self::current_time_ms().saturating_sub(start_time_ms);
+            if elapsed >= duration_ms {
+                return false;
+            }
+        }
+        true
     }
 
     /// Check if item matches filter (with mixed-ratio support).