Skip to content

Commit 9bf1692

Browse files
gyscosclaude
andcommitted
Say why the Send and Sync impls hold
Most of these were bare. Two rationales cover nearly all of them: the C object is an owned heap allocation with nothing thread-local in it, and everything that mutates it goes through `&mut self`. The dictionaries get their own note - they are immutable once built, which zstd.h states outright for ZSTD_CDict - and the thread pool gets one for being designed to be shared, with its queue under an internal mutex. Also correct the note next to `CStream`, which claimed it does not implement Sync. It is an alias for `CCtx`, so it always has. Comments only, no behaviour change. Raised in the audit appendix of #366; these are written from the code rather than taken from the report. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01TeZDBS4Uw5kdF77tkJ7cAe
1 parent 681bcc3 commit 9bf1692

2 files changed

Lines changed: 37 additions & 2 deletions

File tree

‎zstd-safe/src/lib.rs‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -871,11 +871,22 @@ impl<'a> Drop for CCtx<'a> {
871871
}
872872
}
873873

874+
// Safety: the context is a plain heap allocation this handle owns; zstd keeps
875+
// no thread-local state for it, so it can be moved between threads.
874876
unsafe impl Send for CCtx<'_> {}
875-
// Non thread-safe methods already take `&mut self`, so it's fine to implement Sync here.
877+
// Safety: every method that mutates the context takes `&mut self`, so a shared
878+
// `&CCtx` only ever reads. There is no interior mutability to race on.
876879
unsafe impl Sync for CCtx<'_> {}
877880

881+
/// Converts a zstd-owned C string to a `str`.
882+
///
883+
/// # Safety
884+
///
885+
/// `text` must point to a nul-terminated C string that lives for the rest of
886+
/// the program - which is what the zstd functions this is used with return,
887+
/// as they hand back pointers to static string literals.
878888
unsafe fn c_char_to_str(text: *const c_char) -> &'static str {
889+
// Safety: guaranteed by the caller, see above.
879890
core::ffi::CStr::from_ptr(text)
880891
.to_str()
881892
.expect("bad error message from zstd")
@@ -1285,8 +1296,10 @@ impl Drop for DCtx<'_> {
12851296
}
12861297
}
12871298

1299+
// Safety: as for `CCtx` - an owned heap allocation with no thread-local state.
12881300
unsafe impl Send for DCtx<'_> {}
12891301
// Non thread-safe methods already take `&mut self`, so it's fine to implement Sync here.
1302+
// Safety: as for `CCtx` - the mutating methods all take `&mut self`.
12901303
unsafe impl Sync for DCtx<'_> {}
12911304

12921305
/// Compression dictionary.
@@ -1385,6 +1398,9 @@ impl<'a> Drop for CDict<'a> {
13851398
}
13861399
}
13871400

1401+
// Safety: a digested dictionary is immutable once built. zstd.h: "ZSTD_CDict
1402+
// can be created once and shared by multiple threads concurrently, since its
1403+
// usage is read-only".
13881404
unsafe impl<'a> Send for CDict<'a> {}
13891405
unsafe impl<'a> Sync for CDict<'a> {}
13901406

@@ -1468,6 +1484,8 @@ impl<'a> Drop for DDict<'a> {
14681484
}
14691485
}
14701486

1487+
// Safety: like `CDict`, a digested dictionary is only read once built - the
1488+
// contexts referencing it never write to it.
14711489
unsafe impl<'a> Send for DDict<'a> {}
14721490
unsafe impl<'a> Sync for DDict<'a> {}
14731491

