index previous next 

file name: netbase.hpp, netbase.cpp
classification: pure simulation
contents: abstract class ACNetwork, derived from CControlledObject and CCrashingModule, class CDelayer, derived from ACNetworkProcess, class CMessenger, derived from ACNetworkProcess
use: provides the basic functions needed by all network implementations
 

global items used by ACNetwork:

 
local items used by ACNetwork:

const addr broadcastAddress: the address used for sending a broadcast message.
 
 
member variables of class ACNetwork:

CDelayer *delayer: the delayer delays the message, then calls Transmit().

SRandomData distDataLambda:  the distribution data for choosing the broadcast latency of a message.
default and reset values: dist=Uniform, all other members are 0

SRandomData distDataOmega:  the distribution data for choosing the broadcast operation delay of a message.
default and reset values: dist=Uniform, all other members are 0

EBool initCalled_: is set to True by Init(), and to False by Dispose().
default and reset value: True

CNodeIdList *listOfNodes: the nodes that are connected to the network.
Note: in this class, the list is only used in SendMsg() to check if the sender node is connected, so it may be interpreted as a list of sender nodes.

CMessenger *messenger: the messenger delivers the message after its transmission time.

CNetworkAccountant *networkAccountant: a pointer to the network accountant, which manages the transmission delays.

SINT32 networkID_: ID of the network.
default: parameter networkID of the ctor

CRandom *random: a pointer to a random generator for obtaining all necessary random variables.
 
 
member functions of class ACNetwork:

ACNetwork (CControllingObject *ctrl, SINT32 networkID): Stores the network ID and calls Init() to set all members to their default values. Note that the ctor does not check the value of networkID. Nevertheless, you should only use positive values for the ID.

virtual ~ACNetwork(): Calls Dispose() to delete all dynamic members.

void Connect (SINT32 nodeID): Puts the nodeID into the list of nodes. Only nodes that are stored in this list can send messages to the network.

virtual void Crash (): Crashes the network (through setting member variable crashed to True). If the network was already crashed, the method has no effect. A crashed network will accept messages and delay them, but if Transmit() is called for a crashed network, the message is discarded.

void Deliver (SMsg *msg): The function is called by the messenger after the transmission time of the message has passed. It calls ModifyCrashStatus(), then checks the return value of Crashed(). If it returns True, the function sends event MessageLost and has no further effect. Otherwise, it sends event DeliverMessage and delivers the message to all lances of the receiver node calling CLance::Announce(). The receiver node is identified by the receiver nodeID stored in SMsg. The function obtains a local bufx and renvx structure from each Lance calling CLance::GetReceiveBuffer() and CLance::GetReceiveEnvelope(). The data is copied into it (the receive timestamps are stored in the renvx structure) and the buffers are passed to the appropriate Lance object, which must free the memory when it does not need it anymore.
Of SMsg, the following members must contain valid values:

void Disconnect (SINT32 nodeID): Removes the nodeID from the list of nodes. If the nodeID was not in the list, the function has no effect.

virtual void Dispose(): If initCalled is True, all dynamic members are deleted and initCalled is set to False. Since the delayer and messenger are dynamic, all messages still in their keeping will be discarded. The network accountant is dynamic as well, so all transmission data will be lost. If initCalled is False, the function has no effect.

virtual EBool ExecuteCommand (const SCommand& command): All supported commands return True.

All other commands are passed to the ExecuteCommand() function of the base class and its value is returned.

SINT32 GetNetworkID (): Returns the ID of the network.

virtual EBool GetParameter (SParameter& param) const: Returns True if the parameter could be read. If not specified otherwise, the supported parameters of this class assume that param is of type SSingleNetworkParameter.

All other parameters are first passed to the GetParameter() function of the base class CControlledObject. If it returns True, then that is the return value of this function as well. If it returns False, GetParameter() of member networkAccountant is called and its value is returned.

virtual void Init (): If initCalled is False, the function creates all dynamic members and sets the member variables to their reset values. initCalled is then set to True. If initCalled is already True, the function has no effect.

virtual void ReportCrashChange (): creates an event of type SNetCrashEvent, fills in all parameters and passes it to the base class.

