Detailed Description

A port for reading from a MultiBuffer object.

See also: multi_buffer.h, io::MultiPacket, io::MultiWriter.

Definition at line 255 of file multi_buffer.h.

#include <multi_buffer.h>

Inheritance diagram for satcat5::io::MultiReader:

Collaboration diagram for satcat5::io::MultiReader:

Public Member Functions
virtual bool	accept (satcat5::io::MultiPacket *packet)
	Accept a packet from the source buffer? Default accepts all packets unless this port is disabled or full. More...

void	flush ()
	Discard all queued packets.

bool	get_port_enable () const
	Is this port currently enabled? More...

void	set_port_enable (bool enable)
	Enable or disable this port. More...

void	set_timeout (unsigned timeout_msec)
	Update the watchdog timeout. More...

void	read_finalize () override
	Consume any remaining bytes in this frame, if applicable. More...

satcat5::io::MultiPacket *	get_packet () const
	Get a pointer to the current packet, if active.

void	read_reset (const satcat5::io::MultiPacket *pkt)
	Reset read state for the designated packet.

unsigned	get_read_ready () const override
	How many bytes can be read without blocking? More...

bool	read_bytes (unsigned nbytes, void *dst) override
	Read 0 or more bytes into a buffer. More...

bool	read_consume (unsigned nbytes) override
	Read and discard 0 or more bytes. More...

virtual void	set_callback (satcat5::io::EventListener *callback)
	Update registered callback for data_rcvd() events. More...

u8	read_u8 ()
	One of many functions for reading integer/floating point values, see details. More...

unsigned	read_str (unsigned dst_size, char *dst)
	Safely read a null-terminated input string. More...

template<class T >
bool	read_obj (T &t)
	Templated wrapper for any object with the following method: `bool read_from(satcat5::io::Readable* rd);`

unsigned	copy_to (satcat5::io::Writeable *dst)
	Copy data to a Writeable object, without finalizing. More...

bool	copy_and_finalize (satcat5::io::Writeable *dst, satcat5::io::CopyMode mode=CopyMode::PACKET)
	Copy data to a Writeable object, then finalize. More...

void	request_poll ()
	Call this method to request polling at a later time. More...

void	request_cancel ()
	Call this method to cancel a previous request_poll().

void	timer_once (unsigned msec)
	Configure a one-time notification after X milliseconds.

void	timer_every (unsigned msec)
	Configure a repeating notification every X milliseconds.

void	timer_stop ()
	Stop all future notifications.

unsigned	timer_interval () const
	Accessor for recurring timer interval, if one is set.

unsigned	timer_remaining () const
	Accessor for time to next event, if one is set.

Static Public Member Functions
static unsigned	count_ondemand ()
	Count queued objects of this type (i.e., non-idle).

static unsigned	count_timer ()
	Count all objects of this type, including idle timers.

Protected Member Functions
	MultiReader (satcat5::io::MultiBuffer *src)
	Constructor and destructor are only accessible to children.

virtual bool	pkt_push (satcat5::io::MultiPacket *packet)=0
	Push a packet onto the end of a queue or similar data structure. More...

virtual satcat5::io::MultiPacket *	pkt_pop ()=0
	Choose the next packet to start reading, or NULL to stop. More...

void	pkt_init (satcat5::io::MultiPacket *packet)
	Helper function for starting a new packet, or NULL to stop.

void	pkt_free (satcat5::io::MultiPacket *packet)
	Decrement reference count, free when it reaches zero.

void	timer_event () override
	Timeouts help prevent resource-hogging.

u8	read_next () override
	Read the next byte from the underlying buffer or device. More...

void	read_notify ()
	Attempt notification by calling `m_callback->data_rcvd()`. More...

virtual void	read_underflow ()
	Optional error handling for read underflow. More...

Protected Attributes
satcat5::io::MultiBuffer *const	m_src
	Pointer to the source buffer.


satcat5::io::MultiReader *	m_next


bool	m_port_enable
	Internal state.

unsigned	m_read_timeout
	Internal state.

Private Member Functions
void	poll_demand ()
	Event handler for on-demand polling.

void	query (unsigned elapsed_msec)

