indexpreviousnext

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:

Note: both commands are first processed by ClockSync, which does its own activities before passing the command to the algorithm class. Thus, it can be assumed that in the case of ConnectNetwork the networkID is already stored in the list of connected networks, and that in the case of DisconnectNetwork the networkID was already removed from this list.

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:

All other parameters are not supported, and False is returned.

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:

All other parameters are not supported, and False is returned.

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.

virtual EBool StoreRate (const SRate& remoteRate, const CNtpTime& localTime, const CNtpTime& remoteTime, SINT32 networkID, const CAddr& netAddress, int area): Since no rate algorithm is implemented, the rate information of the remote node is not needed and thus ignored. The function always returns True. The function is called by ClockSync whenever a message with rate information of the remote clock arrives. You should overload the function in the derived class and implement the rate algorithm. virtual EBool StoreTime (const STimestamp& time, double resync, SINT32 networkID, const CAddr& netAddress, int area, EBool gps): Computes the current time interval of the remote node from the clock value time and puts it into the database. ReportInterval() is called to report the new input interval to the evaluation. The function returns True if successful, False if an entry was already there (in that case, no event is reported). The function is called by ClockSync whenever a timestamped message arrives. virtual void Suspend (): Deletes the database and creates it anew, sets timeValid to False. The function is called by the fixed part of ClockSync whenever the CSA is suspended.
 

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.


last modified: Fri Feb 5 18:55:55 1999