@@ -1521,12 +1539,17 @@ impl Drop for ThreadPool {
15211539
feature = "doc-cfg",
15221540
doc(cfg(all(feature = "experimental", feature = "zstdmt")))
15231541
)]
1542+
// Safety: the pool owns its worker threads and the queue guarding them; none
1543+
// of that is tied to the thread that created it.
15241544
unsafe impl Send for ThreadPool {}
15251545
#[cfg(all(feature = "experimental", feature = "zstdmt"))]
15261546
#[cfg_attr(
15271547
feature = "doc-cfg",
15281548
doc(cfg(all(feature = "experimental", feature = "zstdmt")))
15291549
)]
1550+
// Safety: sharing is what the pool is for - zstd.h offers these functions to
1551+
// "share a thread pool among multiple compression contexts" - and its work
1552+
// queue is guarded by an internal mutex.
15301553
unsafe impl Sync for ThreadPool {}
15311554

15321555
/// Wraps the `ZSTD_decompress_usingDDict()` function.
@@ -1544,7 +1567,7 @@ pub fn decompress_using_ddict(
15441567
/// Same as `CCtx`.
15451568
pub type CStream<'a> = CCtx<'a>;
15461569

1547-
// CStream can't be shared across threads, so it does not implement Sync.
1570+
// `CStream` is an alias for `CCtx`, and shares its `Send` and `Sync` impls.
15481571

15491572
/// Allocates a new `CStream`.
15501573
pub fn create_cstream<'a>() -> CStream<'a> {

‎zstd-safe/src/seekable.rs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ impl core::fmt::Display for FrameIndexTooLargeError {
2828
/// to start a new compression operation call `init()`.
2929
pub struct SeekableCStream(NonNull<zstd_sys::ZSTD_seekable_CStream>);
3030

31+
// Safety: the stream is an owned heap allocation with no thread-local state,
32+
// and every method that advances it takes `&mut self`.
3133
unsafe impl Send for SeekableCStream {}
3234
unsafe impl Sync for SeekableCStream {}
3335

@@ -175,6 +177,8 @@ impl Drop for SeekableCStream {
175177
/// afterward into a seekable archive.
176178
pub struct FrameLog(NonNull<zstd_sys::ZSTD_frameLog>);
177179

180+
// Safety: as for `SeekableCStream` - owned, not thread-bound, and only mutated
181+
// through `&mut self`.
178182
unsafe impl Send for FrameLog {}
179183
unsafe impl Sync for FrameLog {}
180184

@@ -259,6 +263,8 @@ impl Drop for FrameLog {
259263
/// The lifetime references the potential buffer that holds the data of this seekable.
260264
pub struct Seekable<'a>(NonNull<zstd_sys::ZSTD_seekable>, PhantomData<&'a ()>);
261265

266+
// Safety: as for `SeekableCStream`. Note the decompression methods, which do
267+
// drive the C context, all take `&mut self`.
262268
unsafe impl Send for Seekable<'_> {}
263269
unsafe impl Sync for Seekable<'_> {}
264270

@@ -456,8 +462,13 @@ pub struct AdvancedSeekable<'a, F> {
456462
}
457463

458464
#[cfg(feature = "std")]
465+
// Safety: this owns both the `Seekable`, which is `Send`, and the `F` behind
466+
// `src`, so it can move between threads exactly when `F` can.
459467
unsafe impl<F> Send for AdvancedSeekable<'_, F> where F: Send {}
460468
#[cfg(feature = "std")]
469+
// Safety: `F` is only ever reached from the C callbacks, which run under the
470+
// `&mut self` methods, so a shared reference here never touches it. The `F:
471+
// Sync` bound is more than that needs.
461472
unsafe impl<F> Sync for AdvancedSeekable<'_, F> where F: Sync {}
462473

463474
/// Only `Deref` is implemented, deliberately: handing out a `&mut Seekable`
@@ -625,6 +636,7 @@ impl core::fmt::Display for SeekTableCreateError {
625636

626637
pub struct SeekTable(NonNull<zstd_sys::ZSTD_seekTable>);
627638

639+
// Safety: a seek table is built once and only read afterwards.
628640
unsafe impl Send for SeekTable {}
629641
unsafe impl Sync for SeekTable {}
630642

0 commit comments

Comments
 (0)