# LCPFS Examples
This directory contains runnable examples demonstrating LCPFS usage.
## Running Examples
From the `lcpfs` directory:
```bash
# Basic example (no features required)
cargo run --example basic_pool
# Snapshots workflow
cargo run --example snapshots
# Compression (requires std feature for ZSTD/LZMA)
cargo run --example compression --features std
# Advanced features
cargo run --example advanced
```
## Example Descriptions
### 1. `basic_pool.rs` - Basic Pool Operations
**What it demonstrates:**
- Creating a pool
- Creating and writing files
- Reading files back
- Directory operations
- Proper resource cleanup
**Key API calls:**
- `Pool::create_pool()`
- `pool.create()`, `pool.write()`, `pool.read()`, `pool.close()`
- `pool.mkdir()`, `pool.readdir()`
**Run time:** ~1 second
**Prerequisites:** None (works with default features)
---
### 2. `snapshots.rs` - Snapshot Workflows
**What it demonstrates:**
- Creating snapshots (instant, O(1) operation)
- Rolling back to previous states
- Listing snapshots
- Full send/receive replication
- Incremental send/receive (only deltas)
- Destroying snapshots
**Key API calls:**
- `pool.snapshot()`
- `pool.rollback()`
- `pool.list_snapshots()`
- `pool.send_snapshot()`
- `pool.send_snapshot_incremental()`
- `pool.destroy_snapshot()`
**Run time:** ~2 seconds
**Prerequisites:** None
**Output highlights:**
- Demonstrates snapshot creation is instant
- Shows incremental streams are much smaller than full streams
- Verifies rollback restores exact previous state
---
### 3. `compression.rs` - Compression Tiers
**What it demonstrates:**
- LZ4 compression (universal, no_std)
- ZSTD compression (std feature)
- LZMA compression (std feature)
- Automatic algorithm selection
- Compression ratio measurement
- Handling incompressible data
**Test cases:**
- Highly compressible (zeros): ~50:1 ratio
- Repeated patterns: ~10-20:1 ratio
- Text data: ~3-5:1 ratio
- Random data: 1:1 (stored uncompressed)
- Mixed data: ~2-3:1 average
**Key API calls:**
- Same write/read operations - compression is transparent!
- No special API required - automatic based on data
**Run time:** ~1 second
**Prerequisites:**
- Basic: LZ4 only (default)
- Full: Run with `--features std` for ZSTD/LZMA
**Output highlights:**
- Shows compression is completely transparent
- Demonstrates data integrity after compression/decompression
- Explains when each algorithm is appropriate
---
### 4. `advanced.rs` - Advanced Features
**What it demonstrates:**
- Datasets and hierarchical namespaces
- Properties (get/set/inherit)
- Clones (writable snapshot copies)
- ZVOL (block device emulation)
- ARC cache statistics
**Key concepts:**
**Datasets:**
- `mypool/home/user1` - hierarchical namespace
- Property inheritance from parent datasets
- Per-dataset quotas and compression settings
**Clones:**
- Create writable copies from snapshots
- Useful for testing/development environments
- Independent modifications without affecting original
**ZVOL:**
- Block device emulation (swap, databases, VMs)
- 128K blocks for swap (optimal paging)
- 8K blocks for PostgreSQL (matches page size)
**ARC Statistics:**
- Cache hit/miss tracking
- T1 (recency) vs T2 (frequency) distribution
- Hit rate calculation
**Key API calls:**
- `pool.create_dataset()`, `pool.list_datasets()`
- `pool.set_property()`, `pool.get_property()`
- `pool.clone_dataset()`
- `pool.create_zvol()`, `pool.zvol_write_block()`
- `pool.get_arc_stats()`
**Run time:** ~3 seconds
**Prerequisites:** None
**Output highlights:**
- Shows complete dataset hierarchy
- Demonstrates property inheritance
- Explains ZVOL use cases
- Reports actual cache performance
---
## Common Patterns
### Error Handling
All examples use `?` operator with `FsResult<()>`:
```rust
fn main() -> FsResult<()> {
let mut pool = Pool::create_pool(0, "mypool")?;
// ... operations that can fail ...
Ok(())
}
```
### Resource Cleanup
File descriptors must be closed:
```rust
let fd = pool.create("/file.txt", 0o644)?;
pool.write(fd, b"data")?;
pool.close(fd)?; // Always close!
```
### Snapshot Naming
Snapshots are named relative to pool:
```rust
pool.snapshot("baseline")?; // Creates mypool@baseline
pool.rollback("baseline")?; // Rollback to mypool@baseline
```
### Property Values
Properties are strings (for flexibility):
```rust
pool.set_property("mypool/home", "quota", "10737418240")?; // 10 GB as string
pool.set_property("mypool/home", "compression", "lz4")?;
```
## Troubleshooting
**"Pool already exists" error:**
- Each example creates a pool named "mypool"
- Run examples sequentially, not in parallel
- If needed, modify pool names to be unique
**"Feature not available" error:**
- Some features require `std` or `lunaos` features
- Check example prerequisites above
- Run with appropriate feature flags
**Compilation errors:**
- Ensure you're in the `lcpfs` directory
- Check Rust version: requires 1.70+
- Try `cargo clean` and rebuild
## Next Steps
After running these examples:
1. **Read the API documentation:** `cargo doc --open`
2. **Explore the tests:** `src/lib.rs` has 43 integration tests
3. **Check the module docs:** Each module has detailed rustdoc
4. **Review the architecture:** README.md has architecture diagrams
## Integration Guide
To integrate LCPFS in your kernel:
```toml
[dependencies]
lcpfs = { version = "2026.1", default-features = false }
```
For userspace with advanced compression:
```toml
[dependencies]
lcpfs = { version = "2026.1", features = ["std"] }
```
For LunaOS with adaptive features:
```toml
[dependencies]
lcpfs = { version = "2026.1", features = ["std", "lunaos"] }
```
See main README.md for complete documentation.