/usr/share/doc/simgrid/html/bindings.html is in simgrid-doc 3.10-7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>SimGrid: Bindings</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">SimGrid
 <span id="projectnumber">3.10</span>
</div>
<div id="projectbrief">Versatile Simulation of Distributed Systems</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="http://simgrid.gforge.inria.fr/"><span>Home page</span></a></li>
<li><a href="http://simgrid.gforge.inria.fr/documentation.html"><span>Online documentation</span></a></li>
<li><a href="https://gforge.inria.fr/projects/simgrid"><span>Dev's Corner</span></a></li>
<li> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.2 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('bindings.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Bindings </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="MSG_Ruby"></a>
Ruby Binding</h1>
<p>Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.html">Simgrid-Ruby documentation</a>.</p>
<h1><a class="anchor" id="MSG_Java"></a>
Java Binding</h1>
<p>Simgrid-java is a java API that let you use <a href="http://simgrid.gforge.inria.fr/">Simgrid</a> MSG API in your favorite language (java). Without it, you would be forced to use C or one of the other bindings provided.</p>
<p>MSG was the first distributed programming environment provided within SimGrid. While almost realistic, it remains quite simple. This describes the Java bindings to this interface.</p>
<p>The javadoc is accessible <a href="javadoc/index.html">here</a></p>
<h2><a class="anchor" id="bindings_binding_Java_jMSG_who"></a>
Who should use this (and who shouldn't)</h2>
<p>You should use MSG if you want to study some heuristics for a given problem you don't really want to implement. SimGrid-java let you use MSG while coding in Java. So if your need is MSG + Java, you're in the right section!</p>
<h2><a class="anchor" id="SimGrid-java"></a>
Usage overview</h2>
<p>To make a long story short, it's a JNI binding, so it implies that:</p>
<ul>
<li>Most of the MSG and SimGrid documentation about behavioral aspects applies directly to what you are programming.</li>
<li>MSG data structures are mapped to Java objects. So it means that from the syntax point of view, you have to know how those objects are. Fortunately, we have generated the Javadoc for those objects. So take a look at it</li>
</ul>
<p>Finally, it implies also that your program can crash for 3 main reasons:</p>
<ul>
<li>Your Java part is not good: you'll have a good old java exception thrown, and hence you should be able to correct it by yourself.</li>
<li>Our java part is not good: you'll also have a java exception thrown, but we have real doubts this can happen, since the java part is only a JNI binding. The other option is that it crashed because you used incorrectly the MSG API, so this means also you should have an MSGException. It means you should read carefully MSG samples and/or documentation.</li>
<li>Something has crashed in the C part. Okay, here comes the tricky thing.</li>
</ul>
<p>C crashes mainly for 2 reasons:</p>
<ul>
<li>When something goes wrong in your simulation, sometimes the C part stops because you used SimGrid incorrectly, and JNI bindings are not fond of that. It means that you'll have something that looks ugly, but you should be able to identify what's going wrong in your code by carefully reading the whole error message</li>
<li>It may happen that the problem comes directly from SimGrid: in this case, the error should be uglier. In that case, you may submit a bug directly to SimGrid.</li>
</ul>
<h2><a class="anchor" id="bindings_binding_java_install"></a>
How to install Simgrid-java</h2>
<p>To use java with Simgrid you have to install some dependencies:</p>
<ul>
<li>Java JDK packages, such as <code>openjdk7</code> or <code>sun-java6-jdk</code> (with <code>libgcj10-dev</code> or another version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see <a class="el" href="bindings.html#bindings_binding_java_coroutines">How to use the coroutines context factory</a>).</li>
</ul>
<p>Then build Simgrid with the Java bindings enabled: </p>
<div class="fragment"><div class="line">cmake -Denable_java=ON .</div>
</div><!-- fragment --><p>If cmake complains that <b>jni could not be found</b>, you need to tell it where JNI header files are located. the following command should tell you:</p>
<div class="fragment"><div class="line">$ locate jni.h</div>
<div class="line">/usr/lib/jvm/java-6-openjdk-amd64/include/jni.h</div>
<div class="line">/usr/lib/jvm/java-7-openjdk-amd64/include/jni.h</div>
</div><!-- fragment --><p>If you have several version of jni installed (as in the example above), you need to check the version of java that is used by default on your machine (using javac -version), and pick the right one. Then set the <code>JAVA_INCLUDE_PATH</code> environment variable to the right path (note that we remove the filename <code>jni.h</code> from that path), and relaunch cmake.</p>
<div class="fragment"><div class="line">$ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/</div>
<div class="line">$ cmake .</div>
</div><!-- fragment --><h3><a class="anchor" id="bindings_binding_java_use"></a>
How to use Simgrid-java</h3>
<p>To execute the examples you need to add the path where you installed the generated <code>libsimgrid-java</code> and <code>libsimgrid</code> libraries into the <code>LD_LIBRARY_PATH</code>.</p>
<p>Be careful on Mac, this variable is called <code>DYLD_LIBRARY_PATH</code> and not <code>LD_LIBRARY_PATH</code>.</p>
<div class="fragment"><div class="line">$ export SIMGRID_ROOT=<span class="stringliteral">"$HOME/Install/simgrid/"</span> # change it to the path where you installed the SimGrid library</div>
<div class="line">$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib</div>
<div class="line">$ cd examples</div>
<div class="line">$ java -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml</div>
</div><!-- fragment --><p>If you want to make these settings permanent even after a reboot, you need to add the export lines into your <code>~/.bashrc</code> file, or equivalent.</p>
<h3><a class="anchor" id="bindings_binding_java_coroutines"></a>
How to use the coroutines context factory</h3>
<p>There is two main motivations to use the coroutine variant of SimGrid Java bindings: it's about 5 times faster than the default thread-based context factory, and the amount of runnable processes is then only limited by the amount of RAM that you have. The drawbacks are that it requires a specific and rather experimental JVM to run, and that this context factory itself remains a bit experimental so far.</p>
<h3><a class="anchor" id="bindings_java_coro_install"></a>
Getting a mlvm JVM</h3>
<p>You need to get a patched JVM from <a href="http://ssw.jku.at/General/Staff/LS/coro/">here</a> (many thanks to Lukas Stadler for this work!).</p>
<p>You can either get a prebuilt binary, or recompile your own JVM. Make sure to get a coro-simple version, as we don't need to serialize nor migrate stacks in SimGrid. You should be able to follow the <code>README.txt</code> that you'll get in the repository, but here is how we did it, just in case. The instructions are given for a debian or Ubuntu box, but I think you should manage to convert it to your system quite easily. Finally, if you're really stuck, you can get the version compiled by Jonathan Rouzaud-Cornabas from his web page. This version is known to work with SimGrid for sure! <a href="http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz">http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz</a></p>
<ol type="1">
<li>Install mercurial and some dependencies <div class="fragment"><div class="line">sudo apt-<span class="keyword">get</span> install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev</div>
<div class="line"><span class="preprocessor"># Grab the forest extension: we need to source-install it</span></div>
<div class="line"><span class="preprocessor">hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim</span></div>
</div><!-- fragment --></li>
<li><p class="startli">Configure the mercurial extensions: Edit ~/.hgrc and paste the following lines. Don't forget to change the /path/to/forest.py to point to where you just downloaded the source.</p>
<p class="startli">Forest extension is needed to download the openjdk source code and patches while the mq line is needed to apply the patches. The username is needed at the step "preparing the sources", not sure why. </p>
<pre class="fragment">[ui]
username = YouUserameWithoutSpaces
[extensions]
forest=/path/to/forest.py
mq=
</pre></li>
<li>Prepare the source code <div class="fragment"><div class="line"><span class="preprocessor"># create a working directory, and enter it</span></div>
<div class="line"><span class="preprocessor"></span>mkdir davinci; cd davinci</div>
<div class="line"></div>
<div class="line"><span class="preprocessor"># Grab the sources</span></div>
<div class="line"><span class="preprocessor"></span>hg fclone http:<span class="comment">//hg.openjdk.java.net/hsx/hotspot-comp sources</span></div>
<div class="line"><span class="preprocessor"># Grab the patches</span></div>
<div class="line"><span class="preprocessor"></span>hg fclone http:<span class="comment">//hg.openjdk.java.net/mlvm/mlvm patches</span></div>
<div class="line"></div>
<div class="line"><span class="preprocessor"># Link the patch directories into the sources</span></div>
<div class="line"><span class="preprocessor"></span>bash patches/make/link-patch-dirs.sh sources patches</div>
<div class="line"><span class="preprocessor"># Test wether the previous command worked with</span></div>
<div class="line"><span class="preprocessor"></span>ls -i patches/hotspot/series sources/hotspot/.hg/patches/series</div>
<div class="line"><span class="preprocessor"># It should display something like the following.</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor"># (note that both file share the same inode number)</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor"># 9707849 patches/hotspot/series </span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor"># 9707849 sources/hotspot/.hg/patches/series</span></div>
<div class="line"><span class="preprocessor"></span></div>
<div class="line"><span class="preprocessor"># Specify what to compile. </span></div>
<div class="line"><span class="preprocessor"></span>export davinci=$(pwd) guards=<span class="stringliteral">"buildable testable coro-simple"</span></div>
<div class="line"># Apply the patches</div>
<div class="line">sh patches/make/each-patch-repo.sh hg qselect --reapply $guards <span class="stringliteral">'$(sh $davinci/patches/make/current-release.sh)'</span></div>
<div class="line"># Check that it understood that you want the patch applied:</div>
<div class="line">grep GLOBAL_GUARDS patches/make<span class="comment">/* -r</span></div>
<div class="line"><span class="comment"># this should display something like the following (maybe amonst other unrelated lines)</span></div>
<div class="line"><span class="comment"># GLOBAL_GUARDS=buildable testable coro-simple</span></div>
<div class="line"><span class="comment"># If this does not work, edit patches/make/Makefile,</span></div>
<div class="line"><span class="comment"># manually coro-simple to GLOBAL_GUARDS and then </span></div>
<div class="line"><span class="comment"># rerun the patches/make/each-patch-repo.sh script as earlier</span></div>
<div class="line"><span class="comment"></span></div>
<div class="line"><span class="comment"># Finish the setup</span></div>
<div class="line"><span class="comment">(cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")</span></div>
<div class="line"><span class="comment"># If this last command failed, check your mercurial config within ~/.hgrc (see above)</span></div>
</div><!-- fragment --></li>
<li>Compile it all <div class="fragment"><div class="line">unset LD_LIBRARY_PATH</div>
<div class="line">export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/</div>
<div class="line">cd sources</div>
<div class="line"><span class="preprocessor"># Check that everything is fine</span></div>
<div class="line"><span class="preprocessor"></span>make sanity</div>
<div class="line"><span class="preprocessor"># Go for it (it takes about half an hour on my machine)</span></div>
<div class="line"><span class="preprocessor"></span>make all</div>
<div class="line"></div>
<div class="line"><span class="preprocessor"># Check that the coroutine library got compiled in</span></div>
<div class="line"><span class="preprocessor"></span>ls sources/build/linux-amd64/classes/java/dyn/</div>
<div class="line"><span class="preprocessor"># This should display a bunch of class files. If not, something went wrong, you need to investigate further</span></div>
</div><!-- fragment --></li>
</ol>
<h3><a class="anchor" id="bindings_java_coro_use"></a>
Using coroutine contexts</h3>
<p>SimGrid Java will automatically switch to the coroutine context factory if your JVM support it, so you will just need to execute your simulation with the correct JVM. The selected context factory gets displayed automatically. </p>
<div class="fragment"><div class="line">export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so</div>
<div class="line">cd examples</div>
<div class="line">$PATH_TO_COROUTINE_JVM/java -classpath .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml</div>
</div><!-- fragment --><p>Note that you may have to adjust the "coro.stacksPerThread" configuration option to run large simulations. The default is 100 and you want to increase it to run more processes. </p>
<div class="fragment"><div class="line">$ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml</div>
</div><!-- fragment --><p>If you reach the point where the creation of new simulated processes fail with the message "Can't create coroutine object", you may need to increase the relevant system limit with the following command. </p>
<div class="fragment"><div class="line">sysctl -w vm.max_map_count = 131072</div>
</div><!-- fragment --><p>The full story is that each coroutine requires two memory maps, and that Linux puts a limit on the total amount of memory maps that each process can manage (by default, this limit is often at 65535). Since the JVM needs a few dozen of such maps on its own (three maps per dynamic library – check <code>/proc/the_pid/maps</code> if you don't believe it), this is enough to create over 30,000 simulated processes. But to go futher, that limit must be modified.</p>
<p>If you want to make this change permanent on your machine, edit your <code>/etc/sysctl.conf</code> file. Otherwise, you have to redo it by calling sysctl after each reboot.</p>
<h1><a class="anchor" id="bindings_binding_lua"></a>
Lua Binding</h1>
<p>Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library. Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works, which avoid dealing with C errors, and sometime an important gain of time. Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid for MSG Module, and we are currenlty working on bindings for other modules.</p>
<h2><a class="anchor" id="bindings_binding_lua_about"></a>
What is lua ?</h2>
<p>Lua is a lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>). </p>
<h3><a class="anchor" id="bindings_binding_lua_why"></a>
Why lua ?</h3>
<p>Lua is a fast, portable and powerful script language, quite simple to use for developpers. it combines procedural features with powerful data description facilities, by using a simple, yet powerful, mechanism of tables. Lua has a relatively simple C API compared to other scripting languages, and accordingly it provides a robust, easy to use it. </p>
<h3><a class="anchor" id="bindings_binding_lua_simgrid"></a>
How to use lua in Simgrid ?</h3>
<p>Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :</p>
<ul>
<li>Coding functions coresponding to each process</li>
<li>loading the platforme/deployment XML file that describe the environment of simulation</li>
<li>and … Running the Simulation.</li>
</ul>
<h2><a class="anchor" id="bindings_binding_lua_example_master_slave"></a>
Master/Slave Example</h2>
<ul>
<li>Master Code <div class="fragment"><div class="line"><span class="keyword">function</span> Master(...) </div>
<div class="line"></div>
<div class="line"> if <span class="preprocessor">#arg ~= 4 then</span></div>
<div class="line"><span class="preprocessor"></span> error(<span class="stringliteral">"Wrong number of arguments (got "</span> .. #arg ..</div>
<div class="line"> <span class="stringliteral">", expected 4: nb_tasks comp_size comm_size slave_count)"</span>)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> simgrid.info("Hello from lua, I'm the master")</div>
<div class="line"></div>
<div class="line"> local nb_task, comp_size, comm_size, slave_count = unpack(arg)</div>
<div class="line"></div>
<div class="line"> -- Dispatch the tasks</div>
<div class="line"></div>
<div class="line"> for i = 1, nb_task do</div>
<div class="line"> local task = simgrid.task.new("Task " .. i, comp_size, comm_size)</div>
<div class="line"> local task_name = task:get_name()</div>
<div class="line"> local alias = "slave " .. (i % slave_count)</div>
<div class="line"> simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")</div>
<div class="line"> task:send(alias) -- C user data set to NULL</div>
<div class="line"> simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> -- Sending Finalize Message To Others</div>
<div class="line"></div>
<div class="line"> simgrid.info("All tasks have been dispatched. Let's tell everybody the computation is over.")</div>
<div class="line"> for i = 0, slave_count - 1 do</div>
<div class="line"> local alias = "slave " .. i</div>
<div class="line"> simgrid.info("Sending finalize to '" .. alias .. "'")</div>
<div class="line"> local finalize = simgrid.task.new("finalize", comp_size, comm_size)</div>
<div class="line"> finalize:send(alias)</div>
<div class="line"> end</div>
<div class="line"> simgrid.info("Everything's done.")</div>
<div class="line">end -- end_of_master</div>
</div><!-- fragment --> we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task, then simgrid.Task.send(task,alias) to send it. we use also simgrid.Task.name(task), to get the task's name.</li>
</ul>
<ul>
<li>Slave Code <div class="fragment"><div class="line"><span class="keyword">function</span> Slave(...)</div>
<div class="line"></div>
<div class="line"> if <span class="preprocessor">#arg ~= 1 then</span></div>
<div class="line"><span class="preprocessor"></span> error(<span class="stringliteral">"Wrong number of arguments (got "</span> .. #arg .. <span class="stringliteral">", expected 1: slave_id)"</span>)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> local my_mailbox = "slave " .. arg[1]</div>
<div class="line"> simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)</div>
<div class="line"></div>
<div class="line"> while true do</div>
<div class="line"></div>
<div class="line"> local task = simgrid.task.recv(my_mailbox)</div>
<div class="line"> local task_name = task:get_name()</div>
<div class="line"> if (task_name == "finalize") then</div>
<div class="line"> simgrid.info("Got finalize message")</div>
<div class="line"> break</div>
<div class="line"> end</div>
<div class="line"> simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")</div>
<div class="line"> task:execute()</div>
<div class="line"> simgrid.info("Task '" .. task_name .. "' is done")</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> simgrid.info("I'm done. See you!")</div>
<div class="line">end -- end_of_slave</div>
</div><!-- fragment --> Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias, this function return directly the task recevied.</li>
</ul>
<ul>
<li>Set Environmenet and run application <div class="fragment"><div class="line">dofile <span class="stringliteral">'master.lua'</span></div>
<div class="line">dofile <span class="stringliteral">'slave.lua'</span></div>
<div class="line">-- Simulation Code ----------------------------------------------------------</div>
<div class="line"></div>
<div class="line">require <span class="stringliteral">"simgrid"</span></div>
<div class="line"></div>
<div class="line">simgrid.platform(arg[1])</div>
<div class="line">simgrid.application(arg[2])</div>
<div class="line">simgrid.run()</div>
<div class="line">simgrid.info(<span class="stringliteral">"Simulation's over. See you."</span>)</div>
<div class="line">-- end-of-master-slave</div>
</div><!-- fragment --></li>
</ul>
<h2><a class="anchor" id="bindings_binding_lua_example_data"></a>
Exchanging Data</h2>
<p>You can also exchange data between Process using lua. for that, you have to deal with lua task as a table, since lua is based itself on a mechanism of tables, so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.</p>
<ul>
<li>Sender process <pre class="fragment"> task = simgrid.Task.new("data_task",task_comp,task_comm);
task['matrix'] = my_matrix;
task['table'] = my_table;
task['message'] = "Hello from (Lua || Simgrid ) !! "
…
simgrid.Task.send(task,alias)
</pre> After creating task, we associate to it various kind of data with a specific key (string in this case) to distinguish between data variables. The receiver will use this key to access easily to datas.</li>
</ul>
<ul>
<li>Receiver processe <pre class="fragment"> task = simgrid.Task.recv(alias);
sender_matrix = task['matrix'];
sender_table = task['table'];
sender_message = task['message']
...
</pre> Note that in lua, both sender and receiver share the same lua task. So that the receiver could joint data directly on the received task without sending it back. You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.</li>
</ul>
<h2><a class="anchor" id="bindings_binding_lua_example_bypass"></a>
Bypass XML</h2>
<p>maybe you wonder if there is a way to bypass the XML files, and describe your platform directly from the code, with lua bindings it's Possible !! how ? We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )</p>
<ul>
<li>set Routing mode <pre class="fragment"> simgrid.AS.new{id="AS0",mode="Full"};
</pre></li>
</ul>
<ul>
<li>set Hosts <pre class="fragment"> simgrid.Host.new{id="Tremblay",power=98095000};
simgrid.Host.new{id="Jupiter",power=76296000};
simgrid.Host.new{id="Fafard",power=76296000};
simgrid.Host.new{id="Ginette",power=48492000};
simgrid.Host.new{id="Bourassa",power=48492000};
</pre> we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.</li>
</ul>
<ul>
<li>set Links <pre class="fragment"> for i=0,11 do
simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;)
end
</pre> we used simgrid.Link.new{id=link_id,bandwidth=bw,latency=lat} with a simple for loop to create all links we need (much easier than XML hein ?)</li>
</ul>
<ul>
<li>set Routes <pre class="fragment">-- simgrid.Route.new(src_id,des_id,links_nb,links_list)
simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
...
</pre> for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.</li>
</ul>
<ul>
<li>Save platform <pre class="fragment"> simgrid.register_platform();
</pre> Don't forget to register your platform, that SURF callbacks starts their work ;)</li>
</ul>
<ul>
<li>set application <pre class="fragment"> simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
</pre> you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list) you can associate functions for each host with arguments if needed .</li>
</ul>
<ul>
<li><pre class="fragment"> simgrid.register_application();
</pre> Yes, Here too you have to register your application before running the simulation.</li>
</ul>
<p>the full example is distributed in the file examples/lua/master_slave_bypass.lua</p>
<h2><a class="anchor" id="MSG_ex_master_slave_lua"></a>
Master/slave Lua application</h2>
<p>Simulation of a master-slave application using lua bindings</p>
<ul>
<li><a class="el" href="bindings.html#MSG_ext_ms_master_lua">Master code</a></li>
<li><a class="el" href="bindings.html#MSG_ext_ms_slave_lua">Slave code</a></li>
<li><a class="el" href="bindings.html#MSG_ext_ms_core_lua">Simulation core</a></li>
<li><a class="el" href="use.html#MSG_ext_ms_helping">Helping files</a></li>
<li><a class="el" href="use.html#MSG_ext_ms_application">Example of application file</a></li>
<li><a class="el" href="use.html#MSG_ext_ms_platform">Example of platform file</a></li>
</ul>
<h3><a class="anchor" id="MSG_ext_ms_master_lua"></a>
Master code</h3>
<p>as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master.</p>
<p>Lua style arguments (...) in for the master are interpreted as:</p>
<ul>
<li>the number of tasks to distribute</li>
<li>the computation size of each task</li>
<li>the size of the files associated to each task</li>
<li>a list of host that will accept those tasks.</li>
</ul>
<p>Tasks are dumbly sent in a round-robin style. <div class="fragment"><div class="line"> -- Dispatch the tasks</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">for</span> i = 1, nb_task <span class="keywordflow">do</span></div>
<div class="line"> local task = simgrid.task.new(<span class="stringliteral">"Task "</span> .. i, comp_size, comm_size)</div>
<div class="line"> local task_name = task:get_name()</div>
<div class="line"> local alias = "slave " .. (i % slave_count)</div>
<div class="line"> simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")</div>
<div class="line"> task:send(alias) -- C user data set to NULL</div>
<div class="line"> simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")</div>
<div class="line"> end</div>
</div><!-- fragment --></p>
<h3><a class="anchor" id="MSG_ext_ms_slave_lua"></a>
Slave code</h3>
<p>This function has to be assigned to a <a class="el" href="group__m__process__management.html#ga49407197cb1ba4a2b1943285786eacec" title="Process datatype.A process may be defined as a code, with some private data, executing in a location...">msg_process_t</a> that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them. <div class="fragment"><div class="line"><span class="keyword">function</span> Slave(...)</div>
<div class="line"></div>
<div class="line"> if <span class="preprocessor">#arg ~= 1 then</span></div>
<div class="line"><span class="preprocessor"></span> error(<span class="stringliteral">"Wrong number of arguments (got "</span> .. #arg .. <span class="stringliteral">", expected 1: slave_id)"</span>)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> local my_mailbox = "slave " .. arg[1]</div>
<div class="line"> simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)</div>
<div class="line"></div>
<div class="line"> while true do</div>
<div class="line"></div>
<div class="line"> local task = simgrid.task.recv(my_mailbox)</div>
<div class="line"> local task_name = task:get_name()</div>
<div class="line"> if (task_name == "finalize") then</div>
<div class="line"> simgrid.info("Got finalize message")</div>
<div class="line"> break</div>
<div class="line"> end</div>
<div class="line"> simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")</div>
<div class="line"> task:execute()</div>
<div class="line"> simgrid.info("Task '" .. task_name .. "' is done")</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> simgrid.info("I'm done. See you!")</div>
<div class="line">end -- end_of_slave</div>
</div><!-- fragment --> </p>
<h3><a class="anchor" id="MSG_ext_ms_core_lua"></a>
Simulation core</h3>
<p>in this section the core of the simulation which start by including the simgrid lib for bindings : <em>require "simgrid" </em></p>
<ol type="1">
<li>Simulation settings : <em>simgrid.platform</em> creates a realistic environment</li>
<li>Application deployment : create the processes on the right locations with <em>simgrid.application</em></li>
<li>The simulation is run with <em>simgrid.run</em></li>
</ol>
<p>Its arguments are:</p>
<ul>
<li><em>platform_file</em>: the name of a file containing an valid surfxml platform description.( first command line argument)</li>
<li><em>application_file</em>: the name of a file containing a valid surfxml application description ( second commande line argument ) <div class="fragment"><div class="line">simgrid.platform(arg[1])</div>
<div class="line">simgrid.application(arg[2])</div>
<div class="line">simgrid.run()</div>
</div><!-- fragment --></li>
</ul>
<h2><a class="anchor" id="MSG_ex_master_slave_lua_bypass"></a>
Master/slave Bypass Lua application</h2>
<p>Simulation of a master-slave application using lua bindings, Bypassing the XML parser</p>
<ul>
<li><a class="el" href="bindings.html#MSG_ext_ms_bp_master_lua">Master code</a></li>
<li><a class="el" href="bindings.html#MSG_ext_ms_bp_slave_lua">Slave code</a></li>
<li><a class="el" href="bindings.html#MSG_ext_ms_bp_core_lua">Simulation core</a></li>
</ul>
<h3><a class="anchor" id="MSG_ext_ms_bp_master_lua"></a>
Master code</h3>
<p>as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master.</p>
<p>Lua style arguments (...) in for the master are interpreted as:</p>
<ul>
<li>the number of tasks to distribute</li>
<li>the computation size of each task</li>
<li>the size of the files associated to each task</li>
<li>a list of host that will accept those tasks.</li>
</ul>
<p>Tasks are dumbly sent in a round-robin style.</p>
<div class="fragment"><div class="line">--Master Function</div>
<div class="line"><span class="keyword">function</span> Master(...) </div>
<div class="line"></div>
<div class="line"> if <span class="preprocessor">#arg ~= 4 then</span></div>
<div class="line"><span class="preprocessor"></span> error(<span class="stringliteral">"Wrong number of arguments (got "</span> .. #arg ..</div>
<div class="line"> <span class="stringliteral">", expected 4: nb_tasks comp_size comm_size slave_count)"</span>)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> simgrid.info("Hello from lua, I'm the master")</div>
<div class="line"> for i,v in ipairs(arg) do</div>
<div class="line"> simgrid.info("Got " .. v)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> local nb_task, comp_size, comm_size, slave_count = unpack(arg)</div>
<div class="line"></div>
<div class="line"> simgrid.info("Argc=" .. (<span class="preprocessor">#arg) .. " (should be 4)")</span></div>
<div class="line"><span class="preprocessor"></span></div>
<div class="line"> -- Dispatch the tasks</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">for</span> i = 1, nb_task <span class="keywordflow">do</span></div>
<div class="line"> task = simgrid.task.new(<span class="stringliteral">"Task "</span> .. i, comp_size, comm_size);</div>
<div class="line"> local task_name = simgrid.task.get_name(task)</div>
<div class="line"> alias = <span class="stringliteral">"slave "</span> .. (i%slave_count);</div>
<div class="line"> simgrid.info(<span class="stringliteral">"Master sending '"</span> .. task_name .. <span class="stringliteral">"' To '"</span> .. alias .. <span class="stringliteral">"'"</span>);</div>
<div class="line"> simgrid.task.send(task, alias); -- C user data <span class="keyword">set</span> to NULL</div>
<div class="line"> simgrid.info(<span class="stringliteral">"Master done sending '"</span> .. task_name .. <span class="stringliteral">"' To '"</span> .. alias .. <span class="stringliteral">"'"</span>);</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> -- Sending Finalize Message To Others</div>
<div class="line"></div>
<div class="line"> simgrid.info(<span class="stringliteral">"Master: All tasks have been dispatched. Let's tell everybody the computation is over."</span>);</div>
<div class="line"> <span class="keywordflow">for</span> i = 0, slave_count-1 <span class="keywordflow">do</span></div>
<div class="line"> alias = <span class="stringliteral">"slave "</span> .. i;</div>
<div class="line"> simgrid.info(<span class="stringliteral">"Master: sending finalize to "</span> .. alias);</div>
<div class="line"> finalize = simgrid.task.new(<span class="stringliteral">"finalize"</span>, comp_size, comm_size);</div>
<div class="line"> simgrid.task.send(finalize, alias)</div>
<div class="line"> end</div>
<div class="line"> simgrid.info(<span class="stringliteral">"Master: Everything's done."</span>);</div>
<div class="line">end</div>
<div class="line">--end_of_master</div>
</div><!-- fragment --></p>
<h3><a class="anchor" id="MSG_ext_ms_bp_slave_lua"></a>
Slave code</h3>
<p>This function has to be assigned to a <a class="el" href="group__m__process__management.html#ga49407197cb1ba4a2b1943285786eacec" title="Process datatype.A process may be defined as a code, with some private data, executing in a location...">msg_process_t</a> that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them.</p>
<div class="fragment"><div class="line"></div>
<div class="line"></div>
<div class="line">-- Slave Function ---------------------------------------------------------</div>
<div class="line"><span class="keyword">function</span> Slave(...)</div>
<div class="line"></div>
<div class="line"> if <span class="preprocessor">#arg ~= 1 then</span></div>
<div class="line"><span class="preprocessor"></span> error(<span class="stringliteral">"Wrong number of arguments (got "</span> .. #arg .. <span class="stringliteral">", expected 1: slave_id)"</span>)</div>
<div class="line"> end</div>
<div class="line"></div>
<div class="line"> local my_mailbox = "slave " .. arg[1]</div>
<div class="line"> simgrid.info("Hello from lua, I'm a poor slave with mbox: " .. my_mailbox)</div>
<div class="line"></div>
<div class="line"> while true do</div>
<div class="line"></div>
<div class="line"> local task = simgrid.task.recv(my_mailbox);</div>
<div class="line"> --print(task)</div>
<div class="line"> local task_name = task:get_name()</div>
<div class="line"> if (task:get_name() == "finalize") then</div>
<div class="line"> simgrid.info("Slave '" .. my_mailbox .. "' got finalize msg");</div>
<div class="line"> break</div>
<div class="line"> end</div>
<div class="line"> --local tk_name = simgrid.task.get_name(tk) </div>
<div class="line"> simgrid.info("Slave '" .. my_mailbox .. "' processing " .. task:get_name())</div>
<div class="line"> simgrid.task.execute(task)</div>
<div class="line"> simgrid.info("Slave '" .. my_mailbox .. "': task " .. task:get_name() .. " done")</div>
<div class="line"> end -- while</div>
<div class="line"></div>
<div class="line"> simgrid.info("Slave '" .. my_mailbox .. "': I'm Done . See You !!");</div>
<div class="line"></div>
<div class="line">end </div>
<div class="line">-- end_of_slave</div>
</div><!-- fragment --></p>
<h3><a class="anchor" id="MSG_ext_ms_bp_core_lua"></a>
Simulation core</h3>
<p>in this section the core of the simulation which start by including the simgrid lib for bindings, then create the resources we need to set up our environment bypassing the XML parser. : <em>require "simgrid" </em></p>
<ol type="1">
<li>Hosts : <em>simgrid.Host.new</em> instanciate a new host with an id, and power.</li>
<li>Links : <em>simgrid.Link.new</em> instanictae a new link that will require an id, bandwith and latency values.</li>
<li>Route : <em>simgrid.Route.new</em> define a route between two hosts specifying the links to use.</li>
<li>Simulation settings : <em>simgrid.register_platform();</em> register own platform without using the XML SURF parser.</li>
</ol>
<p>we can also bypass the XML deployment file, and associate functions for each of defined hosts.</p>
<ul>
<li><em>simgrid.Host.setFunction</em>: associate a function to a host, specifying arguments if needed.</li>
<li><em>simgrid.register_application()</em>: saving the deployment settings before running the simualtion.</li>
</ul>
<div class="fragment"><div class="line">require <span class="stringliteral">"simgrid"</span></div>
<div class="line">dofile <span class="stringliteral">'platform.lua'</span></div>
<div class="line">dofile <span class="stringliteral">'deploy.lua'</span></div>
<div class="line">--Rutform.lua<span class="stringliteral">'</span></div>
<div class="line"><span class="stringliteral">dofile '</span>master.lua<span class="stringliteral">'</span></div>
<div class="line"><span class="stringliteral">dofile '</span>slave.lua<span class="stringliteral">'</span></div>
<div class="line"><span class="stringliteral"> simgrid.run()</span></div>
<div class="line"><span class="stringliteral"> simgrid.info("Simulation'</span>s over.See you.<span class="stringliteral">")</span></div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Sun Nov 17 2013 21:34:47 for SimGrid by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.2 </li>
</ul>
</div>
</body>
</html>
|