5   Some PLAN Primops

5.1   Network Primitives

• OnRemote
  The first basic network primitive, OnRemote, is quite general. Its syntax is:
  OnRemote( E, H, Rb, Routing )
  The meaning of this primitive is: evaluate E on node H. Furthermore, use the Routing function to determine how to get to H. Finally, the current packet donates Rb of its resource bound to the child packet.
  
  More specific restrictions follow:
  • E must be an expression of type a chunk. Typically, a chunk literal is created used the syntax described in Section 6.1. This syntax resembles a function call in which the function f to be called is surrounded by |'s. The arguments of the function (a₁,...,a_n) are evaluated locally (becoming v₁,...,v_n), while the function itself will be evaluated remotely.
  • H is an expression of type host.
  • Rb is an integer indicating how much of the parent's global resource bound should be transferred to the child packet.
  • Routing should be a service (not a PLAN function) of type host®host × dev. Routing(h) should return some node h' which is a neighbor of the current node (with the idea being that h' is the next hop on a route to h in the routing scheme represented by Routing).
  
  On success, the call to OnRemote will create a PLAN packet which is sent to h', decrementing the current packet's resource bound by the designated amount. The invocation part of the PLAN program in the newly created PLAN packet consists of f(v₁,...,v_n) (where f is the function named in the chunk, and v₁,...,v_n are the actual paremeters) and the code part consists of the subset of the code of the invoking program that is required to properly evaluate the invocation. The remainder of the packet is defined by the remaining three arguments to OnRemote. Within the currently executing program OnRemote returns unit.
  
  In the event of an error, one of the following exceptions will be raised (and the creation of the packet aborted):
  • NotEnoughRB will be raised if Rb exceeds the parent packet's current resource bound.
  • HostNotLocal will be raised if the Routing function maps H to a node which is not a neighbor of the current node.
  
  
• RetransOnRemote
  The second network primitive, RetransOnRemote is similar to OnRemote, except it tries to ensure reliable delivery of the PLAN packet. The syntax is :
  
  
  RetransOnRemote ( Cs, K, n, H, Rb, Routing )
  
  Here, we want the chunks Cs (which could be the fragmented parts of a PLAN packet) to be sent to the node H using the routing function Routing, and resource bound Rb for each chunk. The packet should be retransmitted every second until an acknowledgement is received (as indicated by the invocation of the service function reliableAck, see below), up to a maximum of n times. Specifically :
  
  
  • Cs is a list of chunks.
  • K is an expression of type key, and ``names'' the chunks Cs. In particular, the retransmission of these chunks will be halted when the function reliableAck (see Section 7.2.9) is executed on the sending node with K as an argument.
  • n is the maximum number of times to retransmit the chunks Cs.
  • H is the node at which the chunks Cs should be evaluated.
  • Rb is the amount of resource bound that is given to each chunk in Cs.
  • Routing is the routing function used to route the packets to H.
  
  RetransOnRemote will return unit on success, and might raise one of the following exceptions in case of an error :
  
  
  • NotEnoughRB will be raised if Rb exceeds the parent packet's current resource bound.
  • HostNotLocal will be raised if the Routing function maps H to a node which is not a neighbor of the current node.
  
  For an example of the use of RetransOnRemote, see Section 7.2.9.
  
  
• OnNeighbor
  The final primitive, OnNeighbor is similar to OnRemote, with the restriction that the generated child packet must execute on a neighbor of the current node. The syntax is:
  OnNeighbor( E, H, Rb, D )
  Here, we want E to be evaluated on H (a neighbor of the current node), and Rb of the current packet's resource bound will be transferred to the child packet. D specifies the device that the packet should be sent through. More specifically:
  
  
  • As with OnRemote, E must be a chunk.
  • H is a expression of type host, and must be a neighbor (that is, on the same link layer network) of the current node.
  • Rb is an integer expression indicating how much of the parent's resource bound should be transferred to the child packet.
  • D is an expression of type dev that indicates the device that the packet should be sent through. A device value corresponds to an entity specified in the interface configuration file. See the active router manual for more details [4]. Devices are normally acquired as the result of calling a routing function (like defaultRoute), or by querying how the packet arrives (getSrcDev)---see Section 7.1 for details on these services.
  
  On success, the call to OnNeighbor will return unit. In the event of an error, one of the following exceptions will be raised:
  • NotEnoughRB will be raised if Rb exceeds the parent packet's current resource bound.
  • HostNotLocal will be raised if H is not a neighbor of the current node.

5.2   List Iterators

• foldl : (a × b ® a) × a × b list ® a
  Although the type above is correct, current PLAN programs may only have a function name appearing in the function argument to foldl (which is only natural, since PLAN does not have anonymous functions). The meaning of
  foldl(f, a, [b₁; ... ;b_n])
  is
  f(f ... f(f(a,b₁),b₂)...,b_n)
  
  
• foldr : (a × b ® b) × a list × b ® b
  As for foldl, the function argument to foldr must be a function name. The meaning of
  foldr(f,[a₁; ...; a_n],b)
  is
  f(a₁,f(a₂,... f(a_n,b) ... ))

5.3   Summary of Other Operators