1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
//! # Netbeam
//!
//! A high-performance networking library providing multiplexing, reliable connections,
//! and synchronization primitives for building robust networked applications.
//!
//! ## Features
//!
//! - **Multiplexing**: Create multiple logical streams over a single connection
//! - **Reliable Connections**: Guaranteed ordered delivery of messages
//! - **Synchronization**: Thread-safe primitives for network applications
//! - **Time Tracking**: Precise timing utilities for network operations
//! - **Zero Unsafe Code**: Completely safe Rust implementation
//!
//! ## Core Components
//!
//! - `multiplex`: Multiplexed connection handling and stream management
//! - `reliable_conn`: Traits and implementations for reliable ordered connections
//! - `sync`: Synchronization primitives and network application utilities
//! - `time_tracker`: Precise timing utilities for network operations
//!
//! ## Example
//!
//! ```rust,no_run
//! use anyhow::Result;
//! use netbeam::multiplex::MultiplexedConn;
//! use netbeam::sync::SymmetricConvID;
//! use netbeam::reliable_conn::ReliableOrderedStreamToTarget;
//! use netbeam::sync::subscription::Subscribable;
//! use netbeam::sync::RelativeNodeType;
//!
//! async fn example() -> Result<()> {
//! // This is just a placeholder - replace with your actual connection
//! let conn = get_connection().await?;
//!
//! // Create a multiplexed connection
//! let muxed_conn = MultiplexedConn::<SymmetricConvID>::new(RelativeNodeType::Initiator, conn);
//!
//! // Create a new stream with a unique ID
//! let stream_id = 1.into();
//! let mut stream = muxed_conn.subscribe(stream_id);
//!
//! // Send data
//! stream.send_to_peer(b"Hello").await?;
//!
//! // Receive response
//! let response = stream.recv().await?;
//! println!("Received: {:?}", response);
//!
//! Ok(())
//! }
//! # async fn get_connection() -> Result<impl ReliableOrderedStreamToTarget> { Ok(citadel_io::tokio::net::TcpStream::connect("127.0.0.1:8080").await?) }
//! ```
//!
//! ## Synchronization Example
//!
//! ```rust,no_run
//! use anyhow::Result;
//! use netbeam::sync::primitives::net_mutex::NetMutex;
//! use netbeam::sync::subscription::Subscribable;
//!
//! async fn sync_example<S: Subscribable + 'static>(connection: &S) -> Result<()> {
//! // Create a network-aware mutex
//! let mutex = NetMutex::create(connection, Some(0)).await?;
//!
//! // Acquire the lock
//! let mut guard = mutex.lock().await?;
//!
//! // Modify the protected data
//! *guard += 1;
//!
//! Ok(())
//! }
//! ```
//!
//! ## Design Philosophy
//!
//! Netbeam is built with the following principles:
//!
//! 1. **Safety**: Zero unsafe code, leveraging Rust's type system
//! 2. **Performance**: Efficient multiplexing and minimal overhead
//! 3. **Reliability**: Guaranteed message ordering and delivery
//! 4. **Flexibility**: Extensible traits for custom implementations
//!
//! ## Usage Notes
//!
//! - All network operations are async and require a Tokio runtime
//! - Proper error handling is essential as network operations can fail
//! - Stream IDs should be coordinated between endpoints
//! - Consider using the synchronization primitives for shared state
use Future;
use Pin;
/// A scoped future result type used internally by the crate.
///
/// This type alias represents a pinned, boxed future that returns a Result
/// and can be sent across thread boundaries.
pub type ScopedFutureResult<'a, T> =
;