neon/types_impl/buffer/
mod.rs

1//! Types and traits for working with binary buffers.
2
3use std::{
4    cell::RefCell,
5    error::Error,
6    fmt::{self, Debug, Display},
7    marker::PhantomData,
8    ops::{Deref, DerefMut},
9};
10
11use crate::{
12    context::Context,
13    handle::Handle,
14    result::{JsResult, NeonResult, ResultExt},
15    types::{
16        buffer::lock::{Ledger, Lock},
17        JsArrayBuffer, JsTypedArray, Value,
18    },
19};
20
21pub(crate) mod lock;
22pub(super) mod types;
23
24pub use types::Binary;
25
26/// A trait allowing Rust to borrow binary data from the memory buffer of JavaScript
27/// [typed arrays][typed-arrays].
28///
29/// This trait provides both statically and dynamically checked borrowing. As usual
30/// in Rust, mutable borrows are guaranteed not to overlap with other borrows.
31///
32/// # Example
33///
34/// ```
35/// # use neon::prelude::*;
36/// use neon::types::buffer::TypedArray;
37///
38/// fn double(mut cx: FunctionContext) -> JsResult<JsUndefined> {
39///     let mut array: Handle<JsUint32Array> = cx.argument(0)?;
40///
41///     for elem in array.as_mut_slice(&mut cx).iter_mut() {
42///         *elem *= 2;
43///     }
44///
45///     Ok(cx.undefined())
46/// }
47/// ```
48///
49/// [typed-arrays]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays
50pub trait TypedArray: Value {
51    type Item: Binary;
52
53    /// Statically checked immutable borrow of binary data.
54    ///
55    /// This may not be used if a mutable borrow is in scope. For the dynamically
56    /// checked variant see [`TypedArray::try_borrow`].
57    fn as_slice<'cx, 'a, C>(&self, cx: &'a C) -> &'a [Self::Item]
58    where
59        C: Context<'cx>;
60
61    /// Statically checked mutable borrow of binary data.
62    ///
63    /// This may not be used if any other borrow is in scope. For the dynamically
64    /// checked variant see [`TypedArray::try_borrow_mut`].
65    fn as_mut_slice<'cx, 'a, C>(&mut self, cx: &'a mut C) -> &'a mut [Self::Item]
66    where
67        C: Context<'cx>;
68
69    /// Dynamically checked immutable borrow of binary data, returning an error if the
70    /// the borrow would overlap with a mutable borrow.
71    ///
72    /// The borrow lasts until [`Ref`] exits scope.
73    ///
74    /// This is the dynamically checked version of [`TypedArray::as_slice`].
75    fn try_borrow<'cx, 'a, C>(&self, lock: &'a Lock<C>) -> Result<Ref<'a, Self::Item>, BorrowError>
76    where
77        C: Context<'cx>;
78
79    /// Dynamically checked mutable borrow of binary data, returning an error if the
80    /// the borrow would overlap with an active borrow.
81    ///
82    /// The borrow lasts until [`RefMut`] exits scope.
83    ///
84    /// This is the dynamically checked version of [`TypedArray::as_mut_slice`].
85    fn try_borrow_mut<'cx, 'a, C>(
86        &mut self,
87        lock: &'a Lock<C>,
88    ) -> Result<RefMut<'a, Self::Item>, BorrowError>
89    where
90        C: Context<'cx>;
91
92    /// Returns the size, in bytes, of the allocated binary data.
93    fn size<'cx, C>(&self, cx: &mut C) -> usize
94    where
95        C: Context<'cx>;
96
97    /// Constructs an instance from a slice by copying its contents.
98    fn from_slice<'cx, C>(cx: &mut C, slice: &[Self::Item]) -> JsResult<'cx, Self>
99    where
100        C: Context<'cx>;
101}
102
103#[derive(Debug)]
104/// Wraps binary data immutably borrowed from a JavaScript value.
105pub struct Ref<'a, T> {
106    data: &'a [T],
107    ledger: &'a RefCell<Ledger>,
108}
109
110#[derive(Debug)]
111/// Wraps binary data mutably borrowed from a JavaScript value.
112pub struct RefMut<'a, T> {
113    data: &'a mut [T],
114    ledger: &'a RefCell<Ledger>,
115}
116
117impl<'a, T> Deref for Ref<'a, T> {
118    type Target = [T];
119
120    fn deref(&self) -> &Self::Target {
121        self.data
122    }
123}
124
125impl<'a, T> Deref for RefMut<'a, T> {
126    type Target = [T];
127
128    fn deref(&self) -> &Self::Target {
129        self.data
130    }
131}
132
133impl<'a, T> DerefMut for RefMut<'a, T> {
134    fn deref_mut(&mut self) -> &mut Self::Target {
135        self.data
136    }
137}
138
139impl<'a, T> Drop for Ref<'a, T> {
140    fn drop(&mut self) {
141        if self.is_empty() {
142            return;
143        }
144
145        let mut ledger = self.ledger.borrow_mut();
146        let range = Ledger::slice_to_range(self.data);
147        let i = ledger.shared.iter().rposition(|r| r == &range).unwrap();
148
149        ledger.shared.remove(i);
150    }
151}
152
153impl<'a, T> Drop for RefMut<'a, T> {
154    fn drop(&mut self) {
155        if self.is_empty() {
156            return;
157        }
158
159        let mut ledger = self.ledger.borrow_mut();
160        let range = Ledger::slice_to_range(self.data);
161        let i = ledger.owned.iter().rposition(|r| r == &range).unwrap();
162
163        ledger.owned.remove(i);
164    }
165}
166
167#[derive(Eq, PartialEq)]
168/// An error returned by [`TypedArray::try_borrow`] or [`TypedArray::try_borrow_mut`] indicating
169/// that a mutable borrow would overlap with another borrow.
170///
171/// [`BorrowError`] may be converted to an exception with [`ResultExt::or_throw`].
172pub struct BorrowError {
173    _private: (),
174}
175
176impl BorrowError {
177    fn new() -> Self {
178        BorrowError { _private: () }
179    }
180}
181
182impl Error for BorrowError {}
183
184impl Display for BorrowError {
185    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
186        Display::fmt("Borrow overlaps with an active mutable borrow", f)
187    }
188}
189
190impl Debug for BorrowError {
191    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
192        f.debug_struct("BorrowError").finish()
193    }
194}
195
196impl<T> ResultExt<T> for Result<T, BorrowError> {
197    fn or_throw<'a, C: Context<'a>>(self, cx: &mut C) -> NeonResult<T> {
198        self.or_else(|_| cx.throw_error("BorrowError"))
199    }
200}
201
202/// Represents a typed region of an [`ArrayBuffer`](crate::types::JsArrayBuffer).
203///
204/// A `Region` can be created via the
205/// [`Handle<JsArrayBuffer>::region()`](crate::handle::Handle::region) or
206/// [`JsTypedArray::region()`](crate::types::JsTypedArray::region) methods.
207///
208/// A region is **not** checked for validity until it is converted to
209/// a typed array via [`to_typed_array()`](Region::to_typed_array) or
210/// [`JsTypedArray::from_region()`](crate::types::JsTypedArray::from_region).
211///
212/// # Example
213///
214/// ```
215/// # use neon::prelude::*;
216/// # fn f(mut cx: FunctionContext) -> JsResult<JsUint32Array> {
217/// // Allocate a 16-byte ArrayBuffer and a uint32 array of length 2 (i.e., 8 bytes)
218/// // starting at byte offset 4 of the buffer:
219/// //
220/// //       0       4       8       12      16
221/// //      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
222/// // buf: | | | | | | | | | | | | | | | | |
223/// //      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
224/// //               ^       ^
225/// //               |       |
226/// //              +-------+-------+
227/// //         arr: |       |       |
228/// //              +-------+-------+
229/// //               0       1       2
230/// let buf = cx.array_buffer(16)?;
231/// let arr = JsUint32Array::from_region(&mut cx, &buf.region(4, 2))?;
232/// # Ok(arr)
233/// # }
234/// ```
235#[derive(Clone, Copy)]
236pub struct Region<'cx, T: Binary> {
237    buffer: Handle<'cx, JsArrayBuffer>,
238    offset: usize,
239    len: usize,
240    phantom: PhantomData<T>,
241}
242
243impl<'cx, T> Region<'cx, T>
244where
245    T: Binary,
246    JsTypedArray<T>: Value,
247{
248    /// Returns the handle to the region's buffer.
249    pub fn buffer(&self) -> Handle<'cx, JsArrayBuffer> {
250        self.buffer
251    }
252
253    /// Returns the starting byte offset of the region.
254    pub fn offset(&self) -> usize {
255        self.offset
256    }
257
258    /// Returns the number of elements of type `T` in the region.
259    #[allow(clippy::len_without_is_empty)]
260    pub fn len(&self) -> usize {
261        self.len
262    }
263
264    /// Returns the size of the region in bytes, which is equal to
265    /// `(self.len() * size_of::<T>())`.
266    pub fn size(&self) -> usize {
267        self.len * std::mem::size_of::<T>()
268    }
269
270    /// Constructs a typed array for this buffer region.
271    ///
272    /// The resulting typed array has `self.len()` elements and a size of
273    /// `self.size()` bytes.
274    ///
275    /// Throws an exception if the region is invalid, for example if the starting
276    /// offset is not properly aligned, or the length goes beyond the end of the
277    /// buffer.
278    pub fn to_typed_array<'c, C>(&self, cx: &mut C) -> JsResult<'c, JsTypedArray<T>>
279    where
280        C: Context<'c>,
281    {
282        JsTypedArray::from_region(cx, self)
283    }
284}
285
286mod private {
287    use super::Binary;
288    use crate::sys::raw;
289    use std::fmt::{Debug, Formatter};
290    use std::marker::PhantomData;
291
292    pub trait Sealed {}
293
294    #[derive(Clone)]
295    pub struct JsTypedArrayInner<T: Binary> {
296        pub(super) local: raw::Local,
297        pub(super) buffer: raw::Local,
298        pub(super) _type: PhantomData<T>,
299    }
300
301    impl<T: Binary> Debug for JsTypedArrayInner<T> {
302        fn fmt(&self, f: &mut Formatter) -> Result<(), std::fmt::Error> {
303            f.write_str("JsTypedArrayInner { ")?;
304            f.write_str("local: ")?;
305            self.local.fmt(f)?;
306            f.write_str(", buffer: ")?;
307            self.buffer.fmt(f)?;
308            f.write_str(", _type: PhantomData")?;
309            f.write_str(" }")?;
310            Ok(())
311        }
312    }
313
314    impl<T: Binary> Copy for JsTypedArrayInner<T> {}
315}
neon/types_impl/buffer/mod.rs

neon/types_impl/buffer/
mod.rs
