The Polito P2P-TV Simulator, V3-alpha

1. Installation

Use your favourite subversion client to download a working copy of the P2PTVsim distribution. Then either:

for Linux, cd into your download directory and type make, or
for Windows + Visual Studio, cdinto the simulator subdirectory of the download directory and open simulator.sln in Visual Studio, or
for anything else, just compile all the .cpp files and link the object files together.

2. Running the simulator

This new version of the simulator is configured primarily through a configuration file called config.txt, which must be in the current directory when the simulator is run. Look through the supplied config.txt to see what your options are. Apart from all the various bandwidth parameters you must choose:

an overlay type, which sets the configuration (sets of peers and their interconnections -- current options are GNR, WS, GNP, TREE, MC, BWO, OVERLAY_TESTING)
the chunk-scheduling algorithm (currently one of LATEST_RANDOM, LATEST_BA, RANDOM_RANDOM, RANDOM_BA, COLOURED, TESTING_PEER) and
the host type, which sets the network-level timing of chunk-transmission (current options are OLD_SIM, TWEAKED_OLD_SIM, and PRIORITY_SHARING)

The remaining parameters, set through the command line, are the random number seed, the number of hosts, the so-called 'degree' parameter for the overlay connection algorithm and the number of chunks to diffuse. A final optional random number seed can be used to set separately the seed for the chunk diffusion process.

A typical command to run the simulator would look something like the following:

sim 12345 1000 4 2000 13254

That would create an overlay of 1000 nodes using a random number seed of 12345 with a degree of 4 being used by whatever overlay graph building function is specified in config.txt. The program would run a diffusion of 2000 chunks, starting the diffusion with a random seed of 13254.

Output from the simulator is a set of text files with extension .out. See the code to understand the exact content of each of these.

3. Understanding the code

The header files of the project are documented with doxygen. If you have this installed, just cd into your downloaded distribution directory and type the command doxygen. You can then browse the output in the generated html directory.

If you don't have doxygen, either download it (recommended!) or just browse through the source, using the information in the following two subsections as an overview.

Good luck!

3.1 File List (alphabetical order)

Here is a list of all documented files with brief descriptions:

chunk.cpp Implementation of the CHUNK struct and the functions that generate and access CHUNKs

chunk.h Defines the CHUNK struct

edgenetwork.cpp Defines the base EDGE_NETWORK class

edgenetwork.h Declares the base EDGE_NETWORK class

event.cpp Implementations of the Event structure and the internal Event List

event.h Defines the types of events and the functions to schedule events and run the main event loop

globals.cpp Just defines the two system-wide global variables

globals.h Defines global variables and constants for the simulator

host.cpp A file containing the implementation of the HOST class

host.h A file containing the declarations of the HOST class

link.cpp Defines the LINK class, which represents edges in the OVERLAY class

link.h Defines the LINK class, which represents edges in the OVERLAY class

main.cpp The main driver function for the simulator

misc.cpp Implementations of the functions declared in misc.h

misc.h A file of miscellaneous functions that have no obvious home

network.cpp Defines the implementation of the base NETWORK class

network.h Declares the base NETWORK class

overlay.cpp Implementations of the various OVERLAY methods

overlay.h Defines the OVERLAY class

overlaytypes.cpp Defines the various concrete OVERLAY subtypes

overlaytypes.h Defines the various subtypes of the OVERLAY class

peer.h Implementations of the PEER methods declared in peer.h, except for those already declared inline

peertypes.h Defines the various subclasses of the PEER class

propertymap.h Define the PROPERTY_MAP class

random.cpp Random-number generating functions

random.h A file of unknown parentage containing various methods used to calculate random distributions

router.cpp Defines the implementation of the ROUTER class

router.h The declaration of the ROUTER class

stats.cpp Implementations of most statistics gathering and printing functionality

stats.h A file containing the declarations of the statistics-gathering classes

window.cpp Implementations of the window-handling functions declared in window.h

window.h Define the WINDOW class, a sliding window of chunks available for transmission to other peers

3.2 Class/Struct List (alphabetical order)

Here are the classes, structs, unions and interfaces with brief descriptions:

BWO_OVERLAY A BWO_OVERLAY is an MBW_OVERLAY in which the overlay is chosen so that high-bandwidth peers are closest to the source

CHUNK The CHUNK struct

Download A PRIORITY_BASED_HOST allows multiple chunks from lower-speed sources to be downloaded by the host at the same time, but in a prioritised manner

GNP_OVERLAY A GNP_OVERLAY is an MBW_OVERLAY in which each host is given a set of neighbours selected randomly, with the number of neighbours to choose for each peer taken from a poisson distribution

GNR_OVERLAY A GNR_OVERLAY is an MBW_OVERLAY in which each host is given a randomly selected set of neighbours

LINK The LINK class, representing edges in the network overlay

LINK_STATS The LINK_STATS class, an instance of which is present in every link for recording information of a purely statistical nature

MBW_OVERLAY An MBW_OVERLAY is a overlay with a set of multi-bandwidth peers, randomly allocated to one of 4 different classes

MC_OVERLAY An MC_OVERLAY is a multicoloured overlay in which peers have randomly chosen colours (see the COLOUR enum in globals.h) and the chunks also have colours

NETWORK The NETWORK class, which currently is concerned only with providing to the HOSTs latency information on a particular path between two hosts (and so might, for example, model various forms of congestion)

OLD_SIM_HOST An OLD_SIM_HOST is intended to generate an event sequence that more-or-less matches the events generated by the old simulator

OVERLAY The OVERLAY class

