DCC accessory address event producer for the Well-Known DCC Accessory range. More...

#include <DccAccyProducer.hxx>

Inheritance diagram for openlcb::DccAccyProducer:

Public Types
enum	Route { NORMAL = false , REVERSE = true }
	DCC accessory activation values. More...

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.

Public Member Functions
	DccAccyProducer (Node *node, std::function< void(unsigned, bool)> dcc_state_callback=nullptr)
	Constructor.

	~DccAccyProducer ()
	Destructor. Remove "this" instance from instances_ vector.

Public Member Functions inherited from CallableFlow< DccAccyProducerInput >
	CallableFlow (Service *s)
	Creates a callable flow.

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.

Static Public Attributes
static constexpr uint16_t	MAX_ADDRESS = 2044
	highest possible DCC address supported

Private Types
using	Command = DccAccyProducerInput::Command

Private Member Functions
Action	entry () override
	Entry point to sub-flow that dispatches the next state based on the incoming command.

Action	query ()
	Query the last known state of the accessory address.

Action	set ()
	Set the state of the accessory address.

DccAccyProducerInput *	input ()
	Helper method for accessing the subflow input data.

	DISALLOW_COPY_AND_ASSIGN (DccAccyProducer)

Static Private Member Functions
static void	once_routine ()
	Called once.

static void	state_callback (unsigned bit, bool value)
	Callback called when there is a notification of event (DCC accessory address) state.

Private Attributes
std::function< void(unsigned, bool)>	dccStateCallback_
	Callback method that will be invoked when a consumer identified message is received with a known state.

WriteHelper	writer_
	statically allocated buffer

BarrierNotifiable	bn_
	notfiable for unblocking the next state

Static Private Attributes
static uninitialized< BitRangeNonAuthoritativeEventP >	eventProducer_
	Singleton instance of a BitRangeNonAuthoritativeEventP for the DCC accessory address Well-Known Event ID range.

static uninitialized< std::vector< DccAccyProducer * > >	instances_
	Vector of all the subscribers to the DCC accessory address Well-Known Event ID Range.

static Atomic	instancesLock_
	This lock protects the instances_ vector;.

static OSThreadOnce	once_
	one time execution helper

Additional Inherited Members
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 CallableFlow< DccAccyProducerInput >
using	Action = StateFlowBase::Action

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 CallableFlow< DccAccyProducerInput >
DccAccyProducerInput *	request ()

bool	has_request ()

Action	return_ok ()
	Terminates the flow and returns the request buffer to the caller with an error code of OK (zero).

Action	wait_and_return_ok ()
	Waits to be notified before moving onto the next state for termination.

Action	wait_done ()
	Terminates the flow and returns the request buffer to the caller with an error code of OK (zero).

Action	return_with_error (int error)
	Terminates the flow and returns the request buffer to the caller with an specific error code.

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

DCC accessory address event producer for the Well-Known DCC Accessory range.

We implement the event mapping scheme referred to as "Vendor B" in the OpenLCB EventIdentifiersTN document.

Definition at line 106 of file DccAccyProducer.hxx.

Member Typedef Documentation

◆ Command

using openlcb::DccAccyProducer::Command = DccAccyProducerInput::Command

private

Definition at line 167 of file DccAccyProducer.hxx.

Member Enumeration Documentation

◆ Route

enum openlcb::DccAccyProducer::Route

DCC accessory activation values.

Enumerator
NORMAL	normal route
REVERSE	reverse route

Definition at line 110 of file DccAccyProducer.hxx.

Constructor & Destructor Documentation

◆ DccAccyProducer()

openlcb::DccAccyProducer::DccAccyProducer	(	Node *	node,
		std::function< void(unsigned, bool)>	dcc_state_callback = `nullptr`
	)

inline

Constructor.

Creates a new DCC Accessory range producer.

Parameters

node	the node that the producer will be bound to
dcc_state_callback	Callback method for delivering the results of a consumer identified or event report. The first unsigned parameter represents the bit offset for the range and the second bool parameter indicates the state as indicated by Route.

Definition at line 128 of file DccAccyProducer.hxx.

◆ ~DccAccyProducer()

openlcb::DccAccyProducer::~DccAccyProducer ( )

inline

Destructor. Remove "this" instance from instances_ vector.

Definition at line 149 of file DccAccyProducer.hxx.

Member Function Documentation

◆ entry()

Action openlcb::DccAccyProducer::entry ( )

inlineoverrideprivatevirtual

Entry point to sub-flow that dispatches the next state based on the incoming command.

Returns: next state appropriate to the command, else Defs::ERROR_INVALID_ARGS on error

Implements TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >.

Definition at line 181 of file DccAccyProducer.hxx.

◆ input()

DccAccyProducerInput * openlcb::DccAccyProducer::input ( )

inlineprivate

Helper method for accessing the subflow input data.

Returns: pointer to the subflow data

Definition at line 222 of file DccAccyProducer.hxx.

◆ once_routine()

static void openlcb::DccAccyProducer::once_routine ( )

inlinestaticprivate

Called once.

Definition at line 171 of file DccAccyProducer.hxx.

◆ query()

Action openlcb::DccAccyProducer::query ( )

inlineprivate

Query the last known state of the accessory address.

Returns: waits for the query message to go out and advances to the parent flow's next state once the memory holding the message is freed.

Definition at line 200 of file DccAccyProducer.hxx.

◆ set()

Action openlcb::DccAccyProducer::set ( )

inlineprivate

Set the state of the accessory address.

Returns: waits for the query message to go out and advances to the parent flow's next state once the memory holding the message is freed.

Definition at line 212 of file DccAccyProducer.hxx.

◆ state_callback()

static void openlcb::DccAccyProducer::state_callback	(	unsigned	bit,
		bool	value
	)

inlinestaticprivate

Callback called when there is a notification of event (DCC accessory address) state.

Pass to the next level up after accounting for DCC address range starting at 1.

Parameters

bit	bit index within event pair range
value	value of the event pair

Todo:: (Stuart Baker) should this be protected by a mutex with the constructor and destructor?

Definition at line 233 of file DccAccyProducer.hxx.

Member Data Documentation

◆ bn_

BarrierNotifiable openlcb::DccAccyProducer::bn_

private

notfiable for unblocking the next state

Definition at line 265 of file DccAccyProducer.hxx.

◆ dccStateCallback_

std::function<void(unsigned, bool)> openlcb::DccAccyProducer::dccStateCallback_

private

Callback method that will be invoked when a consumer identified message is received with a known state.

Definition at line 262 of file DccAccyProducer.hxx.

◆ eventProducer_

uninitialized< BitRangeNonAuthoritativeEventP > openlcb::DccAccyProducer::eventProducer_

staticprivate

Singleton instance of a BitRangeNonAuthoritativeEventP for the DCC accessory address Well-Known Event ID range.

Definition at line 248 of file DccAccyProducer.hxx.

◆ instances_

uninitialized< std::vector< DccAccyProducer * > > openlcb::DccAccyProducer::instances_

staticprivate

Vector of all the subscribers to the DCC accessory address Well-Known Event ID Range.

Definition at line 252 of file DccAccyProducer.hxx.

◆ instancesLock_

Atomic openlcb::DccAccyProducer::instancesLock_

staticprivate

This lock protects the instances_ vector;.

Definition at line 255 of file DccAccyProducer.hxx.

◆ MAX_ADDRESS

constexpr uint16_t openlcb::DccAccyProducer::MAX_ADDRESS = 2044

staticconstexpr

highest possible DCC address supported

Definition at line 117 of file DccAccyProducer.hxx.

◆ once_

OSThreadOnce openlcb::DccAccyProducer::once_

staticprivate

one time execution helper

Definition at line 258 of file DccAccyProducer.hxx.

◆ writer_

WriteHelper openlcb::DccAccyProducer::writer_

private

statically allocated buffer

Definition at line 264 of file DccAccyProducer.hxx.

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

Public Types

Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Command

Member Enumeration Documentation

◆ Route

Constructor & Destructor Documentation

◆ DccAccyProducer()

◆ ~DccAccyProducer()

Member Function Documentation

◆ entry()

◆ input()

◆ once_routine()

◆ query()

◆ set()

◆ state_callback()

Member Data Documentation

◆ bn_

◆ dccStateCallback_

◆ eventProducer_

◆ instances_

◆ instancesLock_

◆ MAX_ADDRESS

◆ once_

◆ writer_