Trait kekbit_core::api::Writer

pub trait Writer {
    fn write(&mut self, data: &[u8], len: u32) -> Result<u32, WriteError>;

    fn heartbeat(&mut self) -> Result<u32, WriteError> { ... }
    fn flush(&mut self) -> Result<(), Error> { ... }
}

The Writer trait allows writing chunk of bytes as records into a kekbit channel. Implementers of this trait are called 'kekbit writers'. Usually a writer is bound to a given channel, and it is expected that there is only one writer which directly writes into the channel, however multiple writers may cooperate during the writing process.

Required methods

fn write(&mut self, data: &[u8], len: u32) -> Result<u32, WriteError>

Writes a given record to a kekbit channel.

Returns the total amount of bytes wrote into the channel or a WriteError if the write operation fails.

Arguments

• data - The buffer which contains the record data to be written.
• len - The amount of data to be write in the channel, the record length.

Errors

If the operation fails, than an error variant will be returned. Regardless the error variant a future write with a smaller record size may be successful.

Loading content...

Provided methods

fn heartbeat(&mut self) -> Result<u32, WriteError>

Writes into the stream a heartbeat message. This method shall be used by all writers which want to respect to timeout interval associated to a channel. Hearbeating is the expected mechanism by which a channel writer will keep the active readers interested in the data published on the channel. Heartbeat shall be done regularly, at a time interval which ensures that at least one heartbeat is sent between any two 'timeout' long intervals.

Returns the total amount of bytes wrote into the channel or a WriteError if the write operation fails.

Errors

If this call fails, than an error variant will be returned. However in this case the errors are not recoverable, they signal that the channel is at the end of its lifetime.

fn flush(&mut self) -> Result<(), Error>

Flushes the stream which possibly backs the kekbit writer. By default this method does nothing, and should be implemented only for Writers which it makes sense. Returns the success of the operation

Loading content...

Implementors

impl Writer for ShmWriter

fn write(&mut self, data: &[u8], len: u32) -> Result<u32, WriteError>

Writes a message into the channel. This operation will copy the message into the channel storage. While this is a non blocking operation, only one write should be executed at any given time.

Returns the total amount of bytes wrote into the channel which includes, the size of the message, the size of the message header and the amount of padding add to that message.

Arguments

*data - The buffer which contains the data which is going to be wrote into the channel.

• len - The amount of data which is going to be wrote into to he channel

Errors

Two types of failures may occur: message size is larger than the maximum allowed, or the there is not enough space in the channel to write that message. In the second case, a future write may succeed, if the message has a smaller size that the current one.

use kekbit_core::tick::TickUnit::Nanos;
use kekbit_core::shm::*;
use kekbit_core::header::Header;
use kekbit_core::api::Writer;

const FOREVER: u64 = 99_999_999_999;
let writer_id = 1850;
let channel_id = 42;
let capacity = 30_000;
let max_msg_len = 100;
let header = Header::new(writer_id, channel_id, capacity, max_msg_len, FOREVER, Nanos);
let test_tmp_dir = tempdir::TempDir::new("kektest").unwrap();
let mut writer = shm_writer(&test_tmp_dir.path(), &header).unwrap();
let msg = "There are 10 kinds of people: those who know binary and those who don't";
let msg_data = msg.as_bytes();
writer.write(&msg_data, msg_data.len() as u32).unwrap();

fn flush(&mut self) -> Result<(), Error>

Flushes the channel's outstanding memory map modifications to disk. Calling this method explicitly it is not encouraged as flushing does occur automatically and comes with a performance penalty. It should be used only if for various reasons a writer wants to persist the channel data to the disk at a higher rate than is done automatically.

Returns Ok(()) if the operation succeeds.

Errors

If flushing fails an I/O error is returned.

Examples

use kekbit_core::tick::TickUnit::Nanos;
use kekbit_core::shm::*;
use kekbit_core::header::Header;
use kekbit_core::api::Writer;

const FOREVER: u64 = 99_999_999_999;
let writer_id = 1850;
let channel_id = 42;
let capacity = 30_000;
let max_msg_len = 100;
let header = Header::new(writer_id, channel_id, capacity, max_msg_len, FOREVER, Nanos);
let test_tmp_dir = tempdir::TempDir::new("kektest").unwrap();
let mut writer = shm_writer(&test_tmp_dir.path(), &header).unwrap();
let msg = "There are 10 kinds of people: those who know binary and those who don't";
let msg_data = msg.as_bytes();
writer.write(&msg_data, msg_data.len() as u32).unwrap();
writer.flush().unwrap();

Loading content...