Private Attributes
satcat5::io::EventListener *	m_callback
	Pointer to the callback object, or NULL. More...

bool	m_idle

unsigned	m_trem

unsigned	m_tnext


unsigned	m_read_pos
	Current read state.

unsigned	m_read_rem
	Current read state.

const satcat5::io::MultiPacket *	m_read_pkt
	Current read state.

satcat5::io::MultiChunk *	m_read_chunk
	Current read state.

Member Function Documentation

◆ accept()

bool MultiReader::accept ( satcat5::io::MultiPacket * packet )

virtual

Accept a packet from the source buffer? Default accepts all packets unless this port is disabled or full.

Child classes MAY override this method to adjust this policy, apply filters, or to implement an additional pre-buffer. Child classes that accept(...) a packet MUST eventually call either pkt_push(...) or pkt_free(...) to avoid memory leaks.

Note: This method SHOULD only be called from MultiBuffer or its children. This method is public only for to allow flexibility in mutual "friend" inheritance rules.

Definition at line 274 of file multi_buffer.cc.

◆ copy_and_finalize()

bool Readable::copy_and_finalize	(	satcat5::io::Writeable *	dst,
		satcat5::io::CopyMode	mode = `CopyMode::PACKET`
	)

inherited

Copy data to a Writeable object, then finalize.

As copy_to(), but also calls read_finalize() and/or write_finalize() depending on the input/output mode.

In packet mode (the default), call both read_finalize() and write_finalize() if the operation copies all available data. Use this mode whenever the input is packetized.

In byte-stream mode, call write_finalize() if the operation copies any data, but never call read_finalize(). Use this mode for inputs that do not delimit packet boundaries.

Parameters

dst	The destination object.
mode	Select packet mode or stream mode.

Returns: True if the output was finalized successfully.

Definition at line 234 of file io_readable.cc.

◆ copy_to()

unsigned Readable::copy_to ( satcat5::io::Writeable * dst )

inherited

Copy data to a Writeable object, without finalizing.

Copy the contents of this Readable to a Writeable object, stopping at end-of-input, end-of-frame, or the capacity of the destination buffer (whichever comes first). This method does not call read_finalize or write_finalize(). To automatically make finalize calls,

See also: copy_and_finalize.

Returns: The number of bytes copied.

Definition at line 214 of file io_readable.cc.

◆ get_port_enable()

bool satcat5::io::MultiReader::get_port_enable ( ) const

inline

Is this port currently enabled?

See also: set_port_enable.

Definition at line 278 of file multi_buffer.h.

◆ get_read_ready()

unsigned MultiPacket::Reader::get_read_ready ( ) const

overridevirtualinherited

How many bytes can be read without blocking?

Child objects of io::Readable MUST override this method.

Implements satcat5::io::Readable.

Definition at line 63 of file multi_buffer.cc.

◆ pkt_pop()

virtual satcat5::io::MultiPacket* satcat5::io::MultiReader::pkt_pop ( )

protectedpure virtual

Choose the next packet to start reading, or NULL to stop.

Child classes MUST implement this method.

Implemented in satcat5::io::MultiReaderPriority, and satcat5::io::MultiReaderSimple.

◆ pkt_push()

virtual bool satcat5::io::MultiReader::pkt_push ( satcat5::io::MultiPacket * packet )

protectedpure virtual

Push a packet onto the end of a queue or similar data structure.

Child classes MUST implement this method.

Implemented in satcat5::io::MultiReaderPriority, and satcat5::io::MultiReaderSimple.

◆ read_bytes()

bool MultiPacket::Reader::read_bytes	(	unsigned	nbytes,
		void *	dst
	)

overridevirtualinherited

Read 0 or more bytes into a buffer.

Child objects of io::Readable MAY override this method for improved performance.

Reimplemented from satcat5::io::Readable.

Definition at line 68 of file multi_buffer.cc.

◆ read_consume()

bool MultiPacket::Reader::read_consume ( unsigned nbytes )

overridevirtualinherited

Read and discard 0 or more bytes.

Child objects of io::Readable MAY override this method for improved performance.

Reimplemented from satcat5::io::Readable.

Definition at line 88 of file multi_buffer.cc.

◆ read_finalize()

