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:
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:
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.
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.
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:
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.
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:
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:
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: