timely_bytes/lib.rs
1//! A simplified implementation of the `bytes` crate, with different features, less safety.
2//!
3//! # Examples
4//!
5//! ```
6//! use timely_bytes::arc::Bytes;
7//!
8//! let bytes = vec![0u8; 1024];
9//! let mut shared1 = Bytes::from(bytes);
10//! let mut shared2 = shared1.extract_to(100);
11//! let mut shared3 = shared1.extract_to(100);
12//! let mut shared4 = shared2.extract_to(60);
13//!
14//! assert_eq!(shared1.len(), 824);
15//! assert_eq!(shared2.len(), 40);
16//! assert_eq!(shared3.len(), 100);
17//! assert_eq!(shared4.len(), 60);
18//!
19//! for byte in shared1.iter_mut() { *byte = 1u8; }
20//! for byte in shared2.iter_mut() { *byte = 2u8; }
21//! for byte in shared3.iter_mut() { *byte = 3u8; }
22//! for byte in shared4.iter_mut() { *byte = 4u8; }
23//!
24//! // memory in slabs [4, 2, 3, 1]: merge back in arbitrary order.
25//! shared2.try_merge(shared3).ok().expect("Failed to merge 2 and 3");
26//! shared2.try_merge(shared1).ok().expect("Failed to merge 23 and 1");
27//! shared4.try_merge(shared2).ok().expect("Failed to merge 4 and 231");
28//!
29//! assert_eq!(shared4.len(), 1024);
30//! ```
31#![forbid(missing_docs)]
32
33/// An `Arc`-backed mutable byte slice backed by a common allocation.
34pub mod arc {
35
36 use std::ops::{Deref, DerefMut};
37 use std::sync::Arc;
38 use std::any::Any;
39
40 /// A thread-safe byte buffer backed by a shared allocation.
41 pub struct Bytes {
42 /// Pointer to the start of this slice (not the allocation).
43 ptr: *mut u8,
44 /// Length of this slice.
45 len: usize,
46 /// Shared access to underlying resources.
47 ///
48 /// Importantly, this is unavailable for as long as the struct exists, which may
49 /// prevent shared access to ptr[0 .. len]. I'm not sure I understand Rust's rules
50 /// enough to make a stronger statement about this.
51 sequestered: Arc<dyn Any>,
52 }
53
54 // Synchronization happens through `self.sequestered`, which mean to ensure that even
55 // across multiple threads each region of the slice is uniquely "owned", if not in the
56 // traditional Rust sense.
57 unsafe impl Send for Bytes { }
58
59 impl Bytes {
60
61 /// Create a new instance from a byte allocation.
62 pub fn from<B>(bytes: B) -> Bytes where B : DerefMut<Target=[u8]>+'static {
63
64 // Sequester allocation behind an `Arc`, which *should* keep the address
65 // stable for the lifetime of `sequestered`. The `Arc` also serves as our
66 // source of truth for the allocation, which we use to re-connect slices
67 // of the same allocation.
68 let mut sequestered = Arc::new(bytes) as Arc<dyn Any>;
69 let (ptr, len) =
70 Arc::get_mut(&mut sequestered)
71 .unwrap()
72 .downcast_mut::<B>()
73 .map(|a| (a.as_mut_ptr(), a.len()))
74 .unwrap();
75
76 Bytes {
77 ptr,
78 len,
79 sequestered,
80 }
81 }
82
83 /// Extracts [0, index) into a new `Bytes` which is returned, updating `self`.
84 ///
85 /// # Safety
86 ///
87 /// This method first tests `index` against `self.len`, which should ensure that both
88 /// the returned `Bytes` contains valid memory, and that `self` can no longer access it.
89 pub fn extract_to(&mut self, index: usize) -> Bytes {
90
91 assert!(index <= self.len);
92
93 let result = Bytes {
94 ptr: self.ptr,
95 len: index,
96 sequestered: self.sequestered.clone(),
97 };
98
99 unsafe { self.ptr = self.ptr.offset(index as isize); }
100 self.len -= index;
101
102 result
103 }
104
105 /// Regenerates the Bytes if it is uniquely held.
106 ///
107 /// If uniquely held, this method recovers the initial pointer and length
108 /// of the sequestered allocation and re-initializes the Bytes. The return
109 /// value indicates whether this occurred.
110 ///
111 /// # Examples
112 ///
113 /// ```
114 /// use timely_bytes::arc::Bytes;
115 ///
116 /// let bytes = vec![0u8; 1024];
117 /// let mut shared1 = Bytes::from(bytes);
118 /// let mut shared2 = shared1.extract_to(100);
119 /// let mut shared3 = shared1.extract_to(100);
120 /// let mut shared4 = shared2.extract_to(60);
121 ///
122 /// drop(shared1);
123 /// drop(shared2);
124 /// drop(shared4);
125 /// assert!(shared3.try_regenerate::<Vec<u8>>());
126 /// assert!(shared3.len() == 1024);
127 /// ```
128 pub fn try_regenerate<B>(&mut self) -> bool where B: DerefMut<Target=[u8]>+'static {
129 // Only possible if this is the only reference to the sequestered allocation.
130 if let Some(boxed) = Arc::get_mut(&mut self.sequestered) {
131 let downcast = boxed.downcast_mut::<B>().expect("Downcast failed");
132 self.ptr = downcast.as_mut_ptr();
133 self.len = downcast.len();
134 true
135 }
136 else {
137 false
138 }
139 }
140
141 /// Attempts to merge adjacent slices from the same allocation.
142 ///
143 /// If the merge succeeds then `other.len` is added to `self` and the result is `Ok(())`.
144 /// If the merge fails self is unmodified and the result is `Err(other)`, returning the
145 /// bytes supplied as input.
146 ///
147 /// # Examples
148 ///
149 /// ```
150 /// use timely_bytes::arc::Bytes;
151 ///
152 /// let bytes = vec![0u8; 1024];
153 /// let mut shared1 = Bytes::from(bytes);
154 /// let mut shared2 = shared1.extract_to(100);
155 /// let mut shared3 = shared1.extract_to(100);
156 /// let mut shared4 = shared2.extract_to(60);
157 ///
158 /// // memory in slabs [4, 2, 3, 1]: merge back in arbitrary order.
159 /// shared2.try_merge(shared3).ok().expect("Failed to merge 2 and 3");
160 /// shared2.try_merge(shared1).ok().expect("Failed to merge 23 and 1");
161 /// shared4.try_merge(shared2).ok().expect("Failed to merge 4 and 231");
162 /// ```
163 pub fn try_merge(&mut self, other: Bytes) -> Result<(), Bytes> {
164 if Arc::ptr_eq(&self.sequestered, &other.sequestered) && ::std::ptr::eq(unsafe { self.ptr.offset(self.len as isize) }, other.ptr) {
165 self.len += other.len;
166 Ok(())
167 }
168 else {
169 Err(other)
170 }
171 }
172 }
173
174 impl Deref for Bytes {
175 type Target = [u8];
176 fn deref(&self) -> &[u8] {
177 unsafe { ::std::slice::from_raw_parts(self.ptr, self.len) }
178 }
179 }
180
181 impl DerefMut for Bytes {
182 fn deref_mut(&mut self) -> &mut [u8] {
183 unsafe { ::std::slice::from_raw_parts_mut(self.ptr, self.len) }
184 }
185 }
186}