Struct DMSCFrameParser 

pub struct DMSCFrameParser { /* private fields */ }

Frame parser for reading and assembling protocol frames from stream data.

The DMSCFrameParser handles the incremental parsing of frame data from network streams or byte sources. Network protocols often deliver data in chunks that may not align with protocol frame boundaries. This parser accumulates incoming data in an internal buffer and extracts complete frames when sufficient data is available. It also manages sequence number validation to ensure frame ordering integrity.

Parser Operation Model

Incoming Data:  [partial][complete][partial][complete][partial]
                     |         |        |         |
                     v         v        v         v
Parser Buffer:  [======][==========][=========][=======]
                     |         |        |
                     v         v        v
Extracted:      [Frame1] [Frame2] [Frame3]

Sequence Number Validation

The parser maintains an expected sequence number counter. Each extracted frame must have a sequence number matching the expected value. This detects missing frames (gaps in sequence numbers) which may indicate packet loss. Use reset_sequence() to set a new expected sequence number, such as after reconnection.

Buffer Management

The parser maintains an internal buffer that grows as data is added. For long-running connections, periodically check buffer_len() and consider calling clear_buffer() if buffer accumulation indicates parsing issues. The parser automatically removes parsed data from the buffer.

Python Bindings

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

from dmsc import DMSCFrameParser

# Create parser for incoming stream data
parser = DMSCFrameParser.new()

# Simulate receiving data chunks
chunks = [
    frame1_bytes[:20],
    frame1_bytes[20:] + frame2_bytes[:30],
    frame2_bytes[30:] + frame3_bytes
]

for chunk in chunks:
    parser.add_data(chunk)
    while True:
        frame = parser.parse_frame()
        if frame is None:
            break
        print(f"Received frame: {frame.sequence_number()}")

print(f"Buffer contains {parser.buffer_len()} bytes")

Examples

Basic frame parsing from stream data:

use dmsc::protocol::frames::{DMSCFrameParser, DMSCFrame};

let mut parser = DMSCFrameParser::new();

// Simulate receiving frame data in chunks
let frame1 = DMSCFrame::data_frame(b"First message".to_vec(), 0)
    .expect("Failed to create frame");
let frame2 = DMSCFrame::data_frame(b"Second message".to_vec(), 1)
    .expect("Failed to create frame");

let bytes1 = frame1.to_bytes().expect("Failed to serialize");
let bytes2 = frame2.to_bytes().expect("Failed to serialize");

// Add first chunk (partial frame)
parser.add_data(&bytes1[..20]);
assert!(parser.parse_frame().unwrap().is_none());

// Add second chunk (completes frame1, starts frame2)
parser.add_data(&bytes1[20..]);
let parsed = parser.parse_frame().unwrap().expect("Should have complete frame");
assert_eq!(parsed.sequence_number(), 0);

// Add remaining data
parser.add_data(&bytes2);
let parsed = parser.parse_frame().unwrap().expect("Should have complete frame");
assert_eq!(parsed.sequence_number(), 1);

Handling sequence number reset:

use dmsc::protocol::frames::DMSCFrameParser;

let mut parser = DMSCFrameParser::new();

// Parse some frames
parser.add_data(&some_data);
while let Ok(Some(frame)) = parser.parse_frame() {
    // Process frames
}

// Reset sequence number for new session
parser.reset_sequence();
parser.clear_buffer();

// Now expecting sequence 0 again
assert_eq!(parser.next_sequence, 0);

Thread Safety

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

Performance Considerations

• The parser uses Vec::extend_from_slice for efficient buffer appending
• Frame extraction uses slice operations to avoid unnecessary copying
• Buffer memory is only reclaimed when frames are successfully parsed
• Large frames may cause temporary buffer growth; configure appropriate limits

Implementations

impl DMSCFrameParser

pub fn new() -> Self

pub fn add_data(&mut self, data: &[u8])

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

pub fn buffer_len(&self) -> usize

pub fn clear_buffer(&mut self)

pub fn reset_sequence(&mut self)

Trait Implementations

impl<'py> IntoPyObject<'py> for DMSCFrameParser

type Target = DMSCFrameParser

The Python output type

