root / branches / multithread / docs / devel.html

Revision 2, 51.1 kB (checked in by jordi, 2 years ago)

Imported PlanetSim 3.0

Line 
1<html>
2        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3    <html>
4      <head>
5          <title>
6            PlanetSim: An Overlay Network Simulation Framework - Developer's Guide
7          </title>
8        <style type="text/css">
9          @import url("style/tigris.css");
10          @import url("style/maven.css");
11</style>
12        <link rel="stylesheet" href="style/print.css" type="text/css" media="print"></link>
13        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></meta>
14      </head>
15      <body class="composite">
16        <div id="banner0">
17          <table border="0" width="100%" cellpadding="8" cellspacing="0" id="table1">
18            <tr>
19              <td>
20                  <img border="0" src="images/planetsimlogo.jpg" width="251" height="157"><a href="index.htm"><span style="text-decoration: none"></img></span></a>
21                  <span style="text-decoration: none">&nbsp;&nbsp;&nbsp;&nbsp;
22                  <span style="font-weight: 700"><a href="index.html">An Overlay Network Simulation Framework</a></span></span></td>
23              <td width="222">
24                <div id="login" align="right">
25                    <a href="http://ants.etse.urv.es/planet">
26                    <img border="0" src="images/logoplanet.jpg" width="150" height="142"></a></div>
27              </td>
28            </tr>
29          </table>
30        </div>
31        <div id="breadcrumbs">
32          <table border="0" width="98%" cellpadding="4" cellspacing="0" id="table2">
33            <tr>
34                <td width="286"><font size="2">Last Updated: 6 April 2005</font></td>
35              <td>
36                <div align="right">
37      <font size="2">
38                <a href="http://ants.etse.urv.es/planet"><img class="handle" src="images/none.png" alt=""></img>PLANET Project Page</a>
39      |
40      <a href="http://www.etse.urv.es/recerca/ast/"><img class="handle" src="images/none.png" alt=""></img>AST
41                Research Group</a>&nbsp;
42                </font>
43                </div>
44              </td>
45            </tr>
46          </table>
47        </div>
48        <table border="0" width="100%" cellpadding="8" cellspacing="0"> 
49          <tr valign="top">
50            <td>
51              <div id="bodycol">
52                <div class="app">
53    <h3><span lang="en-us">
54                        <font size="2" color="#FFFBF0"><b>Developer's Guide</b></font></span></h3>
55    <p class="MsoNormal" style="text-align: justify; text-autospace: none">
56                        <span lang="EN-GB"><font size="2">PlanetSim&#8217;s architecture comprises
57                        three main extension layers constructed one atop another. As we can
58                        see in the next figure, overlay services are built in the
59                        application layer using the standard Common API façade. This façade
60                        is built on the routing services offered by the underlying overlay
61                        layer. Besides, the overlay layer obtains proximity information to
62                        other nodes asking information to the Network layer.</font></span></p>
63                        <p class="MsoNormal" style="text-align: center; text-autospace: none">
64                        <img border="0" src="images/classes.jpg" width="855" height="534"></p>
65                        <p class="MsoNormal" style="text-align:justify"><span lang="EN-GB">
66                        <font size="2">We propose a novel service to be
67                        supported by overlay simulators: a façade API to develop overlay
68                        services and applications on top of existing overlays. This API is
69                        based on the proposed Common API (CAPI) for structured Peer-to-Peer
70                        overlays. The main motivation for this decision is the plethora of
71                        applications and services that can be built on top of structured
72                        overlays.</font></span></p>
73        <p class="MsoNormal" style="text-align:justify"><b>
74        <a href="http://iptps03.cs.berkeley.edu/final-papers/api.ps">
75                        <font size="2" color="#006699">Towards a Common API for Structured Peer-to-Peer
76                        Overlays</font></a><font size="2" color="#006699"> </font></b>
77        <font size="2"> In this paper, we describe an
78                        ongoing effort to define common APIs for structured peer-to-peer
79                        overlays and the key abstractions that can be built on them. In
80                        doing so, we hope to facilitate independent innovation in overlay
81                        protocols, services, and applications, to allow direct experimental
82                        comparisons, and to encourage application development by third
83                        parties.</font></p>
84    <h3><span lang="en-us">
85                        <font size="2" color="#FFFBF0"><b>1) Network Layer</b></font></span></h3>
86                                <p class="MsoNormal">
87                        <span lang="EN-GB"><font size="2">The Network layer dictates the
88                        overall life cycle of the framework by calling the appropriate
89                        methods in the overlay&#8217;s Node and obtaining routing information to
90                        dispatch messages through the Network. As we explain later, the
91                        Network layer can be implemented either by the NetworkSimulator or
92                        NetworkWrapper. Developers can thus transition from simulation to
93                        experimentation environments in a transparent way.</font></span></p>
94        <p class="MsoNormal">
95                                <span lang="en-gb"><font size="2">In the next figure, we can see
96                                a network creation, where the simulator constructs all nodes and
97                                joins these on the new network.</font></span></p>
98        <p class="MsoNormal">
99                                &nbsp;</p>
100        <p class="MsoNormal" style="text-align: center">
101                                <img border="0" src="images/seq1.png" width="733" height="615"></p>
102                <p class="MsoNormal"><span lang="en-us"><font size="2">An another form
103                to create a network is with an event file. </font></span>
104                <span lang="EN-GB">
105                <span style="font-style: normal; font-variant: normal; font-weight: normal; ">
106                <font size="2">You have </font>
107                </span><font size="2">write an event file with the next event format :</font></span></p>
108        <p class="MsoNormal">&nbsp;</p>
109        <p class="MsoNormal"><span lang="EN-GB"><font size="2" face="Courier">&nbsp;&nbsp;&nbsp;&nbsp; at time [JOIN|LEAVE|FAIL]
110                PARAM0 [PARAM1] NUM_EVENTS</font></span></p>
111        <p class="MsoNormal">&nbsp;</p>
112        <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;Samples:</font></span></p>
113        <p class="MsoNormal">&nbsp;</p>
114                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font face="Courier">
115                </font> </font>
116                <font face="Courier">
117                <b><font size="2">at 3 JOIN 32342322 32342322 1</font></b></font></span></p>
118                <p class="MsoNormal">&nbsp;</p>
119                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; At time
120                3, a new node with id 32342322 joins using itself as bootstrap, one
121                time.</font></span></p>
122                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;</font></span></p>
123                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </font>
124                <b><font size="2" face="Courier">at 14 JOIN&nbsp; 22333564 32342322&nbsp; 1</font></b></span></p>
125                <p class="MsoNormal">&nbsp;</p>
126                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; At time
127                14, a new node with id 22333564 joins using the existing node 32342322
128                as bootstrap, one time. </font></span></p>
129                <p class="MsoNormal">&nbsp;</p>
130                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </font>
131                <b><font size="2" face="Courier">at 400 LEAVE 32342322 &nbsp;1</font></b></span></p>
132                <p class="MsoNormal">&nbsp;</p>
133                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; At time
134                400, the node with id 32342322 leaves.</font></span></p>
135                <p class="MsoNormal">&nbsp;</p>
136                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </font>
137                <b><font size="2" face="Courier">at 502 FAIL 22333564 1</font></b></span></p>
138                <p class="MsoNormal">&nbsp;</p>
139                <p class="MsoNormal"><span lang="EN-GB"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; At time
140                502, &nbsp;the node with id 22333564 crashes.</font></span></p>
141                <p class="MsoNormal">&nbsp;</p>
142                <p class="MsoNormal"><span lang="EN-GB"><font size="2">Also you&nbsp; can generate automatic join event file using
143                the script genfile</font></span></p>
144                <p class="MsoNormal">&nbsp;</p>
145                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB">
146                <font size="2">&gt;&gt; cd bin</font></span></p>
147                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB">
148                <font size="2">&gt;&gt; genfile name_file topology num_nodes delay_steps</font></span></p>
149        <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
150                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB"><b>
151                <font size="2">name_file</font></b><font size="2"> <b>&nbsp;</b>: name
152                of the output file to generate</font></span></p>
153                <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
154                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB"><b>
155                <font size="2">topology</font></b><font size="2">&nbsp; : choose a (R)andom
156                or a (D)istributed scheme</font></span></p>
157                <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
158                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB"><b>
159                <font size="2">num_nodes</font></b><font size="2"> : total number of
160                nodes </font></span></p>
161                <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
162                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB"><b>
163                <font size="2">delay_steps</font></b><font size="2"> : number of steps
164                between two joins</font></span></p>
165                <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
166                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB">
167                <font size="2">&nbsp;Example :</font></span></p>
168                <p class="MsoNormal" style="margin-left:18.0pt"><span lang="EN-GB">
169                <font size="2">&nbsp;&gt;&gt; genfile test_join1000d.txt D 1000 3</font></span></p>
170        <p class="MsoNormal" style="text-align: center">
171                                </br></p>
172    <h3><span lang="en-us"><font color="#FFFBF0" size="2">
173                                <b>2) Overlay Layer
174                                : Protocol Extension</b></font></span></h3>
175                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
176                                <span lang="EN-GB"><font size="2">The main conceptual entity and
177                                obvious hotspot of this layer is the Node. A node contains
178                                incoming and outgoing message queues and methods for sending and
179                                receiving/ processing messages. Each particular node must then
180                                include a complete behaviour or protocol that will dictate which
181                                messages to send in specific times and how to react to incoming
182                                messages. Furthermore, to create a new overlay, the embedded protocol must define its own
183                                messages with specific information to arrange the overlay. This
184                                also implies that developers should be able to define their own
185                                message types (hotspot).</font></span></p>
186                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
187                                <span lang="EN-GB"><font size="2">&nbsp;</font></span></p>
188                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
189                                <span lang="EN-GB"><font size="2">At the overlay layer, the
190                                communication is bidirectional with both the application and
191                                network layers. With the application layer, the Node notifies
192                                the Application of received messages (upcalls) and it is invoked
193                                by the EndPoint façade in order to route messages or obtain
194                                routing state information (downcalls). Both the EndPoints and the
195                                Nodes exchange RouteMessage types. A RouteMessage contains
196                                source and target identifiers, as well as information regarding
197                                the next hop in the overlay. It is also possible to modify the
198                                next hop route at the application or overlay layers in order to
199                                alter the routing scheme.</font></span></p>
200                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
201                                <span lang="EN-GB"><font size="2">&nbsp;</font></span></p>
202                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
203                                <span lang="EN-GB"><font size="2">With the network layer, the
204                                Node hotspot provides the template methods (<i>join</i>, <i>
205                                leave</i>, <i>fail </i>and <i>process</i>) that determine the
206                                life&#8217;s cycle of every node. The method <i>process </i>contains
207                                the specific protocol each node maintains to create the overlay.
208                                Besides, every node has an incoming and an outgoing message
209                                queue; incoming messages are parsed every step in the <i>process
210                                </i>method, and the <i>send </i>method moves messages to the outgoing queue.</font></span></p>
211                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
212                                <span lang="EN-GB"><font size="2">&nbsp;</font></span></p>
213                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
214                                <span lang="EN-GB"><font size="2">To identify nodes in the
215                                overlay, the simulator employs three main entities: Id,
216                                IdFactory and NodeHandle. Ids are custom number types of 32 to
217                                160 bits that identify nodes in the overall key based routing
218                                scheme. The extensible IdFactory permits to define custom Id
219                                generation schemes in each overlay. Additionally, NodeHandles
220                                contain IP to Id value pairs for each node. Furthermore, a
221                                NodeHandle provides a <i>proximity </i>method that queries the
222                                Network to obtain network proximity information. </font></span>
223                                </p>
224                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
225                                <span lang="EN-GB"><font size="2">&nbsp;</font></span></p>
226                                <p class="MsoNormal" style="text-align: justify; text-autospace: none">
227                                <span lang="EN-GB"><font size="2">This information is important
228                                to design locality sensitive overlays. As we can see, we have
229                                many upcalls that define the Node&#8217;s life cycle and registering
230                                of applications, and only one downcall to query the Network for
231                                proximity between Nodes. </font></span></p>
232                <p class="MsoNormal">&nbsp;</p>
233        <p class="MsoNormal"><span lang="EN-GB"><font size="2">You would
234                execute an application than use the overlay likes this example (planet.test.SimTest)</font></span></p>
235                <p class="MsoNormal">&nbsp;</p>
236                <p class="MsoNormal" style="margin-left:18.0pt">
237                <span lang="EN-GB" style="font-family: Courier">
238                <font size="2">package planet.test;&nbsp;</font></span></p>
239                <p class="MsoNormal" style="margin-left:18.0pt">
240                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
241                java.util.Vector;</font></span></p>
242                <p class="MsoNormal" style="margin-left:18.0pt">
243                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
244                planet.commonapi.Network;</font></span></p>
245                <p class="MsoNormal" style="margin-left:18.0pt">
246                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
247                planet.generic.commonapi.factory.GenericFactory;</font></span></p>
248                <p class="MsoNormal" style="margin-left:18.0pt">
249                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
250                planet.simulate.EventParser;</font></span></p>
251                <p class="MsoNormal" style="margin-left:18.0pt">
252                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
253                planet.simulate.NetworkSimulator;</font></span></p>
254                <p class="MsoNormal" style="margin-left:18.0pt">
255                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
256                planet.simulate.Scheduler;</font></span></p>
257                <p class="MsoNormal" style="margin-left:18.0pt">
258                <span lang="EN-GB" style="font-family: Courier"><font size="2">import
259                planet.util.Properties;</font></span></p>
260                <p class="MsoNormal" style="margin-left:18.0pt">&nbsp;</p>
261                <p class="MsoNormal" style="margin-left:18.0pt">
262                <span lang="EN-GB" style="font-family: Courier"><font size="2">/**</font></span></p>
263                <p class="MsoNormal" style="margin-left:18.0pt">
264                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;*
265                This test use the event file &quot;test_join1000d.txt&quot; in the &quot;bin&quot; 
266                directory. Shows the time elapsed</font></span></p>
267                <p class="MsoNormal" style="margin-left:18.0pt">
268                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;* for
269                generating the network and its stabilization. Finally, prints all nodes
270                with theirs</font></span></p>
271                <p class="MsoNormal" style="margin-left:18.0pt">
272                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;*
273                information</font></span></p>
274                <p class="MsoNormal" style="margin-left:18.0pt">
275                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;*
276                @author Ruben Mondejar</font></span></p>
277                <p class="MsoNormal" style="margin-left:18.0pt">
278                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;*
279                @author Jordi Pujol</font></span></p>
280                <p class="MsoNormal" style="margin-left:18.0pt">
281                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;*/</font></span></p>
282                <p class="MsoNormal" style="margin-left:18.0pt">
283                <span lang="EN-GB" style="font-family: Courier"><font size="2">public
284                class SimTest {&nbsp;</font></span></p>
285                <p class="MsoNormal" style="margin-left:18.0pt">
286                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; /**</font></span></p>
287                <p class="MsoNormal" style="margin-left:18.0pt">
288                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
289                Initialize the planet.util.Properties with </font> </span></p>
290                <p class="MsoNormal" style="margin-left:18.0pt">
291                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
292                ../conf/factories_zero.properties, ../conf/sim.properties, ../conf/chord.properties
293                files,</font></span></p>
294                <p class="MsoNormal" style="margin-left:18.0pt">
295                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
296                with a test_join1000d.txt for event file.</font></span></p>
297                <p class="MsoNormal" style="margin-left:18.0pt">
298                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
299                Then, it initialize the GenericFactory and starts the stabilization
300                process.</font></span></p>
301                <p class="MsoNormal" style="margin-left:18.0pt">
302                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
303                @param args Nothing.</font></span></p>
304                <p class="MsoNormal" style="margin-left:18.0pt">
305                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*
306                @throws Exception</font></span></p>
307                <p class="MsoNormal" style="margin-left:18.0pt">
308                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; &nbsp;*/</font></span></p>
309                <p class="MsoNormal" style="margin-left:18.0pt">
310                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp; 
311                public static void main(String[] args) throws Exception {</font></span></p>
312                <p class="MsoNormal" style="margin-left:18.0pt">
313                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp; 
314                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //init context</font></span></p>
315                <p class="MsoNormal" style="margin-left:18.0pt">
316                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp; 
317                &nbsp;&nbsp; Properties.init(&quot;../conf/factories_zero.properties&quot;,&quot;../conf/sim_simtest.properties&quot;,&quot;../conf/chord.properties&quot;);</font></span></p>
318                <p class="MsoNormal" style="margin-left:18.0pt">
319                <span lang="EN-GB" style="font-family: Courier"><font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
320                &nbsp; GenericFactory.init();</font></span></p>
321                <p class="MsoNormal" style="margin-left:18.0pt">
322                <span lang="EN-GB" style="font-family: Courier">
323                <font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </font> </span></p>
324                <p class="MsoNormal" style="margin-left:18.0pt">
325                <span lang="EN-GB" style="font-family: Courier">
326                <font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //load events</font></span></p>
327                <p class="MsoNormal" style="margin-left:18.0pt">
328                <span lang="EN-GB" style="font-family: Courier">
329                <font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Vector events = EventParser.parseEvents(Properties.eventFile);</font></span></p>
330                <p class="MsoNormal" style="margin-left:18.0pt">
331                <span lang="EN-GB" style="font-family: Courier">
332                <font size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Scheduler timer = new Scheduler();</font></span>