file name: algbase.hpp, algbase.cpp
classification: simulation
contents: class ACClockSyncAlgorithm
use: provides the base class for the user-defined part of the
clock synchronization module
Note: This is the base class for all synchronization algorithms.
If you plan to add your own algorithm to SimUTC, you should also take a
look at the implementation of an existing algorithm, p.e., FTA.
If your algorithm needs a duty timer, be sure to use a free
one.
global items used by ACClockSyncAlgorithm:
member variables of ACClockSyncAlgorithm:
SINT32
assocNetwork_: The associated network of the CSA. Only the data from
this network is used as input to the convergence function.
default and reset value: NoAccount
copied during assignment
CClockSync
*cs_: A pointer to the fixed part of the clock synchronization module.
In references to this member in the text below, it is often called ClockSync
instead of cs.
default: parameter cs of the ctor
CApplicationDatabase
*database: The database stores all data collected from the other applications.
EBool initCalled_:
Is set to True by Init(), to False by Dispose().
SExtendedTimestamp
*newClockValue: Contains the new clock timestamp computed by the convergence
function.
INT32
numberOfFaultyNodes: The number of faulty nodes that are tolerated.
default and reset value: 0
copied during assignment
INT32
numberOfNodes: The number of nodes in the system.
default and reset value: 1
copied during assignment
SRate
*rate: Contains the rate data of the associated (local) clock.
defaults: thetaMinus = WcRhoMinus,
thetaPlus = WcRhoPlus, u = 0
EBool
timeValid: It is set to True if newTime contains a valid
new clock value, False if the convergence function has failed.
default: False
member functions of ACClockSyncAlgorithm:
ACClockSyncAlgorithm
(CClockSync *cs): Creates newClockValue, sets timeValid
to its default value. Creates rate and calls ClockChanged()
to set its members to their default values, sets initCalled to
False and calls Init(). If cs is NULL, an assert fails.
Note: if derived classes have overloaded ClockChanged(),
they must call it in their ctor, because the call in the base class only
executes the base function (the derived class has not been constructed
yet).
virtual
~ACClockSyncAlgorithm (): Deletes rate and newClockValue
and calls Dispose().
virtual
void ClockChanged (): If GetClock() returns NULL, rate
is set to its default values. Otherwise, its theta members are set to the
worst case bounds of the clock. The function is called by ClockSync after
the clock pointer is set to a new clock. Derived classes should overload
the function to implement their own clock dependent initializations.
virtual
EBool ComputeNewDelay (double dmin, double dmax, SINT32 networkID, const
CAddr& netAddress): The function is called by StoreDelay()
to add new transmission delays (given by the bounds (dmin, dmax))
to the database. Transmission characteristics are specified with a deterministic
part delta and an upper and lower uncertainty epsilonPlus
and epsilonMinus. The new delta is the mean of any stored delta
and the mean of dmin, dmax. EpsilonPlus, epsilonMinus
are chosen so that the resulting interval encompasses both any old interval
stored and (dmin, dmax). The function always returns
True. Overload the function in the derived class to implement a different
strategy for the computation of the delay characteristics.
If the new transmission delay was computed successfully and the database
contains the nodeID for the <networkID, netAddress>
pair, then event DelayEstimation is sent to the
evaluation. It contains the networkID, the nodeID of the sender
node, and the new transmission delay estimations (delta, epsilon minus,
epsilon plus).
virtual
EBool ConvergenceFunction (): pure virtual
The function should return True if a new interval could be computed.
In that case, the function should store the new clock value in newClockValue
and set timeValid to True. If the computation has failed, the
function should return False and set timeValid to False. The function
is called by ClockSync to execute the CV.
EBool DeleteAssociation
(SINT32 networkID, SINT32 nodeID): Deletes the network address associated
with the key <networkID, nodeID> from the list of
addresses. If there is no entry, False is returned, else True is returned.
virtual
EBool ExecuteCommand (const SCommand& command): Supported commands:
virtual
void Dispose(): If initCalled is True, database
is deleted and initCalled is set to False. If initCalled
is already False, the function has no effect.
SINT32
GetAssociatedNetwork () const: Returns member assocNetwork,
which denotes the associated network. If no associated network exists,
NoAccount
is returned.
CClockInterface
*GetClock () const: Returns a pointer to the clock object
of ClockSync.
double
GetComputationDelayCompensation() const: Returns the duration (in
seconds) of the computation delay compensation used by ClockSync.
double
GetDelayCompensation() const: Returns the duration (in seconds) of
the delay compensation used by ClockSync.
EBool GetLocalRate
(SRate& data) const: If GetClock() returns a value different
from NULL, the current rate information of the local clock (stored in member
rate) is copied into data (that data is broadcast to the other
nodes) and True is returned. If GetClock() returns NULL, False
is returned and data is not modified. The function is called by
ClockSync to obtain the local rate information that is sent to the other
nodes in the course of rate synchronization.
void
GetOwnID (SINT32& nodeID, int& area) const: Obtains the nodeID
and area of the associated ClockSync object and assigns the data to nodeID
and area.
virtual
EBool GetParameter (SParameter& param) const: Returns True if the
parameter could be read. All supported parameters of this class assume
that param is of type SSingleParameter.
Supported parameters:
double
GetRatePeriod() const: Returns the duration (in seconds) of the rate
synchronization period used by ClockSync.
EBool
GetResynchronizationStatus() const: Returns cs::resynchronizing.
It is True if ClockSync does not distribute its own timestamp, False if
ClockSync fully takes part in the synchronization.
double
GetRoundPeriod() const: Returns the duration (in seconds) of the round
period used by ClockSync.
virtual
void Init(): If initCalled is False, the function creates
the database and sets the members to their reset values. Member initCalled
is then set to True. If initCalled is already True, the function
has no effect.
ACClockSyncAlgorithm&
operator= (const ACClockSyncAlgorithm& alg): copies all relevant
configuration data from alg into the own members. This does not
copy algorithm specific data like the measured delays or the local rate,
just general data. All members that are copied by this operator are marked
with "copied during assignment" in the above list of members.
virtual
void PreloadNewClockValue (double loadAt): Preloads the clock to amortize
to the new clock value computed in ConvergenceFunction(). If the
convergence function was not successful and the computed clock value is
marked invalid, the function does not have any effect. If the pointer returned
by GetClock() is NULL (that is, cs::clock is NULL), an
assert fails. The function is called by ClockSync to set the clock
to the new value computed by the CV.
Note: for preloading the clock, function CClockInterface::PreloadTimestamp()
is used (which uses a fixed amortization strategy).
virtual
void Reset (): Calls Dispose(), then Init().
virtual
int ReportError (EReportType type, char *file, int line, char *expression):
Calls the error report function of ClockSync.
virtual
void ReportEvent (SEvent *event): Sets the event type to
UserEvent,
the module to ClockSync, and passes the event to the
ReportEvent()
function of ClockSync. If event is NULL, an assert fails.
virtual
void ReportInterval (EBool input, const STimeInterval& interval):
Creates a new event of type SApplTimeEvent,
sets the event type to IntervalEvent,
the module to ClockSync, the input member to
input
and the interval member to interval. Then it passes the
event to the ReportEvent() function of ClockSync.
Note: derived classes should call the function in ConvergenceFunction()
to report the resulting interval of the CV, and if they overload function
StoreTime(),
they should also report the input interval computed in their function.
virtual
void ReportRate (EBool input, const SRate& rate, double refPoint):
Creates a new event of type SApplRateEvent,
sets the event type to RateEvent, the
module
to ClockSync, the input member to input, the
rate
member to rate and the refPoint member to refPoint.
Then it passes the event to ReportEvent() of ClockSync.
EBool
SetAssociatedNetwork (SINT32 networkID): Searches for networkID
in the list of connected networks of ClockSync. If the entry exists, member
assocNetwork
is set to networkID , event ChangeAssociation
is reported to the evaluation and the function returns True. Otherwise,
the function returns False and has no effect.
virtual
EBool SetAssociation (SINT32 networkID, const CAddr& address, SINT32
nodeID): Stores the association <networkID, address,
nodeID>.
If a different association of either the address or the nodeID
already exists, the new data is ignored. Overload the function in the derived
class to obtain different behaviour. The function returns True if the triple
could be stored (or if it was already stored), else False. The function
is called by ClockSync whenever a message from a remote node arrives.
virtual
void SetNewClockValue (): Sets the clock to the new value computed
in ConvergenceFunction(). If the convergence function was not
successful and the computed clock value is marked invalid, the function
does not have any effect. If the pointer returned by GetClock()
is NULL (that is, cs::clock is NULL), an assert fails. The function
is called by ClockSync to set the clock to the new value computed
by the CV.
Note: for setting the new clock value, function CClockInterface::SetTimestamp()
is used (which uses a fixed amortization strategy).
Note: the function has been replaced by PreloadNewClockValue()
and will be removed in future versions.
virtual
EBool SetParameter (const SParameter& param): Returns True if the
parameter could be set. All supported parameters of this class assume that
param
is of type SSingleParameter. Supported parameters:
void
SetResynchronizationStatus (EBool status) const: Sets the value of
cs::resynchronizing
to status. Set the status to True if it is obvious that the clock
value is wrong and/or that distribution of that value would deteriorate
the synchronization results. Set it to False if ClockSync should send the
value of the local clock.
virtual
EBool StoreDelay (double localDelay, double remoteDelay, const SRate&
remoteRate, SINT32 networkID, const CAddr& netAddress, int area):
Processes the delays (does drift compensation for both), computes the new
transmission delay data and stores it in the database. The function returns
False if the upper bound for the transmission delay is negative. If the
lower bound for the delay is negative, then it is set to zero and the upper
bound is adjusted so that the mean of the new delay bounds is the same
as that of the old bounds. If the adjustment makes the upper bound negative,
then False is returned and an error report is issued. Otherwise, the function
calls ComputeNewDelay() and returns the value of that function.
The function is called by ClockSync whenever a delay measurement message
arrives.
Note: member rate is used for drift compensation of
the local clock.
local (static) functions of the implementation file:
inline double
Max (double a, double b): Returns the maximum of a and b.
inline double
Min (double a, double b): Returns the minimum of a and b.