remove PR description since it is redundant
cbowers
parent
1631553efd
commit
f89e61cda9
|
|
@ -1,187 +0,0 @@
|
|||
# Add Rust Bindings for NORM
|
||||
|
||||
## Summary
|
||||
|
||||
This PR adds complete Rust bindings for the NORM library, enabling developers to use NORM's reliable multicast capabilities within the Rust language.
|
||||
|
||||
## What's Added
|
||||
|
||||
### Core Implementation
|
||||
- **norm-sys**: Low-level FFI bindings auto-generated via bindgen from `normApi.h`
|
||||
- **norm**: Rust wrappers with RAII resource management
|
||||
- **Build Integration**: Seamless integration with NORM's waf build system
|
||||
|
||||
### API Coverage
|
||||
- ✅ Instance management with automatic cleanup
|
||||
- ✅ Session configuration (sender/receiver modes)
|
||||
- ✅ Data, file, and stream object transfers
|
||||
- ✅ Complete stream operations (write, read, flush, mark EOM, seek)
|
||||
- ✅ Event handling via Rust iterators
|
||||
- ✅ Ergonomic multicast configuration with builder pattern and macro
|
||||
- ✅ Type-safe enums for all NORM constants (30+ event types, 9 enum types)
|
||||
- ✅ Comprehensive error handling with `thiserror`
|
||||
|
||||
### Documentation
|
||||
- Complete `README.md` with installation and usage examples
|
||||
- Detailed `API_GUIDE.md` covering all major components
|
||||
- Inline rustdoc documentation for all public APIs
|
||||
- 6 working examples demonstrating data, file, and stream transfers
|
||||
|
||||
### Key Features
|
||||
- **Memory Safety**: RAII pattern ensures proper resource cleanup via Drop trait
|
||||
- **Zero-Cost Abstractions**: Compiles to same machine code as direct C calls
|
||||
- **Idiomatic Rust**: Builder patterns, iterators, Result types, method chaining
|
||||
- **Platform Support**: macOS, Linux, Windows, Solaris (via conditional compilation)
|
||||
|
||||
## Building with Rust Bindings
|
||||
|
||||
```bash
|
||||
# Configure with Rust support
|
||||
./waf configure --build-rust
|
||||
|
||||
# Build in release mode with documentation
|
||||
./waf configure --build-rust --rust-release --rust-docs
|
||||
./waf build
|
||||
|
||||
# Or build directly with cargo
|
||||
cd rust
|
||||
cargo build --release
|
||||
cargo doc --open
|
||||
```
|
||||
|
||||
## Usage Example
|
||||
|
||||
```rust
|
||||
use norm::{Instance, multicast, MulticastExt, EventType, Result};
|
||||
|
||||
fn main() -> Result<()> {
|
||||
let instance = Instance::new(false)?;
|
||||
let session = instance.create_session("224.1.2.3", 6003, 1)?;
|
||||
|
||||
// Ergonomic multicast configuration
|
||||
let config = multicast!("224.1.2.3", 6003, {
|
||||
ttl: 64,
|
||||
loopback: true,
|
||||
});
|
||||
session.with_multicast(&config)?;
|
||||
|
||||
// Start sender and send data
|
||||
session.set_tx_rate(1_000_000.0)
|
||||
.start_sender(rand::random(), 1024*1024, 1400, 64, 16, None)?;
|
||||
|
||||
session.data_enqueue(b"Hello, NORM!", None)?;
|
||||
|
||||
// Event handling with iterators
|
||||
for event in instance.events() {
|
||||
if event.event_type == EventType::TxQueueEmpty {
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Examples Included
|
||||
|
||||
- `data_send.rs` / `data_recv.rs` - Data object transfer
|
||||
- `file_send.rs` / `file_recv.rs` - File transfer
|
||||
- `stream_send.rs` / `stream_recv.rs` - Stream transfer with message boundaries
|
||||
|
||||
Run examples:
|
||||
```bash
|
||||
cargo run --example data_send 224.1.2.3 6003
|
||||
cargo run --example stream_send 224.1.2.3 6003
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
The bindings include comprehensive unit tests covering:
|
||||
- Type conversions (all enum From implementations)
|
||||
- Multicast configuration builder pattern
|
||||
- Multicast address validation (IPv4 and IPv6)
|
||||
- Error handling and display
|
||||
- String conversion functions
|
||||
|
||||
```bash
|
||||
# Run tests (set library path for dynamic linking)
|
||||
cd src/rust
|
||||
DYLD_LIBRARY_PATH=../../build:../../build/protolib cargo test
|
||||
|
||||
# Or use the waf build which handles paths automatically
|
||||
./waf build --build-rust
|
||||
```
|
||||
|
||||
**Test Results:**
|
||||
- ✅ 17 unit tests in `norm` crate (all passing)
|
||||
- ✅ 2 unit tests in `norm-sys` crate (all passing)
|
||||
- ✅ 6 working examples compile and demonstrate functionality
|
||||
|
||||
Test coverage includes:
|
||||
- `error.rs`: 5 tests (error handling, string conversion)
|
||||
- `types.rs`: 5 tests (enum conversions)
|
||||
- `multicast.rs`: 7 tests (builder, validation, macro)
|
||||
|
||||
## Files Added
|
||||
|
||||
```
|
||||
rust/
|
||||
├── norm-sys/ # FFI bindings (bindgen)
|
||||
│ ├── build.rs # Auto-generates bindings from normApi.h
|
||||
│ ├── Cargo.toml
|
||||
│ └── src/lib.rs
|
||||
├── norm/ # Safe Rust wrappers
|
||||
│ ├── Cargo.toml
|
||||
│ ├── build.rs
|
||||
│ └── src/
|
||||
│ ├── lib.rs # Public API
|
||||
│ ├── error.rs # Error types
|
||||
│ ├── types.rs # Type-safe enums
|
||||
│ ├── instance.rs # Instance wrapper
|
||||
│ ├── session.rs # Session wrapper
|
||||
│ ├── object.rs # Object wrapper + stream ops
|
||||
│ ├── node.rs # Node wrapper
|
||||
│ ├── event.rs # Event handling
|
||||
│ └── multicast.rs # Multicast config
|
||||
├── examples/ # 6 complete examples
|
||||
├── Cargo.toml # Workspace configuration
|
||||
├── README.md # Rust documentation
|
||||
├── API_GUIDE.md # Detailed API guide
|
||||
└── waf_rust.py # Build system integration
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
- **Language**: Rust 2021 edition, requires Rust 1.70+
|
||||
- **FFI**: Uses bindgen 0.69 for automatic binding generation
|
||||
- **Dependencies**: `libc`, `thiserror`, `rand` (examples only)
|
||||
- **Build**: Integrates with waf via custom Python module
|
||||
- **Linking**: Automatically links against libnorm, libprotokit, and system libraries
|
||||
- **Safety**: All unsafe FFI calls wrapped in safe Rust APIs
|
||||
|
||||
## Compatibility
|
||||
|
||||
- Non-breaking change - purely additive
|
||||
- Does not modify existing C/C++ code
|
||||
- Optional - NORM builds without Rust if toolchain not present
|
||||
- Requires Rust toolchain only when `--build-rust` flag is used
|
||||
|
||||
## License
|
||||
|
||||
Rust bindings follow NORM's BSD-3-Clause license.
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [x] Code compiles without errors
|
||||
- [x] Examples demonstrate all major features
|
||||
- [x] Documentation is comprehensive
|
||||
- [x] Unit tests cover core functionality (19 tests passing)
|
||||
- [x] Integration with waf build system
|
||||
- [x] Platform-specific configuration (macOS, Linux, Windows, Solaris)
|
||||
- [x] RAII resource management prevents leaks
|
||||
- [x] Error handling throughout
|
||||
- [x] Stream operations fully implemented
|
||||
- [x] FFI constant naming warnings suppressed appropriately
|
||||
- [x] Workspace resolver configured for edition 2021
|
||||
Loading…
Reference in New Issue