Add tests and example for BreakLoop handle

* Added unit tests to verify handle validity and behavior after capture drop or lock poisoning.

* Introduced examples/break_loop.rs demonstrating thread‑safe capture abort using breakloop_handle().

Author: cai-william

examples/breakloop.rs

@@ -0,0 +1,36 @@
+use std::{thread, time::Duration};
+
+fn main() {
+    // Get the default device
+    let device = pcap::Device::lookup()
+        .expect("device lookup failed")
+        .expect("no device available");
+    println!("Using device {}", device.name);
+
+    // Setup capture
+    let mut cap = pcap::Capture::from_device(device)
+        .unwrap()
+        .immediate_mode(true)
+        .open()
+        .unwrap();
+    println!("Using device");
+
+    let break_handle = cap.breakloop_handle();
+
+    // Start capture in a seperate thread
+    let capture_thread = thread::spawn(move || {
+        while let Ok(_) = cap.next_packet() {
+            println!("got packet!");
+        }
+        println!("capture loop exited");
+    });
+
+    // Send break_handle to a separate thread (e.g. user input, signal handler, etc.)
+    thread::spawn(move || {
+        thread::sleep(Duration::from_secs(1));
+        println!("break loop called!");
+        break_handle.breakloop();
+    });
+
+    capture_thread.join().unwrap();
+}

src/capture/activated/mod.rs

@@ -680,6 +680,63 @@ mod tests {
         }
     }
 
+    #[test]
+    fn test_breakloop_capture_dropped() {
+        let _m = RAWMTX.lock();
+
+        let mut value: isize = 1234;
+        let pcap = as_pcap_t(&mut value);
+
+        let test_capture = test_capture::<Active>(pcap);
+        let mut capture: Capture<dyn Activated> = test_capture.capture.into();
+
+        let ctx = raw::pcap_breakloop_context();
+        ctx.expect()
+            .withf_st(move |h| *h == pcap)
+            .return_const(())
+            .times(1);
+
+        let break_handle = capture.breakloop_handle();
+
+        break_handle.breakloop();
+        assert!(*break_handle.handle_valid.read().unwrap());
+
+        drop(capture);
+
+        break_handle.breakloop();  // this call does not trigger mock after drop
+        assert!(!*break_handle.handle_valid.read().unwrap());
+    }
+
+    #[test]
+    fn test_breakloop_poison_lock() {
+        let _m = RAWMTX.lock();
+
+        let mut value: isize = 1234;
+        let pcap = as_pcap_t(&mut value);
+
+        let test_capture = test_capture::<Active>(pcap);
+        let mut capture: Capture<dyn Activated> = test_capture.capture.into();
+
+        let ctx = raw::pcap_breakloop_context();
+        ctx.expect()
+            .withf_st(move |h| *h == pcap)
+            .return_const(())
+            .times(1);
+
+        let break_handle = capture.breakloop_handle();
+
+        break_handle.breakloop();
+        assert!(*break_handle.handle_valid.read().unwrap());
+
+        let _ = catch_unwind(|| {
+            let _guard = break_handle.handle_valid.write().unwrap();
+            panic!("panic to poison lock");
+        });
+
+        assert!(break_handle.handle_valid.is_poisoned());
+        break_handle.breakloop();  // this call does not trigger mock after poison
+    }
+
     #[test]
     fn test_savefile() {
         let _m = RAWMTX.lock();

src/capture/mod.rs

@@ -258,6 +258,33 @@ mod tests {
         assert_eq!(capture.as_ptr(), capture.handle.as_ptr());
     }
 
+    #[test]
+    fn test_capture_drop_poison() {
+        let _m = RAWMTX.lock();
+
+        let mut value: isize = 1234;
+        let pcap = as_pcap_t(&mut value);
+
+        let test_capture = test_capture::<Active>(pcap);
+        let capture: Capture<dyn Activated> = test_capture.capture.into();
+
+        let lock = Arc::clone(&capture.handle_valid);
+        let _ = std::panic::catch_unwind(|| {
+            let _guard = capture.handle_valid.write().unwrap();
+            panic!("panic to poison lock");
+        });
+
+        drop(capture);
+
+        // Ensure handle_valid is set to false on drop even when poisoned
+        let handle_valid = *lock
+            .read()
+            .unwrap_or_else(|e| e.into_inner());
+
+        assert!(lock.is_poisoned());
+        assert!(!handle_valid);
+    }
+
     #[test]
     #[cfg(windows)]
     fn test_min_to_copy() {