docs: add queue examples and benchmarks

Author: jeresoftx

Cargo.toml

@@ -49,6 +49,18 @@ path = "examples/soluciones/stack_balanced_parentheses.rs"
 name = "solution_stack_undo_redo"
 path = "examples/soluciones/stack_undo_redo.rs"
 
+[[example]]
+name = "solution_queue_trace_order"
+path = "examples/soluciones/queue_trace_order.rs"
+
+[[example]]
+name = "solution_queue_round_robin"
+path = "examples/soluciones/queue_round_robin.rs"
+
+[[example]]
+name = "solution_queue_filter_ready_jobs"
+path = "examples/soluciones/queue_filter_ready_jobs.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
@@ -63,3 +75,8 @@ harness = false
 name = "stack_bench"
 path = "benches/stack_bench.rs"
 harness = false
+
+[[bench]]
+name = "queue_bench"
+path = "benches/queue_bench.rs"
+harness = false

benches/queue_bench.rs

@@ -0,0 +1,65 @@
+use rust_data_structures::queue::Queue;
+use rust_data_structures::vector::Vector;
+use std::hint::black_box;
+use std::time::{Duration, Instant};
+
+const SIZE: usize = 30_000;
+
+fn main() {
+    println!("queue benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!("circular enqueue/dequeue: {:?}", bench_circular_queue());
+    println!(
+        "naive vector front remove: {:?}",
+        bench_naive_vector_queue()
+    );
+    println!("wraparound reuse: {:?}", bench_wraparound_reuse());
+}
+
+fn bench_circular_queue() -> Duration {
+    let start = Instant::now();
+    let mut queue = Queue::new();
+
+    for value in 0..SIZE {
+        queue.enqueue(black_box(value));
+    }
+
+    while let Some(value) = queue.dequeue() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}
+
+fn bench_naive_vector_queue() -> Duration {
+    let start = Instant::now();
+    let mut vector = Vector::new();
+
+    for value in 0..SIZE {
+        vector.push(black_box(value));
+    }
+
+    while !vector.is_empty() {
+        black_box(vector.remove(0));
+    }
+
+    start.elapsed()
+}
+
+fn bench_wraparound_reuse() -> Duration {
+    let start = Instant::now();
+    let mut queue = Queue::with_capacity(128);
+
+    for value in 0..SIZE {
+        queue.enqueue(black_box(value));
+        if value % 2 == 0 {
+            black_box(queue.dequeue());
+        }
+    }
+
+    while let Some(value) = queue.dequeue() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}

diagrams/04-queue.mmd

@@ -0,0 +1,27 @@
+flowchart LR
+    title["Queue: FIFO con buffer circular"]
+
+    subgraph metadata["Metadatos"]
+        head["head = 2"]
+        len["len = 4"]
+        cap["capacity = 6"]
+    end
+
+    subgraph buffer["Buffer físico"]
+        slot0["0: D"]
+        slot1["1: libre"]
+        slot2["2: A (front)"]
+        slot3["3: B"]
+        slot4["4: C"]
+        slot5["5: libre"]
+    end
+
+    head --> slot2
+    len --> slot0
+    cap --> slot5
+
+    dequeue["dequeue()<br/>toma front y avanza head"]
+    enqueue["enqueue(E)<br/>escribe en (head + len) % capacity"]
+
+    dequeue --> head
+    enqueue --> slot1

examples/queue_advanced.rs

@@ -0,0 +1,19 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut queue = Queue::with_capacity(3);
+
+    queue.enqueue("A");
+    queue.enqueue("B");
+    queue.enqueue("C");
+    queue.dequeue();
+    queue.dequeue();
+    queue.enqueue("D");
+    queue.enqueue("E");
+
+    println!("capacidad: {}", queue.capacity());
+    println!(
+        "orden logico: {:?}",
+        queue.iter().copied().collect::<Vec<_>>()
+    );
+}

