StateFlow for sending out medium-sized data payloads like the Simple Node Ident Info protocol. More...

#include <SimpleInfoProtocol.hxx>

Inheritance diagram for openlcb::SimpleInfoFlow:

Public Member Functions
	SimpleInfoFlow (Service *s, unsigned max_bytes_per_message=255, bool use_continue_bits=true)
	Creates a simple ident flow handler.

Public Member Functions inherited from StateFlow< MessageType, QueueType >
	StateFlow (Service *service)
	Constructor.

Public Member Functions inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
	TypedStateFlow (Service *service)
	Constructor.

virtual	~TypedStateFlow ()
	Destructor.

void	send (MessageType *msg, unsigned priority=UINT_MAX) OVERRIDE
	Sends a message to the state flow for processing.

Public Member Functions inherited from UntypedStateFlow< QueueType >
	UntypedStateFlow (Service *service)
	Constructor.

Public Member Functions inherited from StateFlowWithQueue
void	notify () override
	Wakeup call arrived. Schedules *this on the executor.

bool	is_waiting ()

Public Member Functions inherited from StateFlowBase
void	run () override
	Callback from the executor.

Service *	service ()
	Return a pointer to the service I am bound to.

Public Member Functions inherited from Executable
void	test_deletion ()

Public Member Functions inherited from QMember
void	init ()
	Initiailize a QMember, in place of a public placement construction.

Public Member Functions inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_next ()

Public Member Functions inherited from FlowInterface< MessageType >
virtual Pool *	pool ()

virtual MessageType *	type_helper ()
	This function is never user in the code, but GDB can use it to infer the correct message types.

MessageType *	alloc ()
	Synchronously allocates a message buffer from the pool of this flow.

void	alloc_async (Executable *target)
	Asynchronously allocates a message buffer from the pool of this flow.

Private Member Functions
Action	entry () OVERRIDE
	Entry into the StateFlow activity.

const SimpleInfoDescriptor &	current_descriptor ()

bool	is_eof ()

void	open_and_seek_next_file ()
	Assumes that the current descriptor is a file argument.

void	update_for_next_entry ()
	Call this function after updating entryOffset_.

uint8_t	file_read_current_byte ()
	Returns the next byte from the file data, advancing the file offset.

uint8_t	current_byte ()
	Returns the current byte in the stream of data.

void	step_byte ()
	Increments to the next byte in the stream of data.

Action	continue_send ()

Action	fill_buffer ()

Private Attributes
uint8_t	maxBytesPerMessage_
	Configuration option.

uint8_t	useContinueBits_: 1
	Configuration option.

uint8_t	isFirstMessage_: 1
	Whether this is the first reply message we are sending out.

uint8_t	entryOffset_: 5
	Tells which descriptor entry we are processing.

uint8_t	byteOffset_
	Byte offset within a descriptor entry.

uint8_t	currentLength_
	Total / max length of the current block.

const char *	fileName_ {nullptr}
	Last file name we opened.

int	fd_ {-1}
	fd of the last file we opened.

BarrierNotifiable	n_

Additional Inherited Members
Public Types inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
typedef Base::Action	Action
	Allows using Action without having StateFlowBase:: prefix in front of it.

Public Types inherited from FlowInterface< MessageType >
typedef MessageType	message_type
	Stores the message template type for external reference.

Static Public Member Functions inherited from StateFlowBase
template<class T , typename... Args>
static void	invoke_subflow_and_ignore_result (FlowInterface< Buffer< T > > *target_flow, Args &&... args)
	Calls a helper flow to perform some actions.

Static Public Member Functions inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Static Public Member Functions inherited from FlowInterface< MessageType >
static MessageType *	cast_alloc (QMember *entry)
	Down casts and initializes an asynchronous allocation result to the appropriate flow's buffer type.

Protected Types inherited from UntypedStateFlow< QueueType >
typedef Action(StateFlowBase::*	Callback) ()
	State Flow callback prototype.

