4 Getting Started
The quintessential first problem solved in any programming language is
the ``Hello world'' program.
4.1 The Hello world program
A PLAN program is a list of definitions, which could be function
definitions, exception declarations, or variable bindings (in the ML
style). In the case of the Hello world program, there is just one
function :
svc print : 'a -> unit
svc thisHost : void -> host list
fun doit () =
(print (thisHost ()); print(" says : Hello world!\n"))
4.2 Run the Hello world program : The inject program
Before we try and understand the program, let us run it to see if it
works!
The inject program is provided as a means to inject PLAN programs into
the network directly from the command line. Get the usage information as
follows:
% bin/inject -help
usage : bin/inject [-v] [-val] [-p port] [-ed evalDest] [-rf routFun]
[-hf host_file] [-o outfile] <codefile>[,codefile2]...] <RB>
-v Turn on verbose mode.
-val Unmarshall and print responses as values (rather than strings).
-p Set default port. (default=3324)
-ed Set initial evaluation destination.
-rf Specify routing function.
-fid Specify flow ID. (default=0)
-hf Specify file for hostname resolution. (default=EXP_IP_ADDRS)
-o Specify file to output marshalled packet. (default=None)
The mandatory arguments are (at least one) codefile, and an integer resource
bound, or RB. The codefile argument is the name of the file (or files) that
contain the PLAN program. The RB argument specifies the initial amount of
resource (more on this later) to hand to the packet going into the network.
The -v option produces a verbose output. The -val option
prints output received as the string representations of PLAN values
rather than as strings; this is useful for printing the results of the
deliver service (see the Programmer's Guide). The -p option allows
you to specify the PLAN port number of the router to receive the message.
This must match the number given to -ip for some pland running
on the local machine. This also serves to set the port portion of the
identity should the thisHost local service routine be invoked during
the initial invocation (see the ping example below).4 If no -p is given, the default is 3324. The options
-ed and -rf specify the evaluation destination and routing function of the packet you are injecting. By default, the
evaluation destination (that is, the node on which the program should
evaluate) is set to the local pland5. For this reason,
the default is for this field (that is, the function that is used to help
the packet get to its evaluation destination) to be empty. Should you
decide that the first location that your program should execute is not
the local node, you would indicate where (and how to get there) with these
options. The flow id is set with -fid; this option isn't important
for now. The -hf option is used to specify the hostname file. This
file is used by the getHostByName function to map domain names to
network addresses. Finally, -o may be used to write the resulting
PLAN packet to a specified file rather than to the local interpreter. This
may be useful for `pre-creating' PLAN packets to be injected into the
network by a means other than the local PLAN interpreter.
The Hello world program may be found in the file interp_tests/Helloworld.plan, and that you want to use the host m:3324
as the network entry point. Let us also give this program an initial
resource amount of 10.6 Now type (again, from the plan directory):
% bin/inject -p 3324 interp_tests/Helloworld.plan 10
or alternatively
% bin/inject interp_tests/Helloworld.plan 10
The program waits for you to give it the next input : the initial
invocation. Recall that a PLAN program is a list of definitions - when
the program arrives at an active host, you must specify which function
to start executing and with what arguments. In the case of the
Hello world program, there is only one function to execute, and it
takes no parameters, so you type:
doit ();
followed by a carriage return.7 Out comes the response:
[(some.ip.address,3324);<loopback>] says : Hello world!
Notice that you must press Ctrl-C to get back to the command line. This is
because inject waits for possible responses; since it does not know
how many responses to expect, it has to wait indefinitely until told
explicitly to stop. Notice that a list of names is returned as a
result of the thisHost call, which differs from PLAN 2.x. This is
because each PLAN router, like an Internet router, may have multiple network
interfaces with one address assigned per interface. All routers will have
at least two addresses: a network address and a loopback address.
As a final note, had you included the -v option, you would have seen
the following (the initial invocation as if you had typed it is included):
% bin/inject -v -p 3324 interp_tests/Helloworld.plan 10
Using port 3324 on localhost.
Initial resource bound of 10.
Consuming host resolution file EXP_IP_ADDRS.
Attempting to read code from files interp_tests/Helloworld.plan...done
Parsing ...
Enter initial invocation:
doit()
Initial invocation parsed.
1.1-1.6: Warning: service doit not declared.
Initial invocation typechecked.
Packet is 139 bytes
[127][0][0][1][12][252][0][0][0][10][127][0][0][1][12][252][0][0][0][0]
[0][0][0][0][0][12]defaultRoute[0][10]defHandler[0][0][0]U[0][4]doit[0]
[0][0][1][2][0][4]doit[0][0][0][11][0][0][0][2][2][0][5]print[0][1][2][
0][8]thisHost[0][0][2][0][5]print[0][1][0][3][0][0][0][21] says : Hello
world![10]
[(127.0.0.1,3324);<loopback>] says : Hello world!
This is useful in debugging errors.
4.3 Understanding the program
This very simple program defines a function called doit, which
takes no parameters, and returns a unit result, as inferred by the
PLAN type-inference algorithm.
The body of the function calls a service routine called print. The
print routine takes a single argument, which is the datum to print.
The second print call is invoked on a string, while the first argument
is yet another service routine call; the thisHost service routine
returns a value of type host list which is a representation of the
active router that the program is currently executing on. Both service
routines are declared as prototypes using the svc keyword.
Figure 1: The PLAN network environment
To illustrate how the print routine is working, let us briefly look at
how PLAN programs are injected by a host into the active network, and
how the host obtains their output. Figure 1 illustrates a
hypothetical active network and a host with an application that desires to
inject a PLAN program into that network. To do this, the application opens
a connection to the local PLAN interpreter, and constructs and submits a
PLAN packet via this connection. The PLAN packet contains the PLAN code to
execute, which in our example is the ``Hello World'' code, as well some
other things that we need not worry about yet. This connection also serves
to pass output from the PLAN program back to the host. It is via this
connection that inject receives the output generated by the print command, and it is inject that displays this output on your
screen.
In PLAN, this connection is referred to as a PLAN port. PLAN ports
are duplex connections between host applications and active routers. The
active router side of the PLAN port always receives PLAN packets, while the
application side receives output in a number of formats, depending on the
service command used; for the print routine, the output format is a
string. When a PLAN packet is first injected into the network onto a
particular node, it is associated with its injection PLAN port on that node.
That way, output routines such as print have a default PLAN port upon
which to send their output. These routines will only work on the injection
node, because that is where the PLAN port resides. For example, in
Figure 1, the PLAN program in the packet submitted by Host
will have its print output sent back to Host via the injection
PLAN port so long as it is executing on Host. If the program were
to move to another node and then execute the print routine, an
exception would be raised.
For a precise description of what the various service routines do, and a
greater exposition on PLAN ports, please refer to the PLAN Programmer's
Guide [5].
