[−][src]Trait kekbit::core::Reader
The Reader
trait allows reading bytes from a kekbit channel. Implementers of this trait
are called 'kekbit readers'. Usually a reader is bound to a given channel, and it is
expected that multiple readers will safely access the same channel simultaneous.
Required methods
fn read(
&mut self,
handler: &mut impl FnMut(u32, &[u8]),
message_count: u16
) -> Result<u32, ReadError>
&mut self,
handler: &mut impl FnMut(u32, &[u8]),
message_count: u16
) -> Result<u32, ReadError>
Accesses a number of records from the kekbit channel, and for each record, calls the given callback.
Returns the amount of bytes read from the channel
Arguments
handler
- The callback function to be called when a record is pulled from the channel. The function will receive as parameters the position of the message in the channel, and the message in binary format.message_count
- A hint about how many records shall be read from the channel before the method completes. It is expected that this method will take from the channel at most this many records
Errors
If this function fails, than an error variant will be returned. These errors are not expected to be recoverable. Once any error except Timeout
occurred, there will never be
data to read pass the current read marker. However reading from beginning of the channel to the current
read marker should still be a valid operation. The Timeout
exception,
may or may not be recoverable, depends on the channel Writer
behaviour.
fn move_to(&mut self, position: u32) -> Result<u32, InvalidPosition>
Moves the reader to the given position in the channel if the position is valid and points to the beginning of a record. This method could be used by a reader to resume work from a previous session.
Returns the position if the operation succeeds
Arguments
position
- The position in channel where we want the reader to point. The value is accounted from the beginning of the channel(e.g. a position of zero means the beginning of the channel). The position must be valid, it must be properly aligned, and is should point to the start of a record.
Errors
If the channel is corrupted or the position is invalid a InvalidPosition will occur.
Implementors
impl Reader for ShmReader
[src]
fn read(
&mut self,
handler: &mut impl FnMut(u32, &[u8]),
message_count: u16
) -> Result<u32, ReadError>
[src]
&mut self,
handler: &mut impl FnMut(u32, &[u8]),
message_count: u16
) -> Result<u32, ReadError>
Reads up to message_count
messages from the channel and for each message
calls the given handler. The handler it is not
called for heartbeat
messages.
This operation is non-blocking, if you want to wait for a message to be available, external
wait/spin mechanisms must be used.
Returns the amount of bytes read together and/or an error. Even if an error occurred there may have been messages which were correctly read, and for which the handler was called.
Arguments
handler
- The function which will be called every time a valid messages is read from the channel. The message is just binary data, it's up to the handler to interpret it properly.message_count
- Themaximum
number of messages to be read on this call.
Errors
Various errors may occur such: a writer
timeout is detected, end of channel is reached, channel is closed or channel data is corrupted.
However even in such situations, some valid records may have been processed.
Examples
use kekbit_core::shm::*; use crate::kekbit_core::api::Reader; let writer_id = 1850; let channel_id = 42; let test_tmp_dir = tempdir::TempDir::new("kektest").unwrap(); let mut reader = shm_reader(&test_tmp_dir.path(), channel_id).unwrap(); reader.read(&mut |pos,buf| println!("{}->{}",pos, std::str::from_utf8(buf).unwrap()), 10).unwrap();
fn move_to(&mut self, position: u32) -> Result<u32, InvalidPosition>
[src]
Tries to move this reader to a given position if it is valid.
Returns the position itself if the operation was successful otherwise some error.
Arguments
position
- Position where will try to point this reader. It must be a valid position on the channel
Errors
///
Examples
use kekbit_core::shm::*; use crate::kekbit_core::api::Reader; let writer_id = 1850; let channel_id = 42; let test_tmp_dir = tempdir::TempDir::new("kektest").unwrap(); let mut reader = shm_reader(&test_tmp_dir.path(), channel_id).unwrap(); reader.read(&mut |pos,buf| println!("{}->{}",pos, std::str::from_utf8(buf).unwrap()), 10).unwrap(); reader.move_to(0);//start reading from beginning again