examples/queue_basic.rs

@@ -0,0 +1,12 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut queue = Queue::new();
+
+    queue.enqueue("primer estudiante");
+    queue.enqueue("segundo estudiante");
+    queue.enqueue("tercer estudiante");
+
+    println!("siguiente: {}", queue.front().unwrap());
+    println!("atendido: {}", queue.dequeue().unwrap());
+}

examples/queue_intermediate.rs

@@ -0,0 +1,13 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut jobs = Queue::new();
+
+    jobs.enqueue("generar docs");
+    jobs.enqueue("correr tests");
+    jobs.enqueue("publicar reporte");
+
+    while let Some(job) = jobs.dequeue() {
+        println!("procesando: {job}");
+    }
+}

examples/queue_real_case.rs

@@ -0,0 +1,24 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut requests = Queue::new();
+
+    requests.enqueue(Request::new("/courses", 10));
+    requests.enqueue(Request::new("/courses/rust-data-structures", 12));
+    requests.enqueue(Request::new("/health", 1));
+
+    while let Some(request) = requests.dequeue() {
+        println!("{} ({} ms)", request.path, request.estimated_ms);
+    }
+}
+
+struct Request {
+    path: &'static str,
+    estimated_ms: u32,
+}
+
+impl Request {
+    fn new(path: &'static str, estimated_ms: u32) -> Self {
+        Self { path, estimated_ms }
+    }
+}

examples/soluciones/queue_filter_ready_jobs.rs

@@ -0,0 +1,36 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut queue = Queue::new();
+    queue.enqueue(Job::new("index", true));
+    queue.enqueue(Job::new("email", false));
+    queue.enqueue(Job::new("report", true));
+
+    let ready = drain_ready(queue);
+
+    assert_eq!(ready, vec!["index", "report"]);
+    println!("{ready:?}");
+}
+
+fn drain_ready(mut queue: Queue<Job>) -> Vec<&'static str> {
+    let mut ready = Vec::new();
+
+    while let Some(job) = queue.dequeue() {
+        if job.ready {
+            ready.push(job.name);
+        }
+    }
+
+    ready
+}
+
+struct Job {
+    name: &'static str,
+    ready: bool,
+}
+
+impl Job {
+    fn new(name: &'static str, ready: bool) -> Self {
+        Self { name, ready }
+    }
+}

examples/soluciones/queue_round_robin.rs

@@ -0,0 +1,39 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut queue = Queue::new();
+    queue.enqueue(Task::new("docs", 2));
+    queue.enqueue(Task::new("tests", 1));
+
+    let completed = run_round_robin(queue);
+
+    assert_eq!(completed, vec!["tests", "docs"]);
+    println!("{completed:?}");
+}
+
+fn run_round_robin(mut queue: Queue<Task>) -> Vec<&'static str> {
+    let mut completed = Vec::new();
+
+    while let Some(mut task) = queue.dequeue() {
+        task.remaining -= 1;
+
+        if task.remaining == 0 {
+            completed.push(task.name);
+        } else {
+            queue.enqueue(task);
+        }
+    }
+
+    completed
+}
+
+struct Task {
+    name: &'static str,
+    remaining: u8,
+}
+
+impl Task {
+    fn new(name: &'static str, remaining: u8) -> Self {
+        Self { name, remaining }
+    }
+}

examples/soluciones/queue_trace_order.rs

@@ -0,0 +1,16 @@
+use rust_data_structures::queue::Queue;
+
+fn main() {
+    let mut queue = Queue::new();
+    let mut trace = Vec::new();
+
+    queue.enqueue("A");
+    queue.enqueue("B");
+    trace.push(queue.dequeue());
+    queue.enqueue("C");
+    trace.push(queue.dequeue());
+    trace.push(queue.dequeue());
+
+    assert_eq!(trace, vec![Some("A"), Some("B"), Some("C")]);
+    println!("{trace:?}");
+}