OverSim - Best/Necessary Practices

General

• Declare each module in a separate file
• Wrap simple modules through compound modules, even if there is only 1 simple module. This is where you connect in/out gates. Use IOverlay or ITier interfaces
• Use @class() property to tell compiler to use our own C++ definition of a simple module
• Use Define_Module() method to add a module definition class to simulation
• Better not to do anything until underlay is properly initialized. Overlay may be in the initialization phase  if you want to measure bootstrap phase. Can check using underlayConfigurator->isInInitPhase()

Applications

Suppose our application name is myapp

• All applications must be stored in /src/applications/ within OverSim directory, e.g., /src/applications/myapp/
• Package name should be oversim.applications.myapp
  
• Each application must be extended from BaseApp class (.ned files & C++ classes)
• This will add default in/out gates & parameters to the module &, also C++generic methods such as initializeApp() or deliver()
• Use the interfaces defined in ITier using keyword like, e.g., module myapp like ITier
• Bind to a UDP port, if application is suppose to receive messages directly, use bindToPort()
• Port numbers between 1024-1034 are reserved
•  Implement required methods defined in BaseApp. In minimum, following methods need to be implemented (click here for details):
• initializeApp(int stage)
• finishApp()
• handleTimerEvent(cMessage* msg)
• deliver(OverlayKey& key, cMessage* msg)
• If you want to use forward() method, e.g., to do caching, you need to use semi-recursive or recursive routing. I figiured out RPC calls don't call forward() in intermediate nodes. forward( ) will be called in source & destination node for all routing schemes
• Remove TTL timers for DHT entries, if you don't need keys to expire. There will be a seperate time for each key stored in the DHT thus consume lots of memory
• Use lookup messages only if you need to put multiple replicas. Otherwise, they just add unnecessary overhead

Overlays

Suppose our application name is myoverlay

• All overlays must be stored in /src/overlay/ inside OverSim directory, e.g., /src/overlay/myoverlay/
• Package name should be oversim.overlay.myoverlay
  
• Each application must be extended from BaseOverlay class (.ned files & C++ classes)

• This will add default in/out gates & parameters to the module &, also C++ generic methods such as initializeOverlay() or joinOverlay()
• Use the interfaces defined in IOverlay using keyword like
• Bind to a UDP port if overlay is suppose to receive messages directly, use bindToPort() 
• Port numbers between 1024-1034 are automatically used by overlay
• Implement required methods defined in BaseOverlay. In minimum, following methods need to be implemented:
• initializeOverlay(int stage) - Can be used to initialize the overlay node, read parameter values, set key, set statistic collectors, start timers, etc. stage can be either MIN_STAGE_APP (this module is being created) or MAX_STAGE_APP (all modules were created)
• finishOverlay() - Called when module is terminating. Can be used to summarize stat, delete remaining messages/timers, etc. New OverSim version seems to be motivating us to delete messages in the destructor
• joinOverlay() - Define what to do when a node is added to the system. Can be used to establish connections with successor/predecessor & identify fingers. Also indicate the simulator that overlay is now ready
• NodeVector* findNode(const OverlayKey& key, int numRedundantNodes, int numSiblings) - Is called by message forwarding function to determine potential next hops, e.g., finger node selection in Chord can go here.
• bool isSiblingFor(const NodeHandle& node, const OverlayKey& key, int numSiblings, bool* err) - Am I the root, i.e.., node responsible for storing key?
• int getMaxNumSiblings() - Maximum number of siblings (potential next hops) to be queried
• int getMaxNumRedundantNodes() - Maximum number of redundant nodes (which store the same key) to be queried
• Make sure overlay is in correct state before issuing messages, e.g., it is not sufficient for Chord to be just initialized, it should be in READY state. Otherwise your calls to overlay will timeout. State can be checked using overlay->getState()

Messages

• RPC messages are preferred over overlay & UDP messages because they are efficient & OverSim provides lot more functionality to easily dealt with them
• Should be defined in the layer (Tier 1, overlay, etc.) that the message is being used by
• File name ends with .msg
• When you compile your application or overlay, message files will be automatically complied to generate appropriate classes
• Use keyword noncobject to indicate it's not a message class
• Set messages length if statistics need to be collected. Without message length, latency don't make sense 
• Make sure to delete messages that are no longer need (delete only once!)
• The name of a RPC call message should end with the word Call while the name of a response message should end with the word Response
• Call messages are inhereted from BaseCallMessage
• Response messages are inherited from BaseResponseMessage
• Use sendInternalRPCCall() to communicate between layers in the same peer. 
• Use DHTputCAPICall & DHTgetCAPICall messages to communicate between tier2 & application 
• Use LookupCall messages to communicate between application & overlay

Keys

• Derive keys from OverlayKey class
• When comparing keys it's more reliable to use a method like isBetween( ) rather than  comparators such as >, >=, <, and <=. Otherwise, it could lead to errors that are not abvious, e.g., 15 > 2 is not always true if address space circular and address range is [0-15].
• Overlay key can be accessed from upper layers using overlay->getThisNode().getKey() function.