@@ -92,7 +92,6 @@ const PARAMETER_UNSUPPORTED_ERROR: ErrorCode =
9292/// The error code zstd itself returns for an operation the context is in no
9393/// state to perform (`-ZSTD_error_stage_wrong` as a `size_t`), for the places
9494/// where that has to be decided on the Rust side of a call.
95- #[ cfg( feature = "experimental" ) ]
9695const STAGE_WRONG_ERROR : ErrorCode =
9796 ( zstd_sys:: ZSTD_ErrorCode :: ZSTD_error_stage_wrong as usize ) . wrapping_neg ( ) ;
9897
@@ -301,6 +300,22 @@ impl Poison {
301300 }
302301}
303302
303+ /// What a `CCtx` knows about its worker threads (`NbWorkers`).
304+ #[ derive( Clone , Copy , Debug , Default ) ]
305+ struct Workers {
306+ /// `NbWorkers` was ever set to a non-zero value, see `guard_own_tables`.
307+ ever : bool ,
308+ /// `NbWorkers` is currently set to a non-zero value.
309+ requested : bool ,
310+ /// A multithreaded frame was started and not finished.
311+ ///
312+ /// Its jobs may still be running on the worker threads, reading the
313+ /// context's dictionary and job table: zstd only waits for them when the
314+ /// next frame starts, or when the context is freed. Until then, nothing
315+ /// may free or resize what they use. See `CCtx::wait_for_workers()`.
316+ pending : bool ,
317+ }
318+
304319/// Compression context
305320///
306321/// It is recommended to allocate a single context per thread and re-use it
@@ -309,9 +324,7 @@ pub struct CCtx<'a>(
309324 NonNull < zstd_sys:: ZSTD_CCtx > ,
310325 PhantomData < & ' a ( ) > ,
311326 Poison ,
312- /// Whether `NbWorkers` was ever set to a non-zero value, see
313- /// `guard_own_tables`.
314- bool ,
327+ Workers ,
315328) ;
316329
317330impl Default for CCtx < ' _ > {
@@ -345,7 +358,7 @@ impl<'a> CCtx<'a> {
345358 NonNull :: new ( context) ?,
346359 PhantomData ,
347360 Poison :: default ( ) ,
348- false ,
361+ Workers :: default ( ) ,
349362 ) )
350363 }
351364
@@ -418,6 +431,7 @@ impl<'a> CCtx<'a> {
418431 // refuses to change the dictionary they read from), and make
419432 // streaming calls wait for an explicit reset.
420433 self . 2 . clear ( ) ;
434+ self . track_frame ( res. is_ok ( ) ) ;
421435 self . 2 . record ( res)
422436 }
423437
@@ -475,7 +489,12 @@ impl<'a> CCtx<'a> {
475489 /// This is equivalent to running:
476490 /// * `reset()`
477491 /// * `set_parameter(CompressionLevel, compression_level)`
492+ ///
493+ /// Fails while a multithreaded frame is left unfinished, see
494+ /// [`CCtx::wait_for_workers()`].
478495 pub fn init ( & mut self , compression_level : CompressionLevel ) -> SafeResult {
496+ // This also unloads the dictionary.
497+ self . guard_workers ( ) ?;
479498 self . 2 . clear ( ) ;
480499 // Safety: Just FFI
481500 let code = unsafe {
@@ -495,6 +514,7 @@ impl<'a> CCtx<'a> {
495514 compression_level : CompressionLevel ,
496515 pledged_src_size : u64 ,
497516 ) -> SafeResult {
517+ self . guard_workers ( ) ?;
498518 self . 2 . clear ( ) ;
499519 // Safety: Just FFI
500520 let code = unsafe {
@@ -518,7 +538,7 @@ impl<'a> CCtx<'a> {
518538 dict : & [ u8 ] ,
519539 compression_level : CompressionLevel ,
520540 ) -> SafeResult {
521- self . 2 . clear ( ) ;
541+ self . guard_workers ( ) ? ;
522542 self . 2 . clear ( ) ;
523543 // Safety: Just FFI
524544 let code = unsafe {
@@ -552,6 +572,7 @@ impl<'a> CCtx<'a> {
552572 where
553573 ' b : ' a , // Dictionary outlives the stream.
554574 {
575+ self . guard_workers ( ) ?;
555576 // Safety: Just FFI
556577 let code = unsafe {
557578 zstd_sys:: ZSTD_initCStream_usingCDict (
@@ -571,7 +592,11 @@ impl<'a> CCtx<'a> {
571592 /// create a `CDict` first, then loads that.
572593 ///
573594 /// The dictionary will apply to all compressed frames, until a new dictionary is set.
595+ ///
596+ /// Fails while a multithreaded frame is left unfinished, see
597+ /// [`CCtx::wait_for_workers()`].
574598 pub fn load_dictionary ( & mut self , dict : & [ u8 ] ) -> SafeResult {
599+ self . guard_workers ( ) ?;
575600 // Safety: Just FFI
576601 parse_code ( unsafe {
577602 zstd_sys:: ZSTD_CCtx_loadDictionary (
@@ -585,10 +610,14 @@ impl<'a> CCtx<'a> {
585610 /// Wraps the `ZSTD_CCtx_refCDict()` function.
586611 ///
587612 /// Dictionary must outlive the context.
613+ ///
614+ /// Fails while a multithreaded frame is left unfinished, see
615+ /// [`CCtx::wait_for_workers()`].
588616 pub fn ref_cdict < ' b > ( & mut self , cdict : & ' a CDict < ' b > ) -> SafeResult
589617 where
590618 ' b : ' a ,
591619 {
620+ self . guard_workers ( ) ?;
592621 // Safety: Just FFI
593622 parse_code ( unsafe {
594623 zstd_sys:: ZSTD_CCtx_refCDict ( self . 0 . as_ptr ( ) , cdict. 0 . as_ptr ( ) )
@@ -598,7 +627,11 @@ impl<'a> CCtx<'a> {
598627 /// Return to "no-dictionary" mode.
599628 ///
600629 /// This will disable any dictionary/prefix previously registered for future frames.
630+ ///
631+ /// Fails while a multithreaded frame is left unfinished, see
632+ /// [`CCtx::wait_for_workers()`].
601633 pub fn disable_dictionary ( & mut self ) -> SafeResult {
634+ self . guard_workers ( ) ?;
602635 // Safety: Just FFI
603636 parse_code ( unsafe {
604637 zstd_sys:: ZSTD_CCtx_loadDictionary (
@@ -614,10 +647,14 @@ impl<'a> CCtx<'a> {
614647 /// Just like a dictionary, decompression will need to be given the same prefix.
615648 ///
616649 /// This is best used if the "prefix" looks like the data to be compressed.
650+ ///
651+ /// Fails while a multithreaded frame is left unfinished, see
652+ /// [`CCtx::wait_for_workers()`].
617653 pub fn ref_prefix < ' b > ( & mut self , prefix : & ' b [ u8 ] ) -> SafeResult
618654 where
619655 ' b : ' a ,
620656 {
657+ self . guard_workers ( ) ?;
621658 // Safety: Just FFI
622659 parse_code ( unsafe {
623660 zstd_sys:: ZSTD_CCtx_refPrefix (
@@ -656,7 +693,9 @@ impl<'a> CCtx<'a> {
656693 )
657694 } ;
658695 let res = output. check ( parse_code ( code) ) ;
659- self . 2 . record ( input. check ( res) )
696+ let res = self . 2 . record ( input. check ( res) ) ;
697+ self . track_frame ( false ) ;
698+ res
660699 }
661700
662701 /// Performs a step of a streaming compression operation.
@@ -693,7 +732,11 @@ impl<'a> CCtx<'a> {
693732 )
694733 } ;
695734 let res = output. check ( parse_code ( code) ) ;
696- self . 2 . record ( input. check ( res) )
735+ let res = self . 2 . record ( input. check ( res) ) ;
736+ self . track_frame (
737+ end_op == zstd_sys:: ZSTD_EndDirective :: ZSTD_e_end && res == Ok ( 0 ) ,
738+ ) ;
739+ res
697740 }
698741
699742 /// Flush any intermediate buffer.
@@ -711,7 +754,9 @@ impl<'a> CCtx<'a> {
711754 let code = unsafe {
712755 zstd_sys:: ZSTD_flushStream ( self . 0 . as_ptr ( ) , ptr_mut ( & mut output) )
713756 } ;
714- self . 2 . record ( output. check ( parse_code ( code) ) )
757+ let res = self . 2 . record ( output. check ( parse_code ( code) ) ) ;
758+ self . track_frame ( false ) ;
759+ res
715760 }
716761
717762 /// Ends the stream.
@@ -729,7 +774,62 @@ impl<'a> CCtx<'a> {
729774 let code = unsafe {
730775 zstd_sys:: ZSTD_endStream ( self . 0 . as_ptr ( ) , ptr_mut ( & mut output) )
731776 } ;
732- self . 2 . record ( output. check ( parse_code ( code) ) )
777+ let res = self . 2 . record ( output. check ( parse_code ( code) ) ) ;
778+ self . track_frame ( res == Ok ( 0 ) ) ;
779+ res
780+ }
781+
782+ /// Records whether a streaming call left a multithreaded frame open.
783+ fn track_frame ( & mut self , frame_ended : bool ) {
784+ if self . 3 . requested {
785+ self . 3 . pending = !frame_ended;
786+ }
787+ }
788+
789+ /// Fails if worker threads may still be running jobs of an unfinished
790+ /// frame, see `Workers::pending`.
791+ fn guard_workers ( & self ) -> Result < ( ) , ErrorCode > {
792+ if self . 3 . pending {
793+ return Err ( STAGE_WRONG_ERROR ) ;
794+ }
795+ Ok ( ( ) )
796+ }
797+
798+ /// Abandons the current frame, if any, and waits for the worker threads
799+ /// to be done with it.
800+ ///
801+ /// When a multithreaded frame (see `CParameter::NbWorkers`) is left
802+ /// unfinished - abandoned, or interrupted by an error - its jobs may
803+ /// still be running, reading the dictionary. zstd only waits for them
804+ /// when the next frame starts or when the context is dropped. Until then,
805+ /// anything that would unload the dictionary or change `NbWorkers` fails
806+ /// with a `stage_wrong` error instead: `load_dictionary()`,
807+ /// `ref_cdict()`, `ref_prefix()`, `disable_dictionary()`, `init()`, and
808+ /// `reset()` with parameters.
809+ ///
810+ /// Calling this first lets them succeed. Like `reset(SessionOnly)`, it
811+ /// discards the current frame and any pledged source size, and keeps
812+ /// parameters and dictionary. It does nothing if no multithreaded frame
813+ /// is unfinished.
814+ pub fn wait_for_workers ( & mut self ) -> SafeResult {
815+ if !self . 3 . pending {
816+ return Ok ( 0 ) ;
817+ }
818+ self . reset ( ResetDirective :: SessionOnly ) ?;
819+
820+ // Starting a new frame is what makes zstd wait for the jobs of the
821+ // previous one. With no input, this one has no jobs of its own.
822+ let mut output = OutBuffer :: around ( & mut [ ] [ ..] ) ;
823+ let mut input = InBuffer :: around ( & [ ] ) ;
824+ self . compress_stream2 (
825+ & mut output,
826+ & mut input,
827+ zstd_sys:: ZSTD_EndDirective :: ZSTD_e_continue ,
828+ ) ?;
829+
830+ self . reset ( ResetDirective :: SessionOnly ) ?;
831+ self . 3 . pending = false ;
832+ Ok ( 0 )
733833 }
734834
735835 /// Returns the size currently used by this context.
@@ -744,22 +844,39 @@ impl<'a> CCtx<'a> {
744844 ///
745845 /// Depending on the reset mode, it can reset the session, the parameters, or both.
746846 ///
847+ /// Resetting the parameters also unloads the dictionary: this fails while
848+ /// a multithreaded frame is left unfinished, see
849+ /// [`CCtx::wait_for_workers()`]. Resetting only the session never does.
850+ ///
747851 /// Wraps the `ZSTD_CCtx_reset()` function.
748852 pub fn reset ( & mut self , reset : ResetDirective ) -> SafeResult {
853+ if !matches ! ( reset, ResetDirective :: SessionOnly ) {
854+ self . guard_workers ( ) ?;
855+ }
749856 // Safety: Just FFI
750857 let res = parse_code ( unsafe {
751858 zstd_sys:: ZSTD_CCtx_reset ( self . 0 . as_ptr ( ) , reset. as_sys ( ) )
752859 } ) ;
753860 if res. is_ok ( ) && reset. resets_session ( ) {
754861 self . 2 . clear ( ) ;
755862 }
863+ if res. is_ok ( ) && !matches ! ( reset, ResetDirective :: SessionOnly ) {
864+ self . 3 . requested = false ;
865+ }
756866 res
757867 }
758868
759869 /// Sets a compression parameter.
760870 ///
761871 /// Some of these parameters need to be set during de-compression as well.
872+ ///
873+ /// Changing `NbWorkers` fails while a multithreaded frame is left
874+ /// unfinished, see [`CCtx::wait_for_workers()`].
762875 pub fn set_parameter ( & mut self , param : CParameter ) -> SafeResult {
876+ if let CParameter :: NbWorkers ( _) = param {
877+ // zstd would resize the job table the old jobs still use.
878+ self . guard_workers ( ) ?;
879+ }
763880 // TODO: Until bindgen properly generates a binding for this, we'll need to do it here.
764881
765882 #[ cfg( feature = "experimental" ) ]
@@ -884,8 +1001,9 @@ impl<'a> CCtx<'a> {
8841001 let res = parse_code ( unsafe {
8851002 zstd_sys:: ZSTD_CCtx_setParameter ( self . 0 . as_ptr ( ) , param, value)
8861003 } ) ;
887- if res. is_ok ( ) && matches ! ( param, ZSTD_c_nbWorkers ) && value != 0 {
888- self . 3 = true ;
1004+ if res. is_ok ( ) && matches ! ( param, ZSTD_c_nbWorkers ) {
1005+ self . 3 . requested = value != 0 ;
1006+ self . 3 . ever |= value != 0 ;
8891007 }
8901008 res
8911009 }
@@ -924,7 +1042,7 @@ impl<'a> CCtx<'a> {
9241042 /// started.
9251043 #[ cfg( feature = "experimental" ) ]
9261044 fn guard_own_tables ( & self ) -> Result < ( ) , ErrorCode > {
927- if self . 3 {
1045+ if self . 3 . ever {
9281046 return Err ( STAGE_WRONG_ERROR ) ;
9291047 }
9301048 Ok ( ( ) )
0 commit comments