rob
/
cpal
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add some notes for devs about the safety requirements of `Data`

This commit is contained in:
mitchmindtree 2020-01-19 19:05:17 +01:00
parent 3fdf189848
commit dbb1cc4140
1 changed files with 18 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/lib.rs
View File

@ -205,6 +205,14 @@ pub struct Data {
impl Data { impl Data {
// Internal constructor for host implementations to use. // Internal constructor for host implementations to use.
//
// The following requirements must be met in order for the safety of `Data`'s public API.
//
// - The `data` pointer must point to the first sample in the slice containing all samples.
// - The `len` must describe the length of the buffer as a number of samples in the expected
// format specified via the `sample_format` argument.
// - The `sample_format` must correctly represent the underlying sample data delivered/expected
// by the stream.
pub(crate) unsafe fn from_parts( pub(crate) unsafe fn from_parts(
data: *mut (), data: *mut (),
len: usize, len: usize,
@ -228,9 +236,11 @@ impl Data {
/// The raw slice of memory representing the underlying audio data as a slice of bytes. /// The raw slice of memory representing the underlying audio data as a slice of bytes.
/// ///
/// It is up to the user to interprate the slice of memory based on `Data::sample_format`. /// It is up to the user to interpret the slice of memory based on `Data::sample_format`.
pub fn bytes(&self) -> &[u8] { pub fn bytes(&self) -> &[u8] {
let len = self.len * self.sample_format.sample_size(); let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See
// the unsafe `from_parts` constructor for these requirements.
unsafe { unsafe {
std::slice::from_raw_parts(self.data as *const u8, len) std::slice::from_raw_parts(self.data as *const u8, len)
} }
@ -238,9 +248,11 @@ impl Data {
/// The raw slice of memory representing the underlying audio data as a slice of bytes. /// The raw slice of memory representing the underlying audio data as a slice of bytes.
/// ///
/// It is up to the user to interprate the slice of memory based on `Data::sample_format`. /// It is up to the user to interpret the slice of memory based on `Data::sample_format`.
pub fn bytes_mut(&mut self) -> &mut [u8] { pub fn bytes_mut(&mut self) -> &mut [u8] {
let len = self.len * self.sample_format.sample_size(); let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See
// the unsafe `from_parts` constructor for these requirements.
unsafe { unsafe {
std::slice::from_raw_parts_mut(self.data as *mut u8, len) std::slice::from_raw_parts_mut(self.data as *mut u8, len)
} }
@ -254,6 +266,8 @@ impl Data {
T: Sample, T: Sample,
{ {
if T::FORMAT == self.sample_format { if T::FORMAT == self.sample_format {
// The safety of this block relies on correct construction of the `Data` instance. See
// the unsafe `from_parts` constructor for these requirements.
unsafe { unsafe {
Some(std::slice::from_raw_parts(self.data as *const T, self.len)) Some(std::slice::from_raw_parts(self.data as *const T, self.len))
} }
@ -270,6 +284,8 @@ impl Data {
T: Sample, T: Sample,
{ {
if T::FORMAT == self.sample_format { if T::FORMAT == self.sample_format {
// The safety of this block relies on correct construction of the `Data` instance. See
// the unsafe `from_parts` constructor for these requirements.
unsafe { unsafe {
Some(std::slice::from_raw_parts_mut(self.data as *mut T, self.len)) Some(std::slice::from_raw_parts_mut(self.data as *mut T, self.len))
} }