Changes between Version 22 and Version 23 of TopdlLibrary


Ignore:
Timestamp:
Oct 8, 2012 3:42:10 PM (11 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TopdlLibrary

    v22 v23  
    55This 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.
    66
    7 = Reference =
    87
    98== Installing and Accessing ==
     
    5352
    5453Most 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
     57All topdl library classes share a couple features, described here.
     58
     59==== Adaptive Constructors ====
    5760
    5861The 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.
     
    8184All 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.
    8285
    83 === Topdl Class Features ===
     86==== Shared Functions ====
    8487
    8588All topdl classes implement the following methods:
     
    99102   Return the XML encoding (from the topdl language) of this object (and nested objects)
    100103
    101 === Topology Class ===
     104=== Individual Classes ===
     105
     106==== Topology Class ====
    102107
    103108This 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.
     
    126131{{{incorporate_elements()}}} is called by the {{{Topology}}} constructor as well and that constructor may throw the same exceptions.
    127132
    128 === Computer Class ===
     133==== Computer Class ====
    129134
    130135A Computer object is a programmable computer in a topology.  A webserver is well represented by a computer, as is a desktop. 
     
    162167A {{{Computer}}} should only be an element of one {{{Topology}}}.  Use {{{clone()}}} to avoid this.
    163168
    164 === Substrate Class ===
     169==== Substrate Class ====
    165170
    166171The {{{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.
     
    197202Because 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.
    198203
    199 === Interface Class ===
     204==== Interface Class ====
    200205
    201206This 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:
     
    216221The 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.
    217222
    218 === Attribute Class ===
     223==== Attribute Class ====
    219224
    220225An attribute is a user-defined annotation of one of the other classes: a key/value pair.  An attribute has the following members:
     
    229234Should a program need to call the constructor, it takes the member names as named parameters.
    230235
    231 === CPU Class ===
     236==== CPU Class ====
    232237
    233238This represents a CPU on a computer.  It has the following members:
     
    240245The constructor takes the member names as named parameters.
    241246
    242 === !OperatingSystem Class ===
     247==== !OperatingSystem Class ====
    243248
    244249This class captures the operating system requirements of a computer.  It has the following members:
     
    258263The 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.
    259264
    260 === Storage Class ===
     265==== Storage Class ====
    261266
    262267The storage requirements or information for a system.  This class characterizes memory or permanent storage.  Its members are:
     
    273278The constructor takes the member names as named parameters.
    274279
    275 === Software Class ===
     280==== Software Class ====
    276281
    277282This indicates what software must be installed on a system.  Its members are:
     
    284289The constructor takes the member names as named parameters.
    285290
    286 === Service Class ===
     291==== Service Class ====
    287292
    288293A 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:
     
    307312The constructor will take the member names as named parameters.
    308313
    309 === !ServiceParam Class ===
     314==== !ServiceParam Class ====
    310315
    311316A description of the type of parameter to a [TopdlLibrary#ServiceClass Service] will accept.  It has the following members:
     
    321326The constructor will take the member names as named parameters.
    322327
    323 === Testbed Class ===
     328==== Testbed Class ====
    324329
    325330This 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.
     
    352357The constructor takes the member names as named parameters.
    353358
    354 === Segment Class ===
     359==== Segment Class ====
    355360
    356361This 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.
     
    367372   A list of [TopdlLibrary#AttributeClass Attribute objects] that are attached to the segment.  The list may be empty.
    368373
    369 === ID Class ===
     374==== ID Class ====
    370375
    371376This class represents a polymorphic identifier as used by the federation system.  At most one of its members is set.
     
    386391The constructor accepts the member names as named parameters.
    387392
    388 === Other Class ===
     393==== Other Class ====
    389394
    390395This 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.
     
    475480An 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.
    476481
    477 = Examples =
     482== Examples ==
    478483
    479484This section contains some illustrative examples.
    480485
    481 == Making a Topology ==
     486=== Making a Topology ===
    482487
    483488This example constructs the topdl describing a simple start topology with 11 nodes, one center and 10 satellites.
     
    547552}}}
    548553
    549 == A More Complex Topology ==
     554=== A More Complex Topology ===
    550555
    551556The 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.
     
    625630The 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.
    626631
    627 == Annotating A Topology ==
     632=== Annotating A Topology ===
    628633
    629634The 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.
    630635
    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.
     636Here 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.
    632637
    633638{{{
     
    647652}}}
    648653
    649 == Adding Other Classes ==
     654=== Adding Other Classes ===
    650655
    651656This 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].
     
    681686}}}
    682687
    683 == Changing a Topology (adding connections) ==
     688=== Changing a Topology (adding connections) ===
    684689
    685690This 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.
     
    753758It 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.
    754759
    755 == Output to NS2 ==
     760=== Output to NS2 ===
    756761
    757762Finally, 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.
     
    799804}}}
    800805
    801 == Putting It All Together ==
     806=== Putting It All Together ===
    802807
    803808The complete example is [attachment:example.py attached to this page.]  It consists of :