Commit 3daa67f3 authored by Gary Wong's avatar Gary Wong

Complete the geni-lib parameter section.

parent 4c641655
......@@ -197,4 +197,81 @@ and is free to respond by constructing arbitrarily different resource
requests based on that input.
The profile above accepts exactly one parameter---the number of VMs it
will instantiate.
will instantiate. You can see that the parameter is described via the
portal @tt{Context} object, using the @tt{defineParameter} call shown
for the first time in this example. @tt{defineParameter} must be
invoked once per profile parameter, and requires the parameter symbol,
parameter description, type, and default value respectively. The
parameter symbol (@tt{"n"} in this example) must be unique within the
profile, and is used to retrieve the parameter's value during script
execution. The description (@tt{"Number of VMs"}, in this case) will
be shown to prompt the user to supply a corresponding value when the
the profile is instantiated. The type is used partly to constrain the
parameters to valid values, and partly to assist the instantiating
user by suggesting appropriate choices. The list of valid types is:
@(tabular #:style 'boxed #:sep (hspace 3) (list
(list "portal.ParameterType.INTEGER"
"Simple integer")
(list "portal.ParameterType.STRING"
"Arbitrary (uninterpreted) string")
(list "portal.ParameterType.BOOLEAN"
"True or False")
(list "portal.ParameterType.IMAGE"
"URN to a disk image")
(list "portal.ParameterType.AGGREGATE"
"URN of a GENI Aggregate Manager")
(list "portal.ParameterType.NODETYPE"
"String specifying a type of node")
(list "portal.ParameterType.BANDWIDTH"
"Floating-point number specifying bandwidth in kbps")
(list "portal.ParameterType.LATENCY"
"Floating-point number specifying delay in ms")
(list "portal.ParameterType.SIZE"
"Integer used for memory or disk size (e.g., MB, GB, etc.)")))
The last field is the default value of the parameter, and is required: not
only must the field itself contain a valid value, but the set of
@italic{all} parameters must be valid when each of them assumes the
default value. (This is partly so that the portal can construct a
default topology for the profile without any manual intervention, and
partly so that unprivileged users, who may lack permission to supply
their own values, might still be able to instantiate the profile.)
After all parameters have been defined, the profile script may retrieve
the runtime values with the @tt{bindParameters} method. This will return
a Python class instance with one attribute for each parameter (with the
name supplied during the appropriate @tt{defineParameter} call). In the
example, the instance was assigned to @tt{params}, and therefore the
only parameter (which was called @tt{"n"}) is accessible as @tt{params.n}.
Of course, it may be possible for the user to specify nonsensical values
for a parameter, or perhaps give a set of parameters whose combination
is invalid. A profile should detect error cases like these, and respond
by constructing a @tt{ParamaterError} object, which can be passed to
the portal context's @tt{reportError} method to abort generation of
the RSpec.
@section[#:tag "geni-lib-debugging"]{Debugging @tt{geni-lib} profile scripts}
It is not necessary to instantiate the profile via the portal web interface
to test it. Properly written profile scripts should work perfectly well
independent of the normal portal---the same @tt{geni-lib} objects will
behave sensibly when invoked from the command line. As long as
@hyperlink["https://bitbucket.org/barnstorm/geni-lib/src"]{@tt{geni-lib} is
installed}, then invoking the Python interpreter on the profile script
should simply write the corresponding RSpec to standard output. (Parameters,
if any, will assume their default values.) For instance, if the script
in the previous example is saved as @tt{geni-lib-parameters.py}, then
the command:
@(elem #:style code-sample-style "python geni-lib-parameters.py")
will produce an RSpec containing three nodes (the default value for @tt{n}).
It is also possible to override the defaults on the command line by
giving the parameter name as an option, followed by the desired value:
@(elem #:style code-sample-style "python geni-lib-parameters.py --n 4")
The option @tt{--help} will list the available parameters and their
descriptions.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment