Implementation of a Broadcast Time Protocol client. More...

#include <BroadcastTimeClient.hxx>

Inheritance diagram for openlcb::BroadcastTimeClient:

Public Member Functions
	BroadcastTimeClient (Node *node, NodeID clock_id, bool configure_agent=false)
	Constructor.

	~BroadcastTimeClient ()
	Destructor.

bool	is_server_detected () override
	Has a time server been detected?

bool	is_server_self () override
	Test if this is a server.

void	handle_identify_global (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Handle requested identification message.

void	handle_identify_consumer (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Handle requested identification message.

void	handle_identify_producer (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Handle requested identification message.

void	handle_producer_identified (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Handle an incoming producer identified.

void	handle_event_report (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Handle an incoming event report.

Public Member Functions inherited from openlcb::BroadcastTime
virtual	~BroadcastTime ()
	Destructor.

void	set_time (int hours, int minutes)
	Set the time in seconds since the system Epoch.

void	set_date (int month, int day)
	Set the time in seconds since the system Epoch.

void	set_year (int year)
	Set the time in seconds since the system Epoch.

void	set_date_year_str (const char *date_year)
	Set the date and year from a C string.

void	set_rate_quarters (int16_t rate)
	Set Rate.

void	start ()
	Start clock.

void	stop ()
	Stop clock.

void	query ()
	Query the current time.

UpdateSubscribeHandle	update_subscribe_add (TimeUpdateCallback callback)
	Register a callback for when the time synchronization is updated.

void	update_subscribe_remove (UpdateSubscribeHandle handle)
	Unregister a callback for when the time synchronization is updated.

Node *	node ()
	Accessor method to get the Node reference.

NodeID	clock_id ()
	Accessor method to get the (48-bit) Clock ID.

EventId	event_base ()
	Access method to get the (64-bit) Event ID base.

const struct tm *	gmtime_recalculate ()
	Recalculate the struct tm representation of time.

const struct tm *	gmtime_get ()
	Get the last calculated reprentation of time.

Public Member Functions inherited from openlcb::SimpleEventHandler
	IGNOREFN (handle_event_report)

	IGNOREFN (handle_consumer_identified)

	IGNOREFN (handle_consumer_range_identified)

	IGNOREFN (handle_producer_identified)

	IGNOREFN (handle_producer_range_identified)

	IGNOREFN (handle_identify_consumer)

	IGNOREFN (handle_identify_producer)

Public Member Functions inherited from openlcb::EventHandler
virtual void	handle_consumer_identified (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done)
	Called on another node sending ConsumerIdentified for this event.

virtual void	handle_consumer_range_identified (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done)
	Called on another node sending ConsumerRangeIdentified.

virtual void	handle_producer_range_identified (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done)
	Called on another node sending ProducerRangeIdentified for this event.

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

void	notify () override
	Wakeup call arrived.

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 TimeBase
void	sync (const TimeBase &other)
	Synchronizes this time with a different clock.

std::pair< time_t, int16_t >	time_and_rate_quarters ()
	Get the time as a value of seconds relative to the system epoch.

time_t	compare_realtime (time_t t1, time_t t2)
	Get the difference in time scaled to real time.

time_t	time ()
	Get the time as a value of seconds relative to the system epoch.

struct tm *	gmtime_r (struct tm *result)
	Get the time as a standard struct tm.

int	date (int month, int day)
	Get the date (month/day).

int	day_of_week ()
	Get the day of the week.

int	day_of_year ()
	Get the day of the year.

int	year ()
	Get the year.

int16_t	get_rate_quarters ()
	Report the clock rate as a 12-bit fixed point number (-512.00 to 511.75).

bool	is_running ()
	Test of the clock is running.

bool	is_started ()
	Test of the clock is started (rate could still be 0).

bool	fast_sec_to_real_nsec_period (int16_t rate, time_t fast_sec, long long *real_nsec)
	Convert fast clock period to a period in real nsec.

bool	real_nsec_to_fast_sec_period (int16_t rate, long long real_nsec, time_t *fast_sec)
	Convert period in real nsec to a fast clock period.

bool	real_nsec_until_fast_time_abs (time_t fast_sec, long long *real_nsec)
	Convert a fast time to absolute nsec until it will occur.

bool	fast_sec_to_real_nsec_period_abs (time_t fast_sec, long long *real_nsec)
	Convert fast clock absolute (negative or positive) period to a positive (absolute) period in real nsec.

Private Member Functions
void	handle_updates (EventReport *event, bool report)
	Handle an incoming time update.

void	start_stop_logic (bool started)
	Perform a bit of logic that is required whenever the clock's running state is changed.

Action	initialize ()
	Initialize client by sending a time query.

Action	client_update ()
	Notification arrived that we should update our state.

Action	client_update_maybe ()
	Test if we are ready to update the client, or if we may want to wait for more messages (in the form of a burst) to come in first.

Action	client_update_commit ()
	commit the client update.

Action	rollover_pending ()
	Wait on the completion of a date rollover sequence.

void	waiting ()
	Setup the state flags to reflect that we are in a wait_and_call().

void	sleeping ()
	Setup the state flags to reflect that we are in a sleep_and_call().

void	wakeup ()
	wakeup the state machine.

	DISALLOW_COPY_AND_ASSIGN (BroadcastTimeClient)

Private Attributes
uint16_t	configureAgent_: 1
	instance can be used to configure clock

uint16_t	immediateUpdate_: 1
	true if the update should be immediate

uint16_t	immediatePending_: 1

uint16_t	sleeping_: 1
	future immediate upate expected

uint16_t	waiting_: 1
	true if stateflow is waiting

uint16_t	rolloverPending_: 1
	a day rollover is about to occur

uint16_t	rolloverPendingDate_: 1
	a day rollover is about to occur

uint16_t	rolloverPendingYear_: 1
	a day rollover is about to occur

uint16_t	serverDetected_: 1
	has a time server been detected

Additional Inherited Members
Public Types inherited from openlcb::BroadcastTime
typedef size_t	UpdateSubscribeHandle
	An opaque data element that is returned from update subscriber registration, and allows unregistering a subscriber.

typedef std::function< void(time_t old, time_t current)>	TimeUpdateCallback
	Callback type used for time update subscribers.

Public Types inherited from openlcb::EventHandler
using	EventReport = openlcb::EventReport

using	EventRegistryEntry = openlcb::EventRegistryEntry

using	EventId = openlcb::EventId

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.

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

Protected Member Functions inherited from openlcb::BroadcastTime
	BroadcastTime (Node *node, NodeID clock_id)
	Constructor.

virtual void	set_shortcut (uint64_t event)
	Try the possible set event shortcut.

void	service_callbacks (time_t old, time_t current)
	Service all of the attached update subscribers.

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 Attributes inherited from openlcb::BroadcastTime
struct tm	tm_
	the time we are last set to as a struct tm

Node *	node_
	OpenLCB node to export the consumer on.

EventId	eventBase_
	48-bit unique identifier for the clock instance

WriteHelper	writer_
	helper for sending event messages

StateFlowTimer	timer_
	timer helper

std::vector< TimeUpdateCallback >	callbacks_
	update subscribers

int16_t	rateRequested_
	pending clock rate

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

Protected Attributes inherited from TimeBase
long long	timestamp_ {OSTime::get_monotonic()}
	OS time at the last time update.

time_t	seconds_ {0}
	Clock time at the last time update.

int16_t	rate_ {0}
	effective clock rate

uint16_t	started_: 1
	true if clock is started

Detailed Description

Implementation of a Broadcast Time Protocol client.

Definition at line 45 of file BroadcastTimeClient.hxx.

Constructor & Destructor Documentation

◆ BroadcastTimeClient()

openlcb::BroadcastTimeClient::BroadcastTimeClient	(	Node *	node,
		NodeID	clock_id,
		bool	configure_agent = `false`
	)

inline

Constructor.

Parameters

node	the virtual node that will be listening for events and responding to Identify messages.
clock_id	48-bit unique identifier for the clock instance
configure_agent	if true, can configure clock server, if false, ignores all set_time/data/etc calls.

Definition at line 54 of file BroadcastTimeClient.hxx.

◆ ~BroadcastTimeClient()

openlcb::BroadcastTimeClient::~BroadcastTimeClient ( )

inline

Destructor.

Definition at line 72 of file BroadcastTimeClient.hxx.

Member Function Documentation

◆ client_update()

Action openlcb::BroadcastTimeClient::client_update ( )

inlineprivate

Notification arrived that we should update our state.

Returns: next state client_update_commit if an update is to be made, else next state client_update_wait if we are expecting more incoming clock set events or producer identified

Definition at line 284 of file BroadcastTimeClient.hxx.

◆ client_update_commit()

Action openlcb::BroadcastTimeClient::client_update_commit ( )

inlineprivate

commit the client update.

Returns: next state rollover_pending if a date rollover is in progress, else next state client_update

Todo:: As of 14 October 2018, newlib for armgcc uses 32-bit time_t. It seems that 64-bit time_t may become the default soon.

Definition at line 322 of file BroadcastTimeClient.hxx.

◆ client_update_maybe()

Action openlcb::BroadcastTimeClient::client_update_maybe ( )

inlineprivate

Test if we are ready to update the client, or if we may want to wait for more messages (in the form of a burst) to come in first.

Returns: next state client_updeate_commit if the burst is interrupted else next state client_update if the burtst is still in progress

Definition at line 306 of file BroadcastTimeClient.hxx.

◆ handle_event_report()

void openlcb::BroadcastTimeClient::handle_event_report	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Handle an incoming event report.

Parameters

entry	registry entry for the event range
event	information about the incoming message
done	used to notify we are finished

Implements openlcb::EventHandler.

Definition at line 221 of file BroadcastTimeClient.hxx.

◆ handle_identify_consumer()

void openlcb::BroadcastTimeClient::handle_identify_consumer	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Handle requested identification message.

Parameters

entry	registry entry for the event range
event	information about the incoming message
done	used to notify we are finished

Implements openlcb::EventHandler.

Definition at line 150 of file BroadcastTimeClient.hxx.

◆ handle_identify_global()

void openlcb::BroadcastTimeClient::handle_identify_global	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Handle requested identification message.

Parameters

entry	registry entry for the event range
event	information about the incoming message
done	used to notify we are finished

Implements openlcb::EventHandler.

Definition at line 95 of file BroadcastTimeClient.hxx.

◆ handle_identify_producer()

void openlcb::BroadcastTimeClient::handle_identify_producer	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Handle requested identification message.

Parameters

entry	registry entry for the event range
event	information about the incoming message
done	used to notify we are finished

Implements openlcb::EventHandler.

Definition at line 168 of file BroadcastTimeClient.hxx.

◆ handle_producer_identified()

void openlcb::BroadcastTimeClient::handle_producer_identified	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Handle an incoming producer identified.

Parameters

entry	registry entry for the event range
event	information about the incoming message
done	used to notify we are finished

Reimplemented from openlcb::EventHandler.

Definition at line 193 of file BroadcastTimeClient.hxx.

◆ handle_updates()

void openlcb::BroadcastTimeClient::handle_updates	(	EventReport *	event,
		bool	report
	)

private

Handle an incoming time update.

Parameters

entry registry entry for the event range @report true of this an event report, false if a Producer Identified

Definition at line 43 of file BroadcastTimeClient.cxx.

◆ initialize()

Action openlcb::BroadcastTimeClient::initialize ( )

inlineprivate

Initialize client by sending a time query.

Returns: next state is client_update

Definition at line 270 of file BroadcastTimeClient.hxx.

◆ is_server_detected()

bool openlcb::BroadcastTimeClient::is_server_detected ( )

inlineoverridevirtual

Has a time server been detected?

Returns: true if a time server has been detected, else false

Implements openlcb::BroadcastTime.

Definition at line 79 of file BroadcastTimeClient.hxx.

◆ is_server_self()

bool openlcb::BroadcastTimeClient::is_server_self ( )

inlineoverridevirtual

Test if this is a server.

Returns: true if a BroadcastTimeServer, else false

Implements openlcb::BroadcastTime.

Definition at line 86 of file BroadcastTimeClient.hxx.

◆ rollover_pending()

Action openlcb::BroadcastTimeClient::rollover_pending ( )

inlineprivate

Wait on the completion of a date rollover sequence.

Returns: next state client_update_commit if timer triggered, else next state initialize

Definition at line 391 of file BroadcastTimeClient.hxx.

◆ sleeping()

void openlcb::BroadcastTimeClient::sleeping ( )

inlineprivate

Setup the state flags to reflect that we are in a sleep_and_call().

Definition at line 414 of file BroadcastTimeClient.hxx.

◆ start_stop_logic()

void openlcb::BroadcastTimeClient::start_stop_logic ( bool started )

inlineprivate

Perform a bit of logic that is required whenever the clock's running state is changed.

Parameters

started true if the clock is started, else false

Definition at line 239 of file BroadcastTimeClient.hxx.

◆ waiting()

void openlcb::BroadcastTimeClient::waiting ( )

inlineprivate

Setup the state flags to reflect that we are in a wait_and_call().

Definition at line 407 of file BroadcastTimeClient.hxx.

◆ wakeup()

void openlcb::BroadcastTimeClient::wakeup ( )

inlineprivate

wakeup the state machine.

Definition at line 421 of file BroadcastTimeClient.hxx.

Member Data Documentation

◆ configureAgent_

uint16_t openlcb::BroadcastTimeClient::configureAgent_

private

instance can be used to configure clock

Definition at line 435 of file BroadcastTimeClient.hxx.

◆ immediatePending_

uint16_t openlcb::BroadcastTimeClient::immediatePending_

private

Definition at line 437 of file BroadcastTimeClient.hxx.

◆ immediateUpdate_

uint16_t openlcb::BroadcastTimeClient::immediateUpdate_

private

true if the update should be immediate

Definition at line 436 of file BroadcastTimeClient.hxx.

◆ rolloverPending_

uint16_t openlcb::BroadcastTimeClient::rolloverPending_

private

a day rollover is about to occur

Definition at line 440 of file BroadcastTimeClient.hxx.

◆ rolloverPendingDate_

uint16_t openlcb::BroadcastTimeClient::rolloverPendingDate_

private

a day rollover is about to occur

Definition at line 441 of file BroadcastTimeClient.hxx.

◆ rolloverPendingYear_

uint16_t openlcb::BroadcastTimeClient::rolloverPendingYear_

private

a day rollover is about to occur

Definition at line 442 of file BroadcastTimeClient.hxx.

◆ serverDetected_

uint16_t openlcb::BroadcastTimeClient::serverDetected_

private

has a time server been detected

Definition at line 443 of file BroadcastTimeClient.hxx.

◆ sleeping_

uint16_t openlcb::BroadcastTimeClient::sleeping_

private

future immediate upate expected

true if stateflow is waiting on timer

Definition at line 438 of file BroadcastTimeClient.hxx.

◆ waiting_

uint16_t openlcb::BroadcastTimeClient::waiting_

private

true if stateflow is waiting

Definition at line 439 of file BroadcastTimeClient.hxx.

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

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BroadcastTimeClient()

◆ ~BroadcastTimeClient()

Member Function Documentation

◆ client_update()

◆ client_update_commit()

◆ client_update_maybe()

◆ handle_event_report()

◆ handle_identify_consumer()

◆ handle_identify_global()

◆ handle_identify_producer()

◆ handle_producer_identified()

◆ handle_updates()

◆ initialize()

◆ is_server_detected()

◆ is_server_self()

◆ rollover_pending()

◆ sleeping()

◆ start_stop_logic()

◆ waiting()

◆ wakeup()

Member Data Documentation

◆ configureAgent_

◆ immediatePending_

◆ immediateUpdate_

◆ rolloverPending_

◆ rolloverPendingDate_

◆ rolloverPendingYear_

◆ serverDetected_

◆ sleeping_

◆ waiting_