Changes between Version 13 and Version 14 of TopdlLibrary


Ignore:
Timestamp:
Oct 8, 2012 10:11:36 AM (7 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TopdlLibrary

    v13 v14  
    395395The constructor accepts the member names as named parameters.
    396396
     397== Procedures ==
     398
     399There are several procedures in the library for inputting and outputing topologies in various formats.  This section explains their use.
     400
     401=== topology_from_xml ===
     402
     403{{{topology_from_xml}}} reads a topdl-encoded topology and returns a [TopdlLibrary#TopologyClass Topology object].  The encoded topology may be in a file or string and the enclosing element name may be set.  It is the inverse of [topdlLibrary#topology_to_xml topology_to_xml]. The parameters are:
     404
     405 {{{string}}}::
     406  A string containing the XML to parse.  If it is set {{{file}}} and {{{filename}}} must be None.
     407 {{{file}}}::
     408  An open python file or file-like object that holds the XML to parse.  It must be open for reading. If it is set {{{string}}} and {{{filename}}} must be None.
     409 {{{filename}}}::
     410  A string containing the filename that holds the XML to parse. If it is set {{{string}}} and {{{file}}} must be None.
     411 {{{top}}}::
     412  The name of the element that contains the topdl to parse.  Topdl is embedded in other soap objects and XML files. This allows the library to extract the topdl from more complicated XML.  If not given it defaults to "topology".
     413
     414Exactly one of {{{string}}}, {{{file}}}, and {{{filename}}} must be given, and to avoid confusion it is best to call {{{topology_from_xml}}} with named parameters.
     415
     416=== topology_to_xml ===
     417
     418Returns a string containing the topdl representation of the given topology, the inverse of [TopdlLibrary#topology_from_xml topology_from_xml].  The enclosing element may be passed as a parameter.  The parameters are:
     419
     420  {{{t}}}::
     421   The [Topdl#TopologyClass Topology object] to encode.
     422  {{{top}}}::
     423   A string containing the name of the element that will enclose the topdl.  If not given, no element will enclose the topdl.
     424
     425=== topology_to_ns2 ===
     426
     427Returns a string containing an {{{ns2}}} representation of the topology.  [TopdlLibrary#ComputerClass Computer objects] are rendered as nodes and [TopdlLibrary#SubstrateClass substrate objects] as lans.  The output can be customized with [TopdlLibrary#ns2FilterFunctions filter functions].  The parameters are:
     428
     429 {{{t}}}::
     430  The [TopdlLibrary#TopologyClass topology class] to encode
     431 {{{filters}}}::
     432  A list of [TopdlLibrary#ns2FilterFunctions filter functions] applied in order as the output is constructed.  If unspecified the list is empty.
     433 {{{routing}}}::
     434  A string that sets the [https://trac.deterlab.net/wiki/Tutorial/CreatingExperiments#SettingupIProutingbetweennodes experiment routing style].  The Default is "Manual"; single testbed experiments will probably want "Static".
     435
     436==== ns2 Filter Functions ====
     437
     438[TopdlLibrary#topology_to_ns2 topology_to_ns2] takes a list of filter functions to customize its output.  Each filter must be callable and accept a single parameter and return a string.  The parameter can be an element or substrate.  That is, {{{e}}} can be a [TopdlLibrary#ComputerClass Computer object], [TopdlLibrary#TestbedClass Testbed object], [TopdlLibrary#SegmentClass Segment object], or [TopdlLibrary#OtherClass Other object], or [TopdlLibrary#SubstrateClass Substrate object].  A callable class is useful if the filter needs to act on internal state.
     439
     440{{{topology_to_ns2}}} calls filters as it generates output.  It outputs elements first by traversing its [TopdlLibrary#TopologyClass topology] parameter's elements in order.  For each element, the filters provided to {{{topology_to_ns2}}} are called in order and their output appended to the ns2 string.  After all elements are output, the substrates are traversed, and again the filters called in order.  The filter output comes after the {{{topology_to_ns2}}} output for each element and substrate.
     441
     442Inside a filter it is often useful to translate an element or substrate name into something valid to ns2.  The {{{to_tcl_name}}} function is in the topdl namespace for this purpose. It takes a string and returns the tcl name for it.  When assigning to the name, this sequence is used:
     443
     444{{{
     445tname = topdl.to_tcl_name(elem.name)
     446out += 'set %s [$ns node]' % tname
     447}}}
     448
     449when dereferencing the name - which is much more common:
     450
     451{{{
     452tname = topdl.to_tcl_name(elem.name)
     453out += 'tb-set-node-hardware ${%s} MicroCloud' % tname
     454}}}
     455
     456The output of {{{to_tcl_name}}} should be enclosed in { } to avoid tcl/ns parsing errors.
     457
     458=== topology_to_rspec ===
     459
     460Converts a topology to a [https://protogeni.org ProtoGENI] [http://www.protogeni.net/trac/protogeni/wiki/RSpec rspec] and returns it as a string.  The parameters are:
     461
     462 {{{t}}}::
     463  The [TopdlLibrary#TopologyClass topology class] to encode
     464 {{{filters}}}::
     465  A list of [TopdlLibrary#ns2FilterFunctions filter functions] applied in order as the output is constructed.  If unspecified the list is empty.
     466
     467The filter functions work the same way as in [TopdlLibrary#ns2FilterFunctions topology_to_ns2].
     468
     469=== Parsing from ns2 ===
     470
     471An 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.
     472
    397473= Examples =
    398474