port

This package provides a means for PLAN programs to interact with host applications. The package makes use of the PLAN type port, which serves to name a duplex connection between an active router and a host application. The active router side of the port always receives PLAN packets, while the application side receives output in a number of formats, depending on the service command used. When a PLAN packet is first injected into the network onto a particular node, it is associated with its injection port on that node. This port is referred to as the implicit port of a packet.

Currently, ports are implemented as TCP/IP connections -- that is, each PLAN port names a TCP/IP connection between some Active Router and a host application.

Ports may be created implicitly or explicitly. Each Active Router has a server socket listening to a particular TCP port number (specified when the router is invoked, see the tutorial document for more) which accepts client connections. When this connection is created, the router tracks it in a table and creates a PLAN port to name the connection. Any packets that arrive via this connection will have this PLAN port as their implicit port. A port may be created explicitly within an executing PLAN program by the routine openPort. This routine attempts to connect to a server application listening on the specified host and TCP port number, and if successful returns the PLAN port associated with the connection.

Ports are only valid on the router which shares the TCP connection that the port names. In other words, if port A lives on router R, but a PLAN program attempts to send data through it while executing on router S, the operation will fail.

Note that PLAN port names are not stored in any explicit way on the routers. Therefore, a PLAN program that wishes to use a port must retain the name of that port. This serves to prevent one PLAN application from using the ports of another. Note that PLAN programs may use the resident data facility to store the names of ports on the routers (see Subsection 6.2.3 for more on resident data).

A TCP connection named by a port is closed whenever a PLAN program explicitly closes it via closePort, or when the peer terminates the connection.

• 
  This function takes no arguments and returns the implicit port of the invoking PLAN program. Note that this port will not be valid if it was previously closed using the closePort service.

• 
  This function attempts to create a TCP connection between the invoking host and a server application residing on that host listening on the specified UDP port number. If successful, the function returns a port naming that connection. On failure, the exception OpenFailed is raised.

• 
  This function closes the TCP connection associated with the passed in port. If the port was closed previously, or does not reside on this router, the exception InvalidPort will be raised.

• 
  This function is identical to the core service print except that the output is transmitted via the specified port, rather than via the invoking packet's implicit port. The commands print(a) and printPort(getImplicitPort(),a) are identical. If the port was closed previously, or does not reside on this router, the exception InvalidPort will be raised.

• 
  This function is identical to printPort, above, except in the form of its output. Rather than converting the specified PLAN value to a string, the value is instead structurally marshalled to be sent across the connection. This marshalling scheme is not currently documented, but is defined by the class basis/Marshalling.pizza. This routine is useful when the receiving host application wishes to manipulate PLAN values directly. This application, if written in Java, would make use of the basis package, which defines Java/Pizza versions of PLAN's values (the ones used by the implementation, in fact). One example of such an application is provided by port/PortTest.pizza. When executed, PortTest listens on port 5001 for connections, and prints out the PLAN values it receives from those connections. A sample PLAN program to use with this application is rout_tests/deliver.plan.

  If the specified port was closed previously, or does not reside on this router, the exception InvalidPort will be raised. If delivery fails for any other reason, the exception DeliveryFailed will be raised.