Add safety docs for BreakLoop::breakloop

Author: cai-william

src/capture/activated/mod.rs

@@ -364,9 +364,21 @@ pub struct BreakLoop {
     handle: Weak<Handle>,
 }
 
+unsafe impl Send for BreakLoop {}
+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.
+    ///
+    /// # Safety
+    ///
+    /// Can be called from any thread, but **must not** be used inside a
+    /// signal handler unless the owning `Capture` is guaranteed to still
+    /// be alive.
+    ///
+    /// The signal handler should defer the execution of `BreakLoop::breakloop()`
+    /// to a thread instead for safety.
     pub fn breakloop(&self) {
         if let Some(handle) = self.handle.upgrade() {
             unsafe { raw::pcap_breakloop(handle.as_ptr()) };

src/capture/mod.rs

@@ -105,18 +105,17 @@ impl Handle {
     }
 }
 
+// `PcapHandle` is safe to Send as it encapsulates the entire lifetime of `raw::pcap_t *`, but it is
+// not safe to Sync as libpcap does not promise thread-safe access to the same `raw::pcap_t *` from
+// multiple threads.
 unsafe impl Send for Handle {}
-unsafe impl Sync for Handle {}
 
 impl Drop for Handle {
     fn drop(&mut self) {
         unsafe { raw::pcap_close(self.handle.as_ptr()) }
     }
 }
 
-// A Capture is safe to Send as it encapsulates the entire lifetime of `raw::pcap_t *`, but it is
-// not safe to Sync as libpcap does not promise thread-safe access to the same `raw::pcap_t *` from
-// multiple threads.
 unsafe impl<T: State + ?Sized> Send for Capture<T> {}
 
 impl<T: State + ?Sized> From<NonNull<raw::pcap_t>> for Capture<T> {