Allow applications to abort a capture loop (pcap_breakloop)

Expose a safe `BreakLoop` handle that forwards to libpcap’s
`pcap_breakloop`. The handle stores a copy of the internal
`Arc<RwLock<bool>>` validity flag so it can be used from any thread
as long as the underlying `Capture` is still open.

* Implements @FeldrinH’s suggestion from issue #312.

* Adds `Capture::breakloop_handle(&self) -> BreakLoop`.

Fixes #312

Author: cai-william

src/capture/activated/mod.rs

@@ -12,6 +12,7 @@ use std::{
     path::Path,
     ptr::{self, NonNull},
     slice,
+    sync::{Arc, RwLock},
 };
 
 #[cfg(not(windows))]
@@ -235,6 +236,39 @@ impl<T: Activated + ?Sized> Capture<T> {
         self.check_err(return_code == 0)
     }
 
+    /// Returns a thread-safe `BreakLoop` handle for calling pcap_breakloop() on an active capture.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// // Using an active capture
+    /// use pcap::Device;
+    ///
+    /// let mut cap = Device::lookup().unwrap().unwrap().open().unwrap();
+    ///
+    /// let break_handle = cap.breakloop_handle();
+    ///
+    /// let capture_thread = std::thread::spawn(move || {
+    ///     while let Ok(packet) = cap.next_packet() {
+    ///         println!("received packet! {:?}", packet);
+    ///     }
+    /// });
+    ///
+    /// // Send break_handle to a seperate thread (i.e. could be signal handler)
+    /// std::thread::spawn(move || {
+    ///     std::thread::sleep(std::time::Duration::from_secs(1));
+    ///     break_handle.breakloop();
+    /// });
+    ///
+    /// capture_thread.join().unwrap();
+    /// ```
+    pub fn breakloop_handle(&mut self) -> BreakLoop {
+        BreakLoop {
+            handle: self.handle,
+            handle_valid: Arc::clone(&self.handle_valid),
+        }
+    }
+
     /// Compiles the string into a filter program using `pcap_compile`.
     pub fn compile(&self, program: &str, optimize: bool) -> Result<BpfProgram, Error> {
         let program = CString::new(program)?;
@@ -321,6 +355,39 @@ impl<T: Activated> From<Capture<T>> for Capture<dyn Activated> {
         unsafe { mem::transmute(cap) }
     }
 }
+/// Breakloop can safely be sent to other threads such as signal handlers to abort
+/// blocking capture loops such as `Capture::next_packet` and `Capture::for_each`.
+///
+/// See <https://www.tcpdump.org/manpages/pcap_breakloop.3pcap.html> for per-platform caveats about
+/// how breakloop can wake up blocked threads.
+pub struct BreakLoop {
+    handle: NonNull<raw::pcap_t>,
+    handle_valid: Arc<RwLock<bool>>,
+}
+
+// The `handle_valid` ensures that a valid handle is always referenced
+unsafe impl Send for BreakLoop {}
+// `pcap_breakloop()` is thread-safe
+unsafe impl Sync for BreakLoop {}
+
+impl BreakLoop {
+    /// Calls `pcap_breakloop` to make the blocking loop of a pcap capture return.
+    /// The call is a no-op if the handle is invalid.
+    pub fn breakloop(&self) {
+        if let Ok(handle_valid) = self.handle_valid.try_read() {
+            if *handle_valid {
+                //
+                // # Safety
+                //
+                // `handle_valid` is true, so the handle is valid before `pcap_breakloop`
+                // `handle_valid` lock is held for the duration of `pcap_breakloop` so the handle
+                // can't be deallocated while `pcap_breakloop` is running
+                unsafe { raw::pcap_breakloop(self.handle.as_ptr()) };
+            }
+        }
+    }
+}
+
 
 /// Abstraction for writing pcap savefiles, which can be read afterwards via `Capture::from_file()`.
 pub struct Savefile {

src/capture/mod.rs

@@ -8,6 +8,7 @@ use std::{
     ffi::CString,
     marker::PhantomData,
     ptr::{self, NonNull},
+    sync::{Arc, RwLock},
 };
 
 #[cfg(windows)]
@@ -91,6 +92,7 @@ impl State for Dead {}
 pub struct Capture<T: State + ?Sized> {
     nonblock: bool,
     handle: NonNull<raw::pcap_t>,
+    handle_valid: Arc<RwLock<bool>>,
     _marker: PhantomData<T>,
 }
 
@@ -104,6 +106,7 @@ impl<T: State + ?Sized> From<NonNull<raw::pcap_t>> for Capture<T> {
         Capture {
             nonblock: false,
             handle,
+            handle_valid: Arc::new(RwLock::new(true)),
             _marker: PhantomData,
         }
     }
@@ -180,6 +183,11 @@ impl<T: State + ?Sized> Capture<T> {
 
 impl<T: State + ?Sized> Drop for Capture<T> {
     fn drop(&mut self) {
+        let mut handle_valid = match self.handle_valid.write() {
+            Ok(g) => g,
+            Err(poison) => poison.into_inner()
+        };
+        *handle_valid = false;
         unsafe { raw::pcap_close(self.handle.as_ptr()) }
     }
 }

src/lib.rs

@@ -74,7 +74,7 @@ mod packet;
 #[cfg(not(windows))]
 pub use capture::activated::open_raw_fd;
 pub use capture::{
-    activated::{iterator::PacketIter, BpfInstruction, BpfProgram, Direction, Savefile, Stat},
+    activated::{iterator::PacketIter, BpfInstruction, BpfProgram, BreakLoop, Direction, Savefile, Stat},
     inactive::TimestampType,
     {Activated, Active, Capture, Dead, Inactive, Offline, Precision, State},
 };