Struct CCtx 

pub struct CCtx<'a>(/* private fields */);

Compression context

It is recommended to allocate a single context per thread and re-use it for many compression operations.

Implementations

impl<'a> CCtx<'a>

pub fn try_create() -> Option<Self>

Tries to create a new context.

Returns None if zstd returns a NULL pointer - may happen if allocation fails.

With the with-rust-allocator feature enabled, the context’s internal allocations go through Rust’s global allocator instead of the C runtime’s malloc.

pub fn create() -> Self

Wrap ZSTD_createCCtx

Panics

If zstd returns a NULL pointer.

pub fn compress<C: WriteBuf + ?Sized>( &mut self, dst: &mut C, src: &[u8], compression_level: CompressionLevel, ) -> SafeResult

Wraps the ZSTD_compressCCtx() function

pub fn compress2<C: WriteBuf + ?Sized>( &mut self, dst: &mut C, src: &[u8], ) -> SafeResult

Wraps the ZSTD_compress2() function.

pub fn compress_using_dict<C: WriteBuf + ?Sized>( &mut self, dst: &mut C, src: &[u8], dict: &[u8], compression_level: CompressionLevel, ) -> SafeResult

Wraps the ZSTD_compress_usingDict() function.

pub fn compress_using_cdict<C: WriteBuf + ?Sized>( &mut self, dst: &mut C, src: &[u8], cdict: &CDict<'_>, ) -> SafeResult

Wraps the ZSTD_compress_usingCDict() function.

pub fn init(&mut self, compression_level: CompressionLevel) -> SafeResult

Initializes the context with the given compression level.

This is equivalent to running:

• reset()
• set_parameter(CompressionLevel, compression_level)

Fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn init_src_size( &mut self, compression_level: CompressionLevel, pledged_src_size: u64, ) -> SafeResult

👎Deprecated:

Use reset, set_parameter, and set_pledged_src_size instead.

Available on crate feature experimental only.

Wraps the ZSTD_initCStream_srcSize() function.

pub fn init_using_dict( &mut self, dict: &[u8], compression_level: CompressionLevel, ) -> SafeResult

👎Deprecated:

Use reset, set_parameter, and load_dictionary instead.

Available on crate feature experimental only.

Wraps the ZSTD_initCStream_usingDict() function.

pub fn init_using_cdict<'b>(&mut self, cdict: &'a CDict<'b>) -> SafeResult

where 'b: 'a,

👎Deprecated:

Use reset and ref_cdict instead.

Available on crate feature experimental only.

Wraps the ZSTD_initCStream_usingCDict() function.

Dictionary must outlive the context.

fn compressor() -> zstd_safe::CCtx<'static> {
    let cdict = zstd_safe::CDict::create(b"dictionary", 3);
    let mut cctx = zstd_safe::CCtx::create();
    cctx.init_using_cdict(&cdict).unwrap();
    cctx // `cdict` would be dropped while `cctx` still points at it.
}

pub fn load_dictionary(&mut self, dict: &[u8]) -> SafeResult

Tries to load a dictionary.

The dictionary content will be copied internally and does not need to be kept alive after calling this function.

If you need to use the same dictionary for multiple contexts, it may be more efficient to create a CDict first, then loads that.

The dictionary will apply to all compressed frames, until a new dictionary is set.

Fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn ref_cdict<'b>(&mut self, cdict: &'a CDict<'b>) -> SafeResult

where 'b: 'a,

Wraps the ZSTD_CCtx_refCDict() function.

Dictionary must outlive the context.

Fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn disable_dictionary(&mut self) -> SafeResult

Return to “no-dictionary” mode.

This will disable any dictionary/prefix previously registered for future frames.

Fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn ref_prefix<'b>(&mut self, prefix: &'b [u8]) -> SafeResult

where 'b: 'a,

Use some prefix as single-use dictionary for the next compressed frame.

Just like a dictionary, decompression will need to be given the same prefix.

This is best used if the “prefix” looks like the data to be compressed.

Fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn compress_stream<C: WriteBuf + ?Sized>( &mut self, output: &mut OutBuffer<'_, C>, input: &mut InBuffer<'_>, ) -> SafeResult

Performs a step of a streaming compression operation.

This will read some data from input and/or write some data to output.

Returns

A hint for the “ideal” amount of input data to provide in the next call.

This hint is only for performance purposes.

Wraps the ZSTD_compressStream() function.