Protected Types inherited from StateFlowBase
typedef Action(StateFlowBase::*	Callback) ()
	State Flow callback prototype.

Protected Member Functions inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
void	release () OVERRIDE
	Unrefs the current buffer.

void	return_buffer ()
	For state flows that are operated using invoke_subflow_and_wait this is a way to hand back the buffer to the caller.

MessageType *	message ()

MessageType *	transfer_message ()
	Releases ownership of the current message.

Protected Member Functions inherited from UntypedStateFlow< QueueType >
void	send (BufferBase *msg, unsigned priority=UINT_MAX)
	Sends a message to the state flow for processing.

QMember *	queue_next (unsigned *priority) OVERRIDE
	Takes the front entry in the queue.

bool	queue_empty () OVERRIDE

Action	call_immediately (Callback c)
	Imediately call the next state upon return.

Protected Member Functions inherited from StateFlowWithQueue
	StateFlowWithQueue (Service *service)
	Constructor.

Action	exit ()
	Terminates the processing of this flow.

Action	release_and_exit ()
	Terminates the processing of the current message.

BufferBase *	message ()

BufferBase *	transfer_message ()
	Releases ownership of the current message.

void	reset_message (BufferBase *message, unsigned priority)
	Sets the current message being processed.

unsigned	priority ()

void	set_priority (unsigned priority)
	Overrides the current priority.

void	start_flow_at_init (Callback c)
	Call this from the constructor of the child class to do some work before the main queue processing loop begins.

Protected Member Functions inherited from StateFlowBase
	StateFlowBase (Service *service)
	Constructor.

	~StateFlowBase ()
	Destructor.

void	reset_flow (Callback c)
	Resets the flow to the specified state.

bool	is_state (Callback c)

bool	is_terminated ()

void	start_flow (Callback c)
	Resets the flow to the specified state and starts it.

Action	again ()
	Call the current state again via call_immediately.

Action	exit ()
	Terminate current StateFlow activity.

Action	delete_this ()
	Terminates the flow and deletes *this.

Action	set_terminated ()
	Sets the flow to terminated state.

Action	call_immediately (Callback c)
	Imediately call the next state upon return.

Action	wait ()
	Wait for an asynchronous call.

Action	wait_and_call (Callback c)
	Wait for resource to become available before proceeding to next state.

template<class T >
Action	allocate_and_call (FlowInterface< Buffer< T > > target_flow, Callback c, Pool pool=nullptr)
	Allocates a buffer from a pool and proceed to the next state when allocation is successful.

Action	allocate_and_call (Callback c, QAsync *queue)
	Allocates an entry from an asynchronous queue, and transitions to a state once the allocation is complete.

template<class T >
Buffer< T > *	full_allocation_result (FlowInterface< Buffer< T > > *target_flow)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
T *	full_allocation_result (TypedQAsync< T > *queue)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
void	cast_allocation_result (T **member)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
Buffer< T > *	get_allocation_result (FlowInterface< Buffer< T > > *target_flow)
	Takes the result of the asynchronous allocation.

Action	yield_and_call (Callback c)
	Place the current flow to the back of the executor, and transition to a new state after we get the CPU again.

Action	yield ()
	Place the current flow to the back of the executor, and re-try the current state after we get the CPU again.

Action	sleep_and_call (::Timer *timer, long long timeout_nsec, Callback c)
	Suspends execution of this control flow for a specified time.

template<class T , typename... Args>
Action	invoke_subflow_and_wait (FlowInterface< Buffer< T > > *target_flow, Callback c, Args &&... args)
	Calls a helper flow to perform some actions.