type Output = Bound<'py, <DMSCFrameParser 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 DMSCFrameParser

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for DMSCFrameParser

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 = c"Frame parser for reading and assembling protocol frames from stream data.\n\nThe DMSCFrameParser handles the incremental parsing of frame data from network\nstreams or byte sources. Network protocols often deliver data in chunks that\nmay not align with protocol frame boundaries. This parser accumulates incoming\ndata in an internal buffer and extracts complete frames when sufficient data\nis available. It also manages sequence number validation to ensure frame\nordering integrity.\n\n## Parser Operation Model\n\n```\nIncoming Data: [partial][complete][partial][complete][partial]\n | | | |\n v v v v\nParser Buffer: [======][==========][=========][=======]\n | | |\n v v v\nExtracted: [Frame1] [Frame2] [Frame3]\n```\n\n## Sequence Number Validation\n\nThe parser maintains an expected sequence number counter. Each extracted frame\nmust have a sequence number matching the expected value. This detects missing\nframes (gaps in sequence numbers) which may indicate packet loss. Use\n`reset_sequence()` to set a new expected sequence number, such as after\nreconnection.\n\n## Buffer Management\n\nThe parser maintains an internal buffer that grows as data is added. For\nlong-running connections, periodically check `buffer_len()` and consider\ncalling `clear_buffer()` if buffer accumulation indicates parsing issues.\nThe parser automatically removes parsed data from the buffer.\n\n## Python Bindings\n\nWhen compiled with the `pyo3` feature, this struct provides Python bindings:\n```python\nfrom dmsc import DMSCFrameParser\n\n# Create parser for incoming stream data\nparser = DMSCFrameParser.new()\n\n# Simulate receiving data chunks\nchunks = [\n frame1_bytes[:20],\n frame1_bytes[20:] + frame2_bytes[:30],\n frame2_bytes[30:] + frame3_bytes\n]\n\nfor chunk in chunks:\n parser.add_data(chunk)\n while True:\n frame = parser.parse_frame()\n if frame is None:\n break\n print(f\"Received frame: {frame.sequence_number()}\")\n\nprint(f\"Buffer contains {parser.buffer_len()} bytes\")\n```\n\n# Examples\n\nBasic frame parsing from stream data:\n```rust,ignore\nuse dmsc::protocol::frames::{DMSCFrameParser, DMSCFrame};\n\nlet mut parser = DMSCFrameParser::new();\n\n// Simulate receiving frame data in chunks\nlet frame1 = DMSCFrame::data_frame(b\"First message\".to_vec(), 0)\n .expect(\"Failed to create frame\");\nlet frame2 = DMSCFrame::data_frame(b\"Second message\".to_vec(), 1)\n .expect(\"Failed to create frame\");\n\nlet bytes1 = frame1.to_bytes().expect(\"Failed to serialize\");\nlet bytes2 = frame2.to_bytes().expect(\"Failed to serialize\");\n\n// Add first chunk (partial frame)\nparser.add_data(&bytes1[..20]);\nassert!(parser.parse_frame().unwrap().is_none());\n\n// Add second chunk (completes frame1, starts frame2)\nparser.add_data(&bytes1[20..]);\nlet parsed = parser.parse_frame().unwrap().expect(\"Should have complete frame\");\nassert_eq!(parsed.sequence_number(), 0);\n\n// Add remaining data\nparser.add_data(&bytes2);\nlet parsed = parser.parse_frame().unwrap().expect(\"Should have complete frame\");\nassert_eq!(parsed.sequence_number(), 1);\n```\n\nHandling sequence number reset:\n```rust,ignore\nuse dmsc::protocol::frames::DMSCFrameParser;\n\nlet mut parser = DMSCFrameParser::new();\n\n// Parse some frames\nparser.add_data(&some_data);\nwhile let Ok(Some(frame)) = parser.parse_frame() {\n // Process frames\n}\n\n// Reset sequence number for new session\nparser.reset_sequence();\nparser.clear_buffer();\n\n// Now expecting sequence 0 again\nassert_eq!(parser.next_sequence, 0);\n```\n\n# Thread Safety\n\nThis struct is not thread-safe. Multiple threads should not concurrently\naccess the same parser instance without external synchronization. For\nconcurrent parsing, either use separate parser instances per thread or\nwrap access with a Mutex or RwLock.\n\n# Performance Considerations\n\n- The parser uses `Vec::extend_from_slice` for efficient buffer appending\n- Frame extraction uses slice operations to avoid unnecessary copying\n- Buffer memory is only reclaimed when frames are successfully parsed\n- Large frames may cause temporary buffer growth; configure appropriate limits\x00"

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<DMSCFrameParser>

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 DMSCFrameParser

const NAME: &'static str = "DMSCFrameParser"

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 DMSCFrameParser

impl ExtractPyClassWithClone for DMSCFrameParser