Trait kekbit_core::api::Writer

pub trait Writer<D: DataFormat> {
    fn write(&mut self, data: &impl Encodable<D>) -> 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. For any given channel a DataFormat must be specified.

Required methods

fn write(&mut self, data: &impl Encodable<D>) -> 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 - information to be encoded and pushed into channel.

Errors

If the operation fails, than an error variant will be returned. Some errors such EncodingError or NoSpaceForRecord may allow future writes to succeed while others such ChannelFull signals the end of life for the channel.

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. The errors are not recoverable, they signal that the channel had reached the end of its lifetime.

Loading content...

Provided methods

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<D: DataFormat> Writer<D> for ShmWriter<D>

fn write(&mut self, data: &impl Encodable<D>) -> Result<u32, WriteError>

Writes a message into the channel. This operation will encode the data directly into channel. 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 data which to encode and write into the channel.

Errors

Two kinds of failures may occur. One if the encoding operation failed, the other if the channel rejected the message for reasons such data is too large or no space is available in the channel.

Examples

use kekbit_core::tick::TickUnit::Nanos;
use kekbit_core::shm::*;
use kekbit_core::header::Header;
use kekbit_core::api::Writer;
use kekbit_codecs::codecs::raw::RawBinDataFormat;

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, RawBinDataFormat).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).unwrap();

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

Push a heartbeat message into the channel. Hearbeats are zero sized messages which do not need encoding. Reader should never activate callbacks for heartbeat messsages.

Returns RecordHeaderLen, 8 in the current version if the operation succeeds.

Errors

If the operation fails a ChannelFull error will be returned, which signals that the channel will not accept any new messages.

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;
use kekbit_codecs::codecs::raw::RawBinDataFormat;

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, RawBinDataFormat).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).unwrap();
writer.flush().unwrap();

Loading content...