Changes between Version 22 and Version 23 of TopdlLibrary

Oct 8, 2012 3:42:10 PM (7 years ago)



  • 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.
    7 = Reference =
    98== Installing and Accessing ==
    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.
    56 === Adaptive Constructors ===
     55=== Common Features ===
     57All topdl library classes share a couple features, described here.
     59==== Adaptive Constructors ====
    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.
    83 === Topdl Class Features ===
     86==== Shared Functions ====
    8588All topdl classes implement the following methods:
    99102   Return the XML encoding (from the topdl language) of this object (and nested objects)
    101 === Topology Class ===
     104=== Individual Classes ===
     106==== Topology Class ====
    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.
    128 === Computer Class ===
     133==== Computer Class ====
    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.
    164 === Substrate Class ===
     169==== Substrate Class ====
    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.
    199 === Interface Class ===
     204==== Interface Class ====
    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.
    218 === Attribute Class ===
     223==== Attribute Class ====
    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.
    231 === CPU Class ===
     236==== CPU Class ====
    233238This represents a CPU on a computer.  It has the following members:
    240245The constructor takes the member names as named parameters.
    242 === !OperatingSystem Class ===
     247==== !OperatingSystem Class ====
    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.
    260 === Storage Class ===
     265==== Storage Class ====
    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.
    275 === Software Class ===
     280==== Software Class ====
    277282This indicates what software must be installed on a system.  Its members are:
    284289The constructor takes the member names as named parameters.
    286 === Service Class ===
     291==== Service Class ====
    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.
    309 === !ServiceParam Class ===
     314==== !ServiceParam Class ====
    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.
    323 === Testbed Class ===
     328==== Testbed Class ====
    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.
    354 === Segment Class ===
     359==== Segment Class ====
    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.
    369 === ID Class ===
     374==== ID Class ====
    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.
    388 === Other Class ===
     393==== Other Class ====
    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 [] program.  That program contacts a running fedd (like the one running on {{{}}}) to call an otcl system to do the parsing.
    477 = Examples =
     482== Examples ==
    479484This section contains some illustrative examples.
    481 == Making a Topology ==
     486=== Making a Topology ===
    483488This example constructs the topdl describing a simple start topology with 11 nodes, one center and 10 satellites.
    549 == A More Complex Topology ==
     554=== A More Complex Topology ===
    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.
    627 == Annotating A Topology ==
     632=== Annotating A Topology ===
    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.
    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.
    649 == Adding Other Classes ==
     654=== Adding Other Classes ===
    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].
    683 == Changing a Topology (adding connections) ==
     688=== Changing a Topology (adding connections) ===
    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.
    755 == Output to NS2 ==
     760=== Output to NS2 ===
    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.
    801 == Putting It All Together ==
     806=== Putting It All Together ===
    803808The complete example is [ attached to this page.]  It consists of :