pub struct Input<T: Send> { /* private fields */ }
Expand description
Producer interface to the triple buffer
The producer of data can use this struct to submit updates to the triple buffer whenever he likes. These updates are nonblocking: a collision between the producer and the consumer will result in cache contention, but deadlocks and scheduling-induced slowdowns cannot happen.
Implementations§
Source§impl<T: Send> Input<T>
impl<T: Send> Input<T>
Sourcepub fn consumed(&self) -> bool
pub fn consumed(&self) -> bool
Check if the consumer has fetched our latest submission yet
This method is only intended for diagnostics purposes. Please do not let it inform your decision of sending or not sending a value, as that would effectively be building a very poor spinlock-based double buffer implementation. If what you truly need is a double buffer, build yourself a proper blocking one instead of wasting CPU time.
Sourcepub fn input_buffer(&mut self) -> &mut T
👎Deprecated: Please use input_buffer_mut() instead
pub fn input_buffer(&mut self) -> &mut T
Access the input buffer directly
This is, for now, a deprecated alias to
input_buffer_mut()
. Please use this method
instead.
In a future major release of this crate, input_buffer()
will
undergo a breaking change to instead provide read-only access.
The aim of this process is to eventually migrate towards the standard
accessor()
/accessor_mut()
method naming convention that most Rust
libraries follow.
Sourcepub fn input_buffer_mut(&mut self) -> &mut T
pub fn input_buffer_mut(&mut self) -> &mut T
Access the input buffer directly
This advanced interface allows you to update the input buffer in place, so that you can avoid creating values of type T repeatedy just to push them into the triple buffer when doing so is expensive.
However, by using it, you force yourself to take into account some implementation subtleties that you could otherwise ignore.
First, the buffer does not contain the last value that you published
(which is now available to the consumer thread). In fact, what you get
may not match any value that you sent in the past, but rather be a new
value that was written in there by the consumer thread. All you can
safely assume is that the buffer contains a valid value of type T, which
you may need to “clean up” before use using a type-specific process
(like calling the clear()
method of a Vec
/String
).
Second, we do not send updates automatically. You need to call
publish()
in order to propagate a buffer update to
the consumer. If you would prefer this to be done automatically when the
input buffer reference goes out of scope, consider using the
input_buffer_publisher()
RAII
interface instead.
Sourcepub fn publish(&mut self) -> bool
pub fn publish(&mut self) -> bool
Publish the current input buffer, checking for overwrites
After updating the input buffer in-place using
input_buffer_mut()
, you can use this method
to publish your updates to the consumer. Beware that this will replace
the current input buffer with another one that has totally unrelated
contents.
It will also tell you whether you overwrote a value which was not read by the consumer thread.
Sourcepub fn input_buffer_publisher(&mut self) -> InputPublishGuard<'_, T>
pub fn input_buffer_publisher(&mut self) -> InputPublishGuard<'_, T>
Access the input buffer wrapped in the InputPublishGuard
This is an RAII alternative to the input_buffer_mut()
/publish()
workflow where the publish()
transaction happens automatically when
the input buffer handle goes out of scope.
Please check out the documentation of input_buffer_mut()
and
publish()
to know more about the precautions that you need to take
when using the lower-level in-place buffer access interface.