PATH A PATH is loosely-equivalent to a socket in that it defines an end-to-end route for chunks through the various layers of the network

PEER The PEER class, representing a peer (peer) in an overlay network

PEER_STATS The PEER_STATS class, an instance of which is present in every peer for recording information of a purely statistical nature

PROPERTY_MAP The PROPERTY_MAP class

ROUTER A ROUTER is constructed with the default constructor then attached to a network -- the network sets its id and network fields

TEST_OVERLAY A TEST_OVERLAY is used for testing. Available to all

TREE_OVERLAY A TREE_OVERLAY is an MBW_OVERLAY that's a tree with peer 0 as the root

TWEAKED_OLD_SIM_HOST A TWEAKED_OLD_SIM_HOST is like the OLD_SIM_HOST except that when a high-bandwidth host is feeding a low-bandwidth one, the source completes its send in a time determined by its own upload bandwidth, and gets called back at that time, allowing it to schedule other chunks

WS_OVERLAY A WS_OVERLAY is intended to approximate a Watts-Strogatz "small world" overlay

chunk.cpp	Implementation of the CHUNK struct and the functions that generate and access CHUNKs
chunk.h	Defines the CHUNK struct
edgenetwork.cpp	Defines the base EDGE_NETWORK class
edgenetwork.h	Declares the base EDGE_NETWORK class
event.cpp	Implementations of the Event structure and the internal Event List
event.h	Defines the types of events and the functions to schedule events and run the main event loop
globals.cpp	Just defines the two system-wide global variables
globals.h	Defines global variables and constants for the simulator
host.cpp	A file containing the implementation of the HOST class
host.h	A file containing the declarations of the HOST class
link.cpp	Defines the LINK class, which represents edges in the OVERLAY class
link.h	Defines the LINK class, which represents edges in the OVERLAY class
main.cpp	The main driver function for the simulator
misc.cpp	Implementations of the functions declared in misc.h
misc.h	A file of miscellaneous functions that have no obvious home
network.cpp	Defines the implementation of the base NETWORK class
network.h	Declares the base NETWORK class
overlay.cpp	Implementations of the various OVERLAY methods
overlay.h	Defines the OVERLAY class
overlaytypes.cpp	Defines the various concrete OVERLAY subtypes
overlaytypes.h	Defines the various subtypes of the OVERLAY class
peer.h	Implementations of the PEER methods declared in peer.h, except for those already declared inline
peertypes.h	Defines the various subclasses of the PEER class
propertymap.h	Define the PROPERTY_MAP class
random.cpp	Random-number generating functions
random.h	A file of unknown parentage containing various methods used to calculate random distributions
router.cpp	Defines the implementation of the ROUTER class
router.h	The declaration of the ROUTER class
stats.cpp	Implementations of most statistics gathering and printing functionality
stats.h	A file containing the declarations of the statistics-gathering classes
window.cpp	Implementations of the window-handling functions declared in window.h
window.h	Define the WINDOW class, a sliding window of chunks available for transmission to other peers

BWO_OVERLAY	A BWO_OVERLAY is an MBW_OVERLAY in which the overlay is chosen so that high-bandwidth peers are closest to the source
CHUNK	The CHUNK struct
Download	A PRIORITY_BASED_HOST allows multiple chunks from lower-speed sources to be downloaded by the host at the same time, but in a prioritised manner
GNP_OVERLAY	A GNP_OVERLAY is an MBW_OVERLAY in which each host is given a set of neighbours selected randomly, with the number of neighbours to choose for each peer taken from a poisson distribution
GNR_OVERLAY	A GNR_OVERLAY is an MBW_OVERLAY in which each host is given a randomly selected set of neighbours
LINK	The LINK class, representing edges in the network overlay
LINK_STATS	The LINK_STATS class, an instance of which is present in every link for recording information of a purely statistical nature
MBW_OVERLAY	An MBW_OVERLAY is a overlay with a set of multi-bandwidth peers, randomly allocated to one of 4 different classes
MC_OVERLAY	An MC_OVERLAY is a multicoloured overlay in which peers have randomly chosen colours (see the COLOUR enum in globals.h) and the chunks also have colours
NETWORK	The NETWORK class, which currently is concerned only with providing to the HOSTs latency information on a particular path between two hosts (and so might, for example, model various forms of congestion)
OLD_SIM_HOST	An OLD_SIM_HOST is intended to generate an event sequence that more-or-less matches the events generated by the old simulator
OVERLAY	The OVERLAY class
PATH	A PATH is loosely-equivalent to a socket in that it defines an end-to-end route for chunks through the various layers of the network
PEER	The PEER class, representing a peer (peer) in an overlay network
PEER_STATS	The PEER_STATS class, an instance of which is present in every peer for recording information of a purely statistical nature
PROPERTY_MAP	The PROPERTY_MAP class
ROUTER	A ROUTER is constructed with the default constructor then attached to a network -- the network sets its id and network fields
TEST_OVERLAY	A TEST_OVERLAY is used for testing. Available to all
TREE_OVERLAY	A TREE_OVERLAY is an MBW_OVERLAY that's a tree with peer 0 as the root
TWEAKED_OLD_SIM_HOST	A TWEAKED_OLD_SIM_HOST is like the OLD_SIM_HOST except that when a high-bandwidth host is feeding a low-bandwidth one, the source completes its send in a time determined by its own upload bandwidth, and gets called back at that time, allowing it to schedule other chunks
WS_OVERLAY	A WS_OVERLAY is intended to approximate a Watts-Strogatz "small world" overlay