Action	read_repeated (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Blocks until size bytes are read and then invokes the next state.

Action	read_single (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Attempts to read at most size_t bytes, and blocks the caller until at least one byte is read.

Action	read_nonblocking (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Attempts to read at most size bytes, and then invokes the next state, even if only zero bytes are available right now.

Action	read_repeated_with_timeout (StateFlowTimedSelectHelper helper, long long timeout_nsec, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Blocks until size bytes are read, or a timeout expires.

Action	internal_try_read ()
	Implementation state that gets repeatedly called upon every wakeup and tries to make progress on reading.

Action	write_repeated (StateFlowSelectHelper helper, int fd, const void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Writes some data into a file descriptor, repeating the operation as necessary until all bytes are written.

Action	internal_try_write ()
	Implementation state that gets repeatedly called upon every wakeup and tries to make progress on writing.

Protected Member Functions inherited from QMember
	QMember ()
	Constructor.

	~QMember ()
	Destructor.

Protected Member Functions inherited from Atomic
void	lock ()

void	unlock ()

Protected Member Functions inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_this ()

	LinkedObject ()
	Constructor. Puts *this on the linked list.

	~LinkedObject ()
	Constructor. Removes *this from the linked list.

StateFlowWithQueue *	link_next ()

Static Protected Member Functions inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Protected Attributes inherited from QMember
QMember *	next
	pointer to the next member in the queue

Protected Attributes inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_
	Linked list pointer.

Static Protected Attributes inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	head_
	Beginning of the list.

Detailed Description

StateFlow for sending out medium-sized data payloads like the Simple Node Ident Info protocol.

The flow works by assembling a medium-sized payload according to a specific pattern. The pattern consists of a sequence of literal bytes, fixed-length strings, C strings, etc.

Usage:

Create a static array of SimpleInfoDescriptor structures to define the response that needs to be pieced together. Add a MessageHandlerFlow to receive the simple X info request messages. When such a request arrives, extract the source node handle, and send a SimpleInfoResponse message to the SimpleInfoFlow with the node handle and the descriptor array pointer. The SimpleInfoFlow will assemble, fragment and send the response message.

Example: see @SNIPHandler.

Definition at line 129 of file SimpleInfoProtocol.hxx.

Constructor & Destructor Documentation

◆ SimpleInfoFlow()

openlcb::SimpleInfoFlow::SimpleInfoFlow	(	Service *	s,
		unsigned	max_bytes_per_message = `255`,
		bool	use_continue_bits = `true`
	)

inline

Creates a simple ident flow handler.

Parameters

max_bytes_per_message	tells how many bytes we should package in one outgoing buffer. Responses longer than this will be sent as multiple separate messages. Set this to 6 on CAN to completely avoid raw pagination. Set to 255 to create one memory buffer that will then be split into frames by the low-level interface. Maximum value is 255.
use_continue_bits	should be true if we should instruct the low-level interface to use the continuation-pending bits so long as we have pending bytes. This will make the messages be pieced together at the receiving end into one message. Setting this to false will send a reply in multiple messages.

Definition at line 144 of file SimpleInfoProtocol.hxx.

◆ ~SimpleInfoFlow()

openlcb::SimpleInfoFlow::~SimpleInfoFlow ( )

inline

Definition at line 153 of file SimpleInfoProtocol.hxx.

Member Function Documentation

◆ continue_send()

Action openlcb::SimpleInfoFlow::continue_send ( )

inlineprivate

Definition at line 350 of file SimpleInfoProtocol.hxx.

◆ current_byte()

uint8_t openlcb::SimpleInfoFlow::current_byte ( )

inlineprivate

Returns the current byte in the stream of data.

Definition at line 262 of file SimpleInfoProtocol.hxx.

◆ current_descriptor()

const SimpleInfoDescriptor & openlcb::SimpleInfoFlow::current_descriptor ( )

inlineprivate

Definition at line 174 of file SimpleInfoProtocol.hxx.

◆ entry()

Action openlcb::SimpleInfoFlow::entry ( )

inlineprivatevirtual

Entry into the StateFlow activity.

Pure virtual which must be defined by derived class.

Returns: function pointer to next state

Implements TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >.

Definition at line 163 of file SimpleInfoProtocol.hxx.

◆ file_read_current_byte()

uint8_t openlcb::SimpleInfoFlow::file_read_current_byte ( )

inlineprivate

Returns the next byte from the file data, advancing the file offset.

Definition at line 251 of file SimpleInfoProtocol.hxx.

◆ fill_buffer()

Action openlcb::SimpleInfoFlow::fill_buffer ( )

inlineprivate

Definition at line 361 of file SimpleInfoProtocol.hxx.

◆ is_eof()

bool openlcb::SimpleInfoFlow::is_eof ( )

inlineprivate

Returns: true if there are no more bytes to send.

Definition at line 180 of file SimpleInfoProtocol.hxx.

◆ open_and_seek_next_file()

void openlcb::SimpleInfoFlow::open_and_seek_next_file ( )

inlineprivate

Assumes that the current descriptor is a file argument.

Opens the filename in the argument, seeks it to the offset.

Definition at line 187 of file SimpleInfoProtocol.hxx.

◆ step_byte()

void openlcb::SimpleInfoFlow::step_byte ( )

inlineprivate

Increments to the next byte in the stream of data.

Definition at line 321 of file SimpleInfoProtocol.hxx.

◆ update_for_next_entry()

void openlcb::SimpleInfoFlow::update_for_next_entry ( )

inlineprivate

Call this function after updating entryOffset_.

Definition at line 206 of file SimpleInfoProtocol.hxx.

Member Data Documentation

◆ byteOffset_

uint8_t openlcb::SimpleInfoFlow::byteOffset_

private

Byte offset within a descriptor entry.

Definition at line 411 of file SimpleInfoProtocol.hxx.

◆ currentLength_

uint8_t openlcb::SimpleInfoFlow::currentLength_

private

Total / max length of the current block.

This is typically strlen() + 1 (including the terminating zero, if any).

Definition at line 414 of file SimpleInfoProtocol.hxx.

◆ entryOffset_

uint8_t openlcb::SimpleInfoFlow::entryOffset_

private

Tells which descriptor entry we are processing.

Definition at line 408 of file SimpleInfoProtocol.hxx.

◆ fd_

int openlcb::SimpleInfoFlow::fd_ {-1}

private

fd of the last file we opened.

Definition at line 419 of file SimpleInfoProtocol.hxx.

◆ fileName_

const char* openlcb::SimpleInfoFlow::fileName_ {nullptr}

private

Last file name we opened.

Definition at line 417 of file SimpleInfoProtocol.hxx.

◆ isFirstMessage_

uint8_t openlcb::SimpleInfoFlow::isFirstMessage_

private

Whether this is the first reply message we are sending out.

Used with the continuation feature.

Definition at line 406 of file SimpleInfoProtocol.hxx.

◆ maxBytesPerMessage_

uint8_t openlcb::SimpleInfoFlow::maxBytesPerMessage_

private

Configuration option.

See constructor.

Definition at line 400 of file SimpleInfoProtocol.hxx.

◆ n_

BarrierNotifiable openlcb::SimpleInfoFlow::n_

private

Definition at line 421 of file SimpleInfoProtocol.hxx.

◆ useContinueBits_

uint8_t openlcb::SimpleInfoFlow::useContinueBits_

private

Configuration option.

See constructor.

Definition at line 402 of file SimpleInfoProtocol.hxx.

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

SimpleInfoProtocol.hxx

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SimpleInfoFlow()

◆ ~SimpleInfoFlow()

Member Function Documentation

◆ continue_send()

◆ current_byte()

◆ current_descriptor()

◆ entry()

◆ file_read_current_byte()

◆ fill_buffer()

◆ is_eof()

◆ open_and_seek_next_file()

◆ step_byte()

◆ update_for_next_entry()

Member Data Documentation

◆ byteOffset_

◆ currentLength_

◆ entryOffset_

◆ fd_

◆ fileName_

◆ isFirstMessage_

◆ maxBytesPerMessage_

◆ n_

◆ useContinueBits_