virtual int ReportError (EReportType type, char *file, int line, char *expression): Adds the module (Network) and the module identifier (networkID) to the error report (ie., calls the appropriate global ReportError() function and returns its value).

virtual void ReportEvent (EEvent eventType): Reports a network event to the controlling object. The function creates an object of type SNetEvent, stores the eventType in type, and sets the module to Network. Then the object is passed on to the base class.

virtual void ReportMessageEvent (EEvent type, const SMsg *msg): Creates an object of type SNetMessageEvent, fills in all members, then passed the event to the base class.

void Reset (): Restores the initial state. The function simply calls Dispose() and then Init().

virtual void SendMsg (tenvx *tenv, bufx *buf, INT16 size, int area): If the sender node (the nodeID is found out through the function GetCurrentNodeID(), which returns the nodeID of the currently active process) is not in the list of nodes, the message is ignored (a report using macro Report() notifies the programmer of this condition). The message is also ignored if tenv is NULL.
Note that buf may be NULL as far as the network is concerned, but either the Lance (lance.hpp) or the CI functions (ci.hpp) should have checked that. The network creates a message structure of type SMsg and sets the following members:

Ater all these members have been set, SendMsg (SMsg*) is called, and afterwards the SMsg object is deleted.

virtual void SendMsg (SMsg *msg): pure virtual
Depending on SMsg::broadcast, the function should send the message to a single recipient or broadcast it. If SMsg::timestamped is True, it should timestamp the message calling SMsg::SetTime() with the sender clock value (you can obtain this value by calling the global function GetTimestamp(). With the help of the delayer and messenger, you should subject the message to all delays that occur in a network of the implemented type. Derived classes must overload this function to obtain a working network.

virtual EBool SetParameter (const SParameter& param): Returns True if the parameter could be set. If not specified otherwise, the supported parameters of this class assume that param is of type SSingleNetworkParameter.

All other parameters are first passed to the SetParameter() function of the base class CControlledObject. If it returns True, then that is the return value of this function as well. If it returns False, SetParameter() of member networkAccountant is called and its value is returned.

virtual void Transmit (SMsg *msg): The function transmits a message (between a pair of nodes, so SMsg::sender and SMsg::receiver must be valid). It obtains the transmission delay from the network accountant and gives a copy of the message to the messenger for delivery after that delay. If the delay obtained by the accountant makes the message early or late, event EarlyMessage or LateMessage is sent to the evaluation. If the message will arrive in time, event SendMessage is reported. If the network accountant does not have any data for the requested transmission, Report() is called to notify the programmer and the function has no effect.
Note: even if the network accountant is empty, transmissions from a node to itself are always possible: if no transmission delay is stored, the minimum delay of a transmission (stored in the network accountant) is assumed.
Note: Since the function is virtual, you may overload it in the derived class. You will have to overload it if you need to do something special to the message after if was delayed by the delayer.
Of SMsg, the following members must contain valid values:

 
global items used by CDelayer:  
class CDelayer: derived from abstract class ACNetworkProcess

Like all classes derived from ACNetworkProcess, the delayer can store a message of type SMsg for an arbitrary time (specified in seconds). The delay is requested by the network, and the delayer returns the message to the network after the specified time has passed. The class is a friend of ACNetwork.

Of SMsg, the following members must contain valid values:

virtual void Deliver (SMsg *msg): Returns a message to the network calling ACNetwork::Transmit(). The network is identified by the if_num stored in SMsg. If no network with the identifier given in if_num is found, an assert fails.
 
 
global items used by CMessenger:  
class CMessenger: derived from ACNetworkProcess

The messenger also stores messages of type SMsg for an arbitrary time. Again, storage is requested by the network, and the messenger returns the message to the network after the specified time has passed. The class is a friend of ACNetwork.

Of SMsg, the following members must contain valid values:

virtual void Deliver (SMsg *msg): Sets the process ID to the nodeID of the receiver node, which is identified by member receiver of SMsg. Then, ACNetwork::Deliver() is called to deliver the message. The network is identified by the if_num stored in SMsg. If no network with the identifier specified in if_num is found, an assert fails.
last modified: Fri Feb 5 18:56:29 1999