Changes between Version 22 and Version 23 of TopdlLibrary
- Timestamp:
- Oct 8, 2012 3:42:10 PM (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TopdlLibrary
v22 v23 5 5 This page describes the python library for manipulating topologies that follow the [TopDl topdl] model and are generally output in the topdl language. It is broken up into a reference section describing the various python classes and procedures and an examples section. 6 6 7 = Reference =8 7 9 8 == Installing and Accessing == … … 53 52 54 53 Most of the nested classes can appear multiple times. This is to allow application designers to express as many interesting topologies as possible without having to redefine topdl. Interfaces can be members of more than one substrate because substrates are intended to be general enough to capture unusual communications media - e.g., interfaces with different line-of-sight connectivity. Similarly, we expect most computers to have one operating system, but want to allow some applications to express multi-boot or virtual machine capabilities. 55 56 === Adaptive Constructors === 54 55 === Common Features === 56 57 All topdl library classes share a couple features, described here. 58 59 ==== Adaptive Constructors ==== 57 60 58 61 The constructors of the various topdl classes will accept contained classes in several formats. They will always accept an object of the relevant class. They will also take a dict that maps constructor parameters to values for the given class. Examples make this clearer than description. … … 81 84 All topdl class constructors take the member names as parameters, and should be called using named parameters, as above. The only exceptions to this is the [TopdlLibrary#SubstrateClass Substrate object]'s {{{interfaces}}} member and the [TopdlLibrary#InterfaceClass Interface object]'s {{{subs}}} member. An Interface's {{{element}}} member can be specified, but generally is not. 82 85 83 === Topdl Class Features===86 ==== Shared Functions ==== 84 87 85 88 All topdl classes implement the following methods: … … 99 102 Return the XML encoding (from the topdl language) of this object (and nested objects) 100 103 101 === Topology Class === 104 === Individual Classes === 105 106 ==== Topology Class ==== 102 107 103 108 This class holds an enitre topology. The utility functions that read and write files operate on it, and it is generally the unit of I/O for the library. … … 126 131 {{{incorporate_elements()}}} is called by the {{{Topology}}} constructor as well and that constructor may throw the same exceptions. 127 132 128 === Computer Class===133 ==== Computer Class ==== 129 134 130 135 A Computer object is a programmable computer in a topology. A webserver is well represented by a computer, as is a desktop. … … 162 167 A {{{Computer}}} should only be an element of one {{{Topology}}}. Use {{{clone()}}} to avoid this. 163 168 164 === Substrate Class===169 ==== Substrate Class ==== 165 170 166 171 The {{{Substrate}}} object represents a communication substrate. The elements that have interfaces connected to a substrate can communicate with one another. A {{{Substrate}}} may include default parameters for the latency and capacity of the communication channel. … … 197 202 Because the enclosing {{{Topology}}} object maintains the {{{interfaces}}} member, it is dangerous to have the same {{{Substrate}}} object in more than one {{{Topology}}}. Use the {{{clone()}}} method to avoid this. 198 203 199 === Interface Class===204 ==== Interface Class ==== 200 205 201 206 This class defines the attachment of an entity, e.g., a [TopdlLibrary#ComputerClass Computer], to a [TopdlLibrary#SubstrateClass Substrate]. As with Substrates and entities, each Interface should be attached to only one entity and be unique across a [TopdlLibrary#Topology Topology]. An Interface has the following members: … … 216 221 The constructor takes all the member names '''except subs''' as parameters. Most programs will not need to use {{{element}}} as a parameter to the constructor, either. 217 222 218 === Attribute Class===223 ==== Attribute Class ==== 219 224 220 225 An attribute is a user-defined annotation of one of the other classes: a key/value pair. An attribute has the following members: … … 229 234 Should a program need to call the constructor, it takes the member names as named parameters. 230 235 231 === CPU Class===236 ==== CPU Class ==== 232 237 233 238 This represents a CPU on a computer. It has the following members: … … 240 245 The constructor takes the member names as named parameters. 241 246 242 === !OperatingSystem Class===247 ==== !OperatingSystem Class ==== 243 248 244 249 This class captures the operating system requirements of a computer. It has the following members: … … 258 263 The constructor takes the member names as parameters. Note that all the members may be None, but an empty {{{!OperatingSystem}}} object is not very useful. The flexibility is there to allow specifying an operating system version without a distribution or a distribution without a base version. 259 264 260 === Storage Class===265 ==== Storage Class ==== 261 266 262 267 The storage requirements or information for a system. This class characterizes memory or permanent storage. Its members are: … … 273 278 The constructor takes the member names as named parameters. 274 279 275 === Software Class===280 ==== Software Class ==== 276 281 277 282 This indicates what software must be installed on a system. Its members are: … … 284 289 The constructor takes the member names as named parameters. 285 290 286 === Service Class===291 ==== Service Class ==== 287 292 288 293 A service class encapsulates the ideas of a [FeddAbout#ExperimentServices DETER federation service]. Such services can be available from or used by a variety of topology elements. The Service class has the following members: … … 307 312 The constructor will take the member names as named parameters. 308 313 309 === !ServiceParam Class===314 ==== !ServiceParam Class ==== 310 315 311 316 A description of the type of parameter to a [TopdlLibrary#ServiceClass Service] will accept. It has the following members: … … 321 326 The constructor will take the member names as named parameters. 322 327 323 === Testbed Class===328 ==== Testbed Class ==== 324 329 325 330 This class represents a testbed that has allocated resources or from which an allocation is requested. While it is primarily used internally by the federation system, some other applications include a {{{Testbed}}} as a place to attach attributes that pertain to the whole topology. … … 352 357 The constructor takes the member names as named parameters. 353 358 354 === Segment Class===359 ==== Segment Class ==== 355 360 356 361 This class represents a sub-experiment of a federated experiment about which the details are unknown except for its interfaces. It is primarily used internally by teh federation system. … … 367 372 A list of [TopdlLibrary#AttributeClass Attribute objects] that are attached to the segment. The list may be empty. 368 373 369 === ID Class===374 ==== ID Class ==== 370 375 371 376 This class represents a polymorphic identifier as used by the federation system. At most one of its members is set. … … 386 391 The constructor accepts the member names as named parameters. 387 392 388 === Other Class===393 ==== Other Class ==== 389 394 390 395 This class represents a topology element that is not captured above. It is a set of interfaces and a place to hang attributes, for use encoding kinds of elements unknown when topdl was specified. … … 475 480 An obvious missing element is a procedure to parse ns2 into topdl. Unfortunately, ns2 programs are full, turing-complete otcl programs, and parsing them would require copying the tcl interpreter into python (or any other implementation language - other than otcl). Rather than do that, we encourage programmers who need that translation to use the [http://fedd.deterlab.net/wiki/FeddCommands#fedd_ns2topdl.py fedd_ns2topdl.py] program. That program contacts a running fedd (like the one running on {{{users.isi.deterlab.net}}}) to call an otcl system to do the parsing. 476 481 477 = Examples=482 == Examples == 478 483 479 484 This section contains some illustrative examples. 480 485 481 == Making a Topology==486 === Making a Topology === 482 487 483 488 This example constructs the topdl describing a simple start topology with 11 nodes, one center and 10 satellites. … … 547 552 }}} 548 553 549 == A More Complex Topology==554 === A More Complex Topology === 550 555 551 556 The next few examples will build on one another to show a more complex change to a topology. We will take a topology, find the degrees of nodes, assign operating systems to them based on that degree, and output DETER-ready ns2. … … 625 630 The code takes a few more shortcuts in construction, e.g., most elements and substrates are appended directly to the lists rather than being assigned to variables, but is not fundamentally different from the start topology generator. 626 631 627 == Annotating A Topology==632 === Annotating A Topology === 628 633 629 634 The first step in our transformation is to take a topology and add attributes that will be used by other applications. In our example, the other applications will be further refinements in the same program. 630 635 631 Here is a function that walks a topology, determines the degree of each computer, and adds an [TopdlLibrary#AttributeClass attribute] to each computer with that degree in it. It demostrates editing a topology using the [TopdlLibrary# TopdlClassFeatures set_attribute] function common to topdl classes.636 Here is a function that walks a topology, determines the degree of each computer, and adds an [TopdlLibrary#AttributeClass attribute] to each computer with that degree in it. It demostrates editing a topology using the [TopdlLibrary#SharedFunctions set_attribute] function common to topdl classes. 632 637 633 638 {{{ … … 647 652 }}} 648 653 649 == Adding Other Classes==654 === Adding Other Classes === 650 655 651 656 This function takes a topology that has been through the {{{annotate_degree}}} function above and adds an [TopdlLibrary#OperatingSystemClass OperatingSystem nested object] to each Computer in the topology, based on the {{{node_degree}}} attribute. This demonstrates adding a nested object directly, rather rthan through [TopdlLibrary#TopdlClassFeatures set_attribute]. … … 681 686 }}} 682 687 683 == Changing a Topology (adding connections)==688 === Changing a Topology (adding connections) === 684 689 685 690 This example shows how to change a topology by adding links. This function adds a link between adjacent clusters of leaf nodes. The code walks the topology, finding routers by their [TopdlLibrary#OperatingSystem OperatingSystem] assigned above. For each router it finds, the code collects the leaves attached to that router (again, discriminating based on their OS) and collects them into a list. There will be a list of leaves for each router, all in a list. Then the code connects one computer from each per-router list to a computer in the adjacent router's list. … … 753 758 It is also important to note the {{{Topology.incorporate_elements}}} call near the end. That call completes the connections between interface objects and substrate objects (filling in the {{{Interface.subs}}} members and {{{Substrate.intrefaces}}} member) and between Interfaces and elements (by filling in the {{{Interface.element}}} member). Without that call further use of the topology is difficult. That call will also throw exceptions if the changes have introduced inconsistencies - multiple substrates with the same name, etc. 754 759 755 == Output to NS2==760 === Output to NS2 === 756 761 757 762 Finally, we want to output out example topology in ns2 format so that we can directly swap it in to DETER. Of course, fedd and the containers system will take (and prefer) topdl, but as an example, we show outputting ns2. … … 799 804 }}} 800 805 801 == Putting It All Together==806 === Putting It All Together === 802 807 803 808 The complete example is [attachment:example.py attached to this page.] It consists of :
