Struct kekbit::core::Header

pub struct Header { /* fields omitted */ }

Defines and validates the metadata associated with a channel.

Methods

impl Header

pub fn new(
    writer_id: u64,
    channel_id: u64,
    capacity_hint: u32,
    max_msg_len_hint: u32,
    timeout: u64,
    tick_unit: TickUnit
) -> Header

Defines a new channel header.

Return a struct that contains all the metadata required to be associated with a new channel.

Arguments

• writer_id - Channel's writer identifier
• channel_id - Channel's identifier
• capacity_hint - Hint for the size of the channel - the maximum amount of data that can be wrote into the channel. Usually a successfully created channel will have a size very close to this hint, probably a little larger.
• max_msg_len_hint - Hint for the maximum size of a message wrote into the channel. This cannot be larger than a certain fraction. of the channel's capacity(1/128th), so the new created channel may have max message length value smaller than this hint.
• timeout - Specifies the write inactivity time interval after each the reader will consider the channel abandoned by the writer.
• tick_unit - Time unit used by the timeout and creation time attributes.

Example

use kekbit_core::tick::TickUnit::Nanos;
use kekbit_core::header::*;
     
let producer_id: u64 = 111;
let channel_id: u64 = 101;
let capacity: u32 = 10_001;
let max_msg_len: u32 = 100;
let timeout: u64 = 10_000;
let tick_unit = Nanos;
let header = Header::new(channel_id, producer_id, capacity, max_msg_len, timeout, tick_unit);
println!("{:?}", &header);

pub fn read(header: &[u8]) -> Result<Header, ChannelError>

Reads and validates the metadata from an existing memory mapped channel.

Returns the metadata associated with the channel.

Arguments

• header - Reference to a byte array which should contain metadata associated with a given channel. Usually points at the beginning of a memory mapped file used as storage for a kekbit channel.

Errors

An error will occur if data is corrupted or points to an incompatible version of kekbit channel.

Example

 use memmap::MmapOptions;
 use std::fs::OpenOptions;

 use kekbit_core::shm::*;
 let writer_id = 1850;
 let channel_id = 4242;
 let test_tmp_dir = tempdir::TempDir::new("kektest").unwrap();
 let dir_path = test_tmp_dir.path();

 let kek_file_name = storage_path(dir_path, channel_id);
 let kek_file = OpenOptions::new()
  .write(true)
  .read(true)
  .open(&kek_file_name).unwrap();
  let mut mmap = unsafe { MmapOptions::new().map_mut(&kek_file) }.unwrap();
  let buf = &mut mmap[..];
  let header = Header::read(buf).unwrap();
  println!("{:?}", &header);

pub fn write_to(&self, header: &mut [u8]) -> usize

Writes kekbit metadata to a memory mapepd file.

Returns the lenght of the metadata

Arguments

• header - Reference to a byte slice where metadata must be written. Usually points at the beginning of a memory mapped file used as storage for a kekbit channel.

Example

 use memmap::MmapOptions;
 use std::fs::OpenOptions;

 use kekbit_core::tick::TickUnit::Nanos;
 use kekbit_core::header::Header;
 use kekbit_core::shm::*;
 use std::fs::DirBuilder;

 const FOREVER: u64 = 99_999_999_999;
 let writer_id = 1850;
 let channel_id = 42;
 let test_tmp_dir = tempdir::TempDir::new("keksample").unwrap();
 let dir_path = test_tmp_dir.path().join(writer_id.to_string());
 let mut builder = DirBuilder::new();
 builder.recursive(true);
 builder.create(&dir_path).or_else(|err| Err(err.to_string())).unwrap();

 let kek_file_name = dir_path.join(format!("{}.kekbit", channel_id));
 let kek_file = OpenOptions::new()
 .write(true)
 .read(true)
 .create(true)
 .open(&kek_file_name)
 .or_else(|err| Err(err.to_string())).unwrap();

 let header = Header::new(writer_id, channel_id, 300_000, 1000, FOREVER, Nanos);
 let total_len = (header.capacity() + header.len() as u32) as u64;
 kek_file.set_len(total_len).or_else(|err| Err(err.to_string())).unwrap();
 let mut mmap = unsafe { MmapOptions::new().map_mut(&kek_file) }.unwrap();
 let buf = &mut mmap[..];
 header.write_to(buf);
 mmap.flush().unwrap();

pub fn version(&self) -> String

Returns the metadata version

pub fn channel_id(&self) -> u64

Returns the channel identifier

pub fn writer_id(&self) -> u64

Returns the channel writer identifier

pub fn capacity(&self) -> u32

Returns the capacity of the channel

pub fn max_msg_len(&self) -> u32

Returns the maximum message size allowed

pub fn timeout(&self) -> u64

Returns the inactivity time interval after each the reader will consider the channel abandoned by the writer.

pub fn creation_time(&self) -> u64

Returns the channel creation time

pub fn tick_unit(&self) -> TickUnit

Returns the time unit used by the channel creation time and the timeout attributes.

pub const fn len(&self) -> usize

Returns the length of the metadata. For any given version the length is the same. In the current version it is 128 bytes.

Trait Implementations

impl Debug for Header

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for Header

impl PartialEq<Header> for Header

fn eq(&self, other: &Header) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Header) -> bool

This method tests for !=.

impl StructuralEq for Header

impl StructuralPartialEq for Header