Struct ParcodeOptions 

pub struct ParcodeOptions { /* private fields */ }

Builder for configuring serialization options (compression, etc.).

This struct provides a builder-style API for configuring serialization parameters and executing read/write operations. It is designed to be lightweight and can be constructed multiple times without significant overhead.

Configuration Options

• Compression: Enable or disable compression (default: disabled). When enabled, the library uses the default compression algorithm (LZ4 if the lz4_flex feature is enabled, otherwise no compression).

Examples

Basic Usage

use parcode::Parcode;

let data = vec![1, 2, 3];
Parcode::save("data_basic.par", &data).unwrap();
let loaded: Vec<i32> = Parcode::load("data_basic.par").unwrap();

Performance Notes

• The builder itself has negligible overhead (it’s just a small struct with flags)
• Compression trades CPU time for reduced I/O and storage
• Parallel execution scales with the number of independent chunks in your data

Implementations

impl ParcodeOptions

pub fn compression(self, enable: bool) -> Self

Enables or disables compression for all chunks.

When compression is enabled, the library will use the default compression algorithm to reduce the size of serialized chunks. The actual algorithm used depends on which features are enabled:

• If the lz4_flex feature is enabled: LZ4 compression (fast, moderate ratio)
• Otherwise: No compression (pass-through)

Parameters

• enable: Whether to enable compression

Returns

Returns self to allow method chaining.

Trade-offs

• Enabled: Smaller files, lower I/O bandwidth, higher CPU usage
• Disabled: Larger files, higher I/O bandwidth, lower CPU usage

Examples

use parcode::{Parcode, ParcodeObject};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, ParcodeObject)]
struct MyData { val: i32 }
let my_data = MyData { val: 42 };

// Enable compression
Parcode::builder()
    .compression(true)
    .save("data.par", &my_data)?;

Performance Notes

• LZ4 compression typically achieves 2-3x compression ratios on structured data with minimal CPU overhead. For data that doesn’t compress well (e.g., already compressed images), the overhead may outweigh the benefits.

pub fn save<T, P>(&self, path: P, root_object: &T) -> Result<()>

where T: ParcodeVisitor + Sync, P: AsRef<Path>,

Serializes an object graph to disk with the configured settings.

This method performs the complete serialization pipeline:

1. Graph Construction: Analyzes the object structure and builds a dependency graph
2. Parallel Execution: Processes independent chunks concurrently using Rayon
3. Compression: Applies compression to each chunk (if enabled)
4. I/O: Writes chunks to disk in a bottom-up order
5. Header Writing: Appends the global header pointing to the root chunk

Type Parameters

• 'a: The lifetime of the object being serialized. The graph borrows from the object, enabling zero-copy serialization.
• T: The type to serialize. Must implement ParcodeVisitor and Sync (for parallel execution).
• P: The path type (anything that implements AsRef<Path>).

Parameters

• path: The file path to write to. If the file exists, it will be truncated.
• root_object: A reference to the object to serialize. This reference must remain valid for the entire duration of the serialization process.

Returns

Returns Ok(()) on success.

Errors

This method can fail if:

• The file cannot be created (e.g., permission denied, disk full)
• Serialization fails (e.g., bincode error)
• Compression fails
• I/O errors occur during writing
• The graph contains cycles (should not happen with valid ParcodeVisitor implementations)

Examples

use parcode::Parcode;

let data = vec![1, 2, 3, 4, 5];

// Write with compression
Parcode::save("data_write.par", &data)?;

Performance Characteristics

• Parallelism: Scales with the number of independent chunks (typically O(cores))
• Memory: Uses zero-copy where possible; peak memory is proportional to the largest chunk plus buffer overhead
• I/O: Buffered writes (16MB buffer) minimize syscalls
• Compression: LZ4 compression adds ~10-20% CPU overhead but can reduce I/O by 2-3x

Serializes an object graph to disk with the configured settings.

This is a convenience wrapper around write that handles file creation.

pub fn write<'a, T, W>(&self, writer: W, root_object: &'a T) -> Result<()>

where T: ParcodeVisitor + Sync, W: Write + Send,

Serializes the object graph to a generic writer (File, Vec<u8>, TcpStream, etc).

This method performs the complete serialization pipeline:

1. Graph Construction: Analyzes the object structure and builds a dependency graph
2. Parallel Execution: Processes independent chunks concurrently using Rayon
3. Compression: Applies compression to each chunk (if enabled)
4. I/O: Writes chunks to the writer in a bottom-up order
5. Header Writing: Appends the global header pointing to the root chunk

Type Parameters

• 'a: The lifetime of the object being serialized. The graph borrows from the object, enabling zero-copy serialization.

Thread Safety

• T: The type to serialize. Must implement ParcodeVisitor + Sync.
• W: The writer type. Must implement Write + Send.

Parameters

• writer: The destination to write to.
• root_object: A reference to the object to serialize.

Returns

Returns Ok(()) on success.

Errors

This method can fail if:

• Serialization fails (e.g., bincode error)
• Compression fails
• I/O errors occur during writing to the writer

Examples

use parcode::Parcode;

let data = vec![1, 2, 3];
let mut buffer = Vec::new();

Parcode::builder()
    .write(&mut buffer, &data)?;

pub fn save_sync<T, P>(&self, path: P, root_object: &T) -> Result<()>

where T: ParcodeVisitor, P: AsRef<Path>,

Serializes an object synchronously (single-threaded).

This method is useful for:

• Environments where spawning threads is expensive or restricted (WASM, embeddedish).
• Debugging serialization logic without concurrency noise.
• Benchmarking vs Parallel implementation.

It uses less memory than write because it reuses a single compression buffer.

pub fn write_sync<'a, T, W>(&self, writer: W, root_object: &'a T) -> Result<()>

where T: ParcodeVisitor, W: Write + Send,

Serializes the object graph to a generic writer synchronously.

This method is equivalent to Self::write but avoids parallel execution.

Trait Implementations

impl Debug for ParcodeOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ParcodeOptions

fn default() -> ParcodeOptions

Returns the “default value” for a type.