void MultiReader::read_finalize ( )

overridevirtual

Consume any remaining bytes in this frame, if applicable.

Child objects of io::Readable SHOULD override this method if they support framing.

Reimplemented from satcat5::io::MultiPacket::Reader.

Definition at line 290 of file multi_buffer.cc.

◆ read_next()

u8 MultiPacket::Reader::read_next ( )

overrideprotectedvirtualinherited

Read the next byte from the underlying buffer or device.

Child objects of io::Readable MUST override this method.

Implements satcat5::io::Readable.

Definition at line 96 of file multi_buffer.cc.

◆ read_notify()

void Readable::read_notify ( )

protectedinherited

Attempt notification by calling m_callback->data_rcvd().

Child objects of io::Readable MAY call this to override default notifications.

Definition at line 254 of file io_readable.cc.

◆ read_str()

unsigned Readable::read_str	(	unsigned	dst_size,
		char *	dst
	)

inherited

Safely read a null-terminated input string.

The input is always consumed up to the end-of-input or the first zero byte, whichever comes first.

Returns: The length of the output string, which may be truncated as needed to fit in the provided buffer.

Definition at line 179 of file io_readable.cc.

◆ read_u8()

u8 Readable::read_u8 ( )

inherited

One of many functions for reading integer/floating point values, see details.

Several functions are provided for reading and writing scalar types to/from io::Readable and io::Writeable instances. Since there are many of these that are frequently inherited, they are hidden from documentation. These functions follow a shared template:

read_ or write_ prefix.
u for unsigned, s for signed, f for floating-point.
Data-type width in bits.
- Available widths for ints: 8/16/24/32/48/64.
- Available widths for floats: 32/64.
l suffix if little-endian, no suffix if big-endian.

Example: write_s48l is "Write 48 bits (6 bytes) to this io::Writeable as a signed value in little-endian order".

Definition at line 44 of file io_readable.cc.

◆ read_underflow()

void Readable::read_underflow ( )

protectedvirtualinherited

Optional error handling for read underflow.

Child objects of io::Readable MAY override this method.

Reimplemented in satcat5::port::Mailmap, and satcat5::io::ReadableRedirect.

Definition at line 271 of file io_readable.cc.

◆ request_poll()

void satcat5::poll::OnDemand::request_poll ( )

inherited

Call this method to request polling at a later time.

Safe to stack requests, but only one call to poll().

Definition at line 208 of file polling.cc.

◆ set_callback()

void Readable::set_callback ( satcat5::io::EventListener * callback )

virtualinherited

Update registered callback for data_rcvd() events.

Child objects of io::Readable SHOULD usually leave this method as-is.

Reimplemented in satcat5::io::ReadableRedirect, satcat5::io::Override, satcat5::io::MuxPort, and satcat5::test::EthernetInterface.

Definition at line 39 of file io_readable.cc.

◆ set_port_enable()

void satcat5::io::MultiReader::set_port_enable ( bool enable )

inline

Enable or disable this port.

Disabled ports reject all incoming packets.

Definition at line 283 of file multi_buffer.h.

◆ set_timeout()

void satcat5::io::MultiReader::set_timeout ( unsigned timeout_msec )

inline

Update the watchdog timeout.

The watchdog is reset each time a byte is read; if data is available, but nothing is is read, then the Reader discards everything in the queue.

Definition at line 290 of file multi_buffer.h.

Member Data Documentation

◆ m_callback

satcat5::io::EventListener* satcat5::io::Readable::m_callback

privateinherited

Pointer to the callback object, or NULL.

This can only be modified through the set_callback(...) method.

Definition at line 199 of file io_readable.h.

The documentation for this class was generated from the following files:

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Member Function Documentation

◆ accept()

◆ copy_and_finalize()

◆ copy_to()

◆ get_port_enable()

◆ get_read_ready()

◆ pkt_pop()

◆ pkt_push()

◆ read_bytes()

◆ read_consume()

◆ read_finalize()

◆ read_next()

◆ read_notify()

◆ read_str()

◆ read_u8()

◆ read_underflow()

◆ request_poll()

◆ set_callback()

◆ set_port_enable()

◆ set_timeout()

Member Data Documentation

◆ m_callback