Struct DMSCFrameBuilder 

pub struct DMSCFrameBuilder { /* private fields */ }

Frame builder for creating protocol frames with automatic sequence numbering.

The DMSCFrameBuilder provides a convenient interface for constructing DMSC frames while automatically managing sequence numbers. Rather than manually tracking and incrementing sequence numbers for each frame, the builder maintains an internal counter that is automatically incremented after each frame construction. This ensures proper sequence numbering without the risk of human error.

Builder Pattern Advantages

Using the frame builder provides several benefits over direct frame construction:

• Automatic Sequencing: No need to manually track and increment sequence numbers
• Type Safety: Compile-time checking of frame type construction
• Convenience Methods: Domain-specific constructors for each frame type
• State Management: Builder maintains state across frame constructions

Sequence Number Management

The builder maintains an internal sequence counter that is automatically incremented after each frame construction. The counter uses wrapping arithmetic (modulo 2^32) to handle overflow gracefully. You can query or set the current sequence number using next_sequence() and set_sequence() methods.

Python Bindings

When compiled with the pyo3 feature, this struct provides Python bindings:

from dmsc import DMSCFrameBuilder

# Create builder for convenient frame construction
builder = DMSCFrameBuilder.new()

# Build frames without manually tracking sequence numbers
control_frame = builder.build_control_frame(b"\x01\x02\x03")
data_frame = builder.build_data_frame(b"Hello, World!")
auth_frame = builder.build_auth_frame(b"token=abc123")

# Check current sequence number
print(f"Next sequence: {builder.next_sequence()}")

# Reset sequence for new session
builder.set_sequence(0)

Examples

Building multiple frames with automatic sequencing:

use dmsc::protocol::frames::DMSCFrameBuilder;

let mut builder = DMSCFrameBuilder::new();

// Build a series of data frames
let frame1 = builder.build_data_frame(b"Message 1".to_vec())
    .expect("Failed to build frame");
let frame2 = builder.build_data_frame(b"Message 2".to_vec())
    .expect("Failed to build frame");
let frame3 = builder.build_data_frame(b"Message 3".to_vec())
    .expect("Failed to build frame");

assert_eq!(frame1.sequence_number(), 0);
assert_eq!(frame2.sequence_number(), 1);
assert_eq!(frame3.sequence_number(), 2);

// Current sequence is now 3
assert_eq!(builder.next_sequence(), 3);

Building different frame types:

use dmsc::protocol::frames::DMSCFrameBuilder;

let mut builder = DMSCFrameBuilder::new();

// Control frame
let control = builder.build_control_frame(vec![0x01, 0x00, 0x01])
    .expect("Failed to build control frame");

// Authentication frame
let auth = builder.build_auth_frame(b"credentials=secret".to_vec())
    .expect("Failed to build auth frame");

// Keep-alive frame
let keepalive = builder.build_keepalive_frame()
    .expect("Failed to build keepalive frame");

// Error frame
let error = builder.build_error_frame(0x0401, "Timeout".to_string())
    .expect("Failed to build error frame");

Managing sequence numbers:

use dmsc::protocol::frames::DMSCFrameBuilder;

let mut builder = DMSCFrameBuilder::new();

// Build some frames
let _ = builder.build_data_frame(b"Frame 0".to_vec()).unwrap();
let _ = builder.build_data_frame(b"Frame 1".to_vec()).unwrap();
let _ = builder.build_data_frame(b"Frame 2".to_vec()).unwrap();

// Check current sequence
assert_eq!(builder.next_sequence(), 3);

// Set specific sequence for resend or new session
builder.set_sequence(100);

let next = builder.build_data_frame(b"Frame 100".to_vec()).unwrap();
assert_eq!(next.sequence_number(), 100);
assert_eq!(builder.next_sequence(), 101);

Thread Safety

This struct is not thread-safe. Multiple threads should not concurrently access the same builder instance without external synchronization. For concurrent frame building, either use separate builder instances per thread or wrap access with a Mutex or RwLock.

Performance Characteristics

• Frame construction is O(1) for fixed-size headers
• Payload copying is O(n) where n is payload size
• Sequence number operations are O(1)
• Minimal heap allocation for small payloads

Implementations

impl DMSCFrameBuilder

pub fn new() -> Self

pub fn build_control_frame( &mut self, control_data: Vec<u8>, ) -> DMSCResult<DMSCFrame>

pub fn build_data_frame(&mut self, data: Vec<u8>) -> DMSCResult<DMSCFrame>

pub fn build_auth_frame(&mut self, auth_data: Vec<u8>) -> DMSCResult<DMSCFrame>

pub fn build_keepalive_frame(&mut self) -> DMSCResult<DMSCFrame>

pub fn build_error_frame( &mut self, error_code: u32, error_message: String, ) -> DMSCResult<DMSCFrame>

pub fn next_sequence(&self) -> u32

pub fn set_sequence(&mut self, sequence: u32)

Trait Implementations

impl<'py> IntoPyObject<'py> for DMSCFrameBuilder

type Target = DMSCFrameBuilder

The Python output type

type Output = Bound<'py, <DMSCFrameBuilder as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for DMSCFrameBuilder

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for DMSCFrameBuilder

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// - Minimal heap allocation for small payloads

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<DMSCFrameBuilder>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyTypeInfo for DMSCFrameBuilder

const NAME: &'static str = "DMSCFrameBuilder"

Class name.

const MODULE: Option<&'static str> = ::core::option::Option::None

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for DMSCFrameBuilder

impl ExtractPyClassWithClone for DMSCFrameBuilder