lib3mf_async/lib.rs
1//! # lib3mf-async
2//!
3//! Asynchronous I/O support for loading 3MF files using tokio.
4//!
5//! ## Overview
6//!
7//! This crate provides async/non-blocking 3MF file loading for applications that require
8//! concurrent I/O operations without blocking threads. It builds on [`lib3mf_core`] and uses
9//! tokio for async runtime and async-zip for ZIP archive handling.
10//!
11//! **When to use this crate:**
12//! - Web servers handling multiple concurrent requests
13//! - Applications with UI threads that must remain responsive during file loading
14//! - Systems processing multiple 3MF files concurrently
15//! - Any async Rust application using tokio
16//!
17//! **When to use lib3mf-core instead:**
18//! - Simple CLI tools or scripts
19//! - Single-threaded applications
20//! - Batch processing where blocking I/O is acceptable
21//! - When you don't already have a tokio runtime
22//!
23//! ## Quick Start
24//!
25//! ```no_run
26//! use lib3mf_async::loader::load_model_async;
27//! use lib3mf_core::validation::ValidationLevel;
28//!
29//! #[tokio::main]
30//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
31//! // Load a 3MF file asynchronously
32//! let model = load_model_async("model.3mf").await?;
33//!
34//! // Validate and use the model
35//! let report = model.validate(ValidationLevel::Standard);
36//! println!("Loaded {} objects", model.resources.iter_objects().count());
37//!
38//! Ok(())
39//! }
40//! ```
41//!
42//! ## Architecture
43//!
44//! The async loading pipeline consists of:
45//!
46//! 1. **Async file open**: `tokio::fs::File::open()` - non-blocking file system access
47//! 2. **Async ZIP reading**: [`AsyncZipArchive`] reads archive entries without blocking
48//! 3. **Async OPC parsing**: Relationship discovery happens with async I/O
49//! 4. **Spawn-blocked XML parsing**: CPU-bound XML parsing offloaded via `tokio::task::spawn_blocking`
50//!
51//! This hybrid approach keeps the tokio runtime responsive during I/O while leveraging blocking
52//! threads for CPU-intensive parsing work.
53//!
54//! ## Modules
55//!
56//! - [`archive`]: Async archive reader trait ([`AsyncArchiveReader`]) and trait definition
57//! - [`zip`]: Async ZIP implementation ([`AsyncZipArchive`]) using async-zip
58//! - [`loader`]: High-level model loading function ([`load_model_async`])
59//!
60//! ## Runtime Requirements
61//!
62//! This crate requires a tokio runtime with both I/O and time drivers enabled. The examples
63//! use `#[tokio::main]` which provides this automatically.
64//!
65//! ```toml
66//! [dependencies]
67//! lib3mf-async = "0.1"
68//! tokio = { version = "1", features = ["full"] }
69//! ```
70//!
71//! ## Cross-References
72//!
73//! This crate is the async counterpart to [`lib3mf_core`]. The [`Model`] type and all
74//! validation/processing operations come from the core crate.
75//!
76//! [`lib3mf_core`]: https://docs.rs/lib3mf-core
77//! [`Model`]: https://docs.rs/lib3mf-core/latest/lib3mf_core/model/struct.Model.html
78//! [`AsyncArchiveReader`]: archive::AsyncArchiveReader
79//! [`AsyncZipArchive`]: zip::AsyncZipArchive
80//! [`load_model_async`]: loader::load_model_async
81
82pub mod archive;
83pub mod loader;
84pub mod zip;