pub fn compress_stream2<C: WriteBuf + ?Sized>( &mut self, output: &mut OutBuffer<'_, C>, input: &mut InBuffer<'_>, end_op: ZSTD_EndDirective, ) -> SafeResult

Performs a step of a streaming compression operation.

This will read some data from input and/or write some data to output.

The end_op directive can be used to specify what to do after: nothing special, flush internal buffers, or end the frame.

Returns

An lower bound for the amount of data that still needs to be flushed out.

This is useful when flushing or ending the frame: you need to keep calling this function until it returns 0.

Wraps the ZSTD_compressStream2() function.

pub fn flush_stream<C: WriteBuf + ?Sized>( &mut self, output: &mut OutBuffer<'_, C>, ) -> SafeResult

Flush any intermediate buffer.

To fully flush, you should keep calling this function until it returns Ok(0).

Wraps the ZSTD_flushStream() function.

pub fn end_stream<C: WriteBuf + ?Sized>( &mut self, output: &mut OutBuffer<'_, C>, ) -> SafeResult

Ends the stream.

You should keep calling this function until it returns Ok(0).

Wraps the ZSTD_endStream() function.

pub fn wait_for_workers(&mut self) -> SafeResult

Abandons the current frame, if any, and waits for the worker threads to be done with it.

When a multithreaded frame (see CParameter::NbWorkers) is left unfinished - abandoned, or interrupted by an error - its jobs may still be running, reading the dictionary. zstd only waits for them when the next frame starts or when the context is dropped. Until then, anything that would unload the dictionary or change NbWorkers fails with a stage_wrong error instead: load_dictionary(), ref_cdict(), ref_prefix(), disable_dictionary(), init(), and reset() with parameters.

Calling this first lets them succeed. Like reset(SessionOnly), it discards the current frame and any pledged source size, and keeps parameters and dictionary. It does nothing if no multithreaded frame is unfinished.

pub fn sizeof(&self) -> usize

Returns the size currently used by this context.

This may change over time.

pub fn reset(&mut self, reset: ResetDirective) -> SafeResult

Resets the state of the context.

Depending on the reset mode, it can reset the session, the parameters, or both.

Resetting the parameters also unloads the dictionary: this fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers(). Resetting only the session never does.

Wraps the ZSTD_CCtx_reset() function.

pub fn set_parameter(&mut self, param: CParameter) -> SafeResult

Sets a compression parameter.

Some of these parameters need to be set during de-compression as well.

Changing NbWorkers fails while a multithreaded frame is left unfinished, see CCtx::wait_for_workers().

pub fn set_pledged_src_size( &mut self, pledged_src_size: Option<u64>, ) -> SafeResult

Guarantee that the input size will be this value.

If given None, assumes the size is unknown.

Unless explicitly disabled, this will cause the size to be written in the compressed frame header.

If the actual data given to compress has a different size, an error will be returned.

pub fn try_clone( &self, pledged_src_size: Option<u64>, ) -> Result<Self, ErrorCode>

👎Deprecated:

Context copying is deprecated by zstd; create a new context and configure it instead.

Available on crate feature experimental only.

Creates a copy of this context.

This only works before any data has been compressed. An error will be returned otherwise. A poisoned context cannot be cloned until its session is reset. A context on which NbWorkers was ever set to a non-zero value cannot be cloned anymore.

pub fn get_block_size(&self) -> usize

👎Deprecated:

The block API is deprecated; use the normal compression API instead.

Available on crate feature experimental only.

Wraps the ZSTD_getBlockSize() function.

pub unsafe fn compress_block<C: WriteBuf + ?Sized>( &mut self, dst: &mut C, src: &[u8], ) -> SafeResult

👎Deprecated:

The block API is deprecated; use compress_stream2 instead.

Available on crate feature experimental only.

Wraps the ZSTD_compressBlock() function.

Returns an error once NbWorkers was set to a non-zero value on this context.

Safety

src becomes this context’s history window, so it must stay allocated and unmodified until the next call to compress_block on this context (or until this context is dropped), as the following block is compressed against it.

pub fn in_size() -> usize

Returns the recommended input buffer size.

Using this size may result in minor performance boost.

pub fn out_size() -> usize

Returns the recommended output buffer size.

Using this may result in minor performance boost.

pub fn get_frame_progression(&self) -> FrameProgression

Available on crate feature experimental only.

Trait Implementations

impl Default for CCtx<'_>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Drop for CCtx<'a>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for CCtx<'_>

impl Sync for CCtx<'_>