Open jonas-schievink opened 3 years ago
Proper documentation is on the traits:
From ReadBuffer
docs:
The implementing type must be safe to use for DMA reads. This means:
- It must be a pointer that references the actual buffer.
- As long as no
&mut self
method is called on the implementing object:
read_buffer
must always return the same value, if called multiple times.- The memory specified by the pointer and size returned by
read_buffer
must not be freed as long as self is not dropped.
To make this easier to find it could probably be added to the methods as well.
That also does not seem to include any obligations that need to be upheld by the caller of the method. If there are none, the function can be made safe while keeping just the trait unsafe
.
...which makes it sound like even a subsequent call to read_buffer would be unsafe.
Did you mean write_buffer
?
The functions are unsafe to allow for implementations for types like Vec
, just like StableDeref
, but we decided to be more clear since we deal with raw pointers.
All of the buffer access methods,
write_buffer
,read_buffer
, and their static counterparts, areunsafe
, but the Safety section in their docs does not explain what invariants the caller needs to uphold for the call to be safe.The safety docs for
write_buffer
are:The docs for
read_buffer
are:...which makes it sound like even a subsequent call to
read_buffer
would be unsafe.