CompressionBlock Base Class

Relevant source files

• src/CompressionBlock.cs
• src/CompressionBlockFactory.cs
• src/CompressionResultCode.cs
• src/Copy/CopyBlock.cs
• src/HashAlgorithmGC.cs

The CompressionBlock abstract class serves as the foundation for all block-based (one-shot) compression and decompression operations within GrindCore.net. Unlike stream-based compression, which processes data incrementally, block-based implementations operate on a single discrete unit of data at a time, making them ideal for scenarios requiring fine-grained control over memory alignment or parallel processing of independent chunks.

Core Implementation and Interface

CompressionBlock src/CompressionBlock.cs17-18 implements IDisposable and provides the standardized API for all algorithm-specific block implementations. It manages the lifecycle of the compression state and provides high-level Compress and Decompress methods that wrap internal abstract logic.

Key Properties and State

• Options: A CompressionOptions object containing the configuration (algorithm, version, block size) used to initialize the block src/CompressionBlock.cs23
• CompressionType: The resolved compression level (e.g., Fastest, Optimal, or a specific numeric level) src/CompressionBlock.cs28
• RequiredCompressOutputSize: An abstract property that each implementation must override to calculate the maximum possible size of the compressed output for a given input block size src/CompressionBlock.cs38
• Properties: Optional byte array for storing algorithm-specific initialization data (common in LZMA/LZMA2) src/CompressionBlock.cs33

Lifecycle and Configuration

The constructor src/CompressionBlock.cs52-71 resolves the CompressionType based on the provided CompressionOptions. It maps logical levels like Optimal or Fastest to concrete numeric values defined in the algorithm's CompressionDefaults src/CompressionBlock.cs62-68

Sources: src/CompressionBlock.cs17-71

---

Data Flow and Method Execution

The public Compress and Decompress methods provide a safe entry point by validating buffer boundaries before delegating to internal "On" methods.

Compression Flow

1. Validation: Compress checks that the source and destination buffers are non-null and that offsets/counts are within array bounds src/CompressionBlock.cs146-160
2. DataBlock Creation: The raw buffers are wrapped in DataBlock structures src/CompressionBlock.cs162-163
3. OnCompress: The implementation-specific logic is executed via the abstract OnCompress method src/CompressionBlock.cs80 src/CompressionBlock.cs164
4. Result: Returns a CompressionResultCode and updates dstCount with the actual number of bytes written src/CompressionBlock.cs164

Decompression Flow

Similarly, Decompress src/CompressionBlock.cs109-131 validates inputs and invokes OnDecompress src/CompressionBlock.cs89 src/CompressionBlock.cs130

Sources: src/CompressionBlock.cs80-165

---

Code Entity Association: Block Architecture

The following diagram bridges the abstract base class concepts to concrete implementation entities and the factory that produces them.

Block Hierarchy and Factory Dispatch

Sources: src/CompressionBlock.cs17-165 src/CompressionBlockFactory.cs16-33 src/Copy/CopyBlock.cs9

---

Implementation Specifics

Different algorithms calculate their required output buffers and handle interop differently. The CompressionBlockFactory maps CompressionAlgorithm enums to these specific classes src/CompressionBlockFactory.cs18-33

Implementation	RequiredCompressOutputSize Calculation	Logic / Native Call
CopyBlock	blockSize (No overhead) src/Copy/CopyBlock.cs29	DataBlock.CopyTo src/Copy/CopyBlock.cs47
Lz4Block	bs + (bs / 255) + 16	SZ_Lz4_v1_10_0_CompressFastContinue
BrotliBlock	bs + (bs >> 1) + 0x10	DN9_BRT_v1_1_0_BrotliEncoderCompress
FastLzma2Block	FL2_compressBound(bs)	FL2_compressCCtx
ZStdBlock	isize + (isize >> 7) + 128	SZ_ZStd_v1_5_7_CompressBlock

Sources: src/CompressionBlock.cs38 src/Copy/CopyBlock.cs14-47 src/CompressionBlockFactory.cs18-33

---

CompressionResultCode

All block operations return a CompressionResultCode src/CompressionResultCode.cs6-37 to indicate the status of the operation. Implementations are responsible for mapping native return codes to these unified enums.

Enum Value	Description
Success	Operation completed successfully (0) src/CompressionResultCode.cs11
Error	Unknown or generic failure (-1) src/CompressionResultCode.cs16
InsufficientBuffer	Destination buffer is too small to hold the output (-2) src/CompressionResultCode.cs21
InvalidData	Source data is corrupted or cannot be processed (-3) src/CompressionResultCode.cs26
InvalidParameter	Provided arguments are invalid (-4) src/CompressionResultCode.cs31
NotSupported	The requested version or operation is not supported (-5) src/CompressionResultCode.cs36

Sources: src/CompressionResultCode.cs6-37

---

Block vs. Stream Implementations

While CompressionStream manages stateful, multi-step processing with internal buffers, CompressionBlock is designed for stateless or "one-shot" operations.

Data Handling Logic

1. Context Lifecycle: Block implementations often operate without the persistent state required for incremental streaming. For example, CopyBlock simply performs a memory copy via DataBlock.CopyTo src/Copy/CopyBlock.cs47
2. Memory Management: Blocks operate directly on DataBlock src/CompressionBlock.cs128-129 which provides access to byte arrays without the overhead of stream position tracking.
3. Error Handling: In blocks, an InsufficientBuffer result is immediately returned to the caller src/CompressionResultCode.cs21 whereas streams typically handle buffer expansion or flushing internally.

Sources: src/CompressionBlock.cs128-129 src/Copy/CopyBlock.cs41-50 src/CompressionResultCode.cs6-37