Walnut/Ordinary Programming

From Erights

(Difference between revisions)

Revision as of 16:58, 26 November 2006

Ordinary Programming

In case you skipped the introduction, this is a last reminder that the fireworks start with Distributed Computing, and you can go there now, or continue to read about normal, ordinary computing in E, starting with Hello World.

Hello World

We will show Hello World as both an E program and an rune script. Rune first: just type


 ? println("Hello World")

when you hit the Enter key, you will get


 Hello World
 
 ?

To run an E program, put "println("Hello World")" into a text file. Make sure the file extension is ".e" (to run Swing-based apps, use extension ".e-awt", and to use SWT-based apps, use ".e-swt"). Type


 java -jar e.jar --rune textfilename.e

into a command shell (a DOS window under Windows, or a Cygwin or Unix shell, such as bash). The greeting will be printed to your display.

Now that you have started rune and run Hello World, it would be a good time to look at your trace log folder for the first time to make sure you know where to look. If you are on Windows95, the trace log will default to c:\windows\temp\etrace. The etrace folder location can always be found in the eprops.txt file in the E installation directory (under Unix, you will have created eprops.txt yourself from eprops-template.txt). You should, after launching rune, find one file in the trace folder, which is the trace log created for the rune session. It will probably be empty, unless you have gone wild experimenting with Hello World.

Simple data types, simple control flow

Here are some of the basics of the language:


 # E sample
 # Comment on this piece of code
 
 def a := 3
 var b := a + 2
 b += 1
 if (a < b) {
     println("a is less than b")
 } else {
     println("Wow, the arithmetic logic unit in this processor is confused")
 }

Variable declarations in E are made with the var statement. Variables that are only assigned a value once at creation (i.e., constants, or variables declared final) are created with the def statement. In E as in Java, "+=" is shorthand for adding the righthand value to the lefthand variable.

Single-line comments have a "#" at the beginning, and terminate with the end of line. The /**...*/ comment style is used only for writing javadoc-style E comments, discussed later. link here

Assignment uses the ":=" operator. The single equal sign "=" is never legal in E, use ":=" for assignment and "==" for testing equality. The function "println" prints to the console. The "if" statement looks identical to its Java equivalent, but the braces are required.

What is the end-of-statement delineator in E? In Java, you terminate a statement with a semi-colon. In E, the end-of-line is also the end-of-statement unless there is an open operation at the end of the line. In the example, the "if" statement's first line ends with an open brace; E knows the next line must be a continuation line. Some quick examples


 This works
 ? def a := 1 + 2 + 3 + 4
 # value: 10
 
 
 And this works
 ? def b := 1 + 2 +
 >   3 + 4
 # value: 10
 
 
 But this does not work, because the first line can and does 
 evaluate without a continuation, so the second line is a syntax error:
 ? def c := 1 + 2
 ?   + 3 + 4
 # example syntax error:
 #   + 3 + 4
 #   ^

The end-of-line statement termination of E makes it easy to use E for command lines, as in rune.

If your organization uses a line continuation convention that puts the operator at the beginning of the second line, you can use the explicit continuation character "\" as here:


 This also works
 ? def c := 1 + 2 \
 >   + 3 + 4
 # value: 10

Basic Types and Operators

The basic types in E are int, float, string, char, and boolean. All integer arithmetic is unlimited precision, as if all integers were BigIntegers.

Floats are represented as 64-bit IEEE floating point numbers. The operators +, -, * have their traditional meanings for integers and floats. The normal division operator "/" always gives you a floating point result. The floor divide operator "//" always gives you an integer, truncated towards negative infinity. So (-3.5 // 1) == -4.

E has 2 modulo operations: "%", like the Java modulo operator, returns the remainder of division that truncates towards zero. E also supplies "%%", which returns a remainder of division that truncates towards negative infinity.

Operator precedence is generally the same as in Java. In a few cases E will throw a syntax error and require the use of parentheses.

"+" when used with strings is a concatenation operator as in Java. It automatically coerces other types on the right-hand if the left-hand operand is a string:


 <font color="#FF0000"># E sample
 def x := 3
 def printString := "Value of x is: " + x</font>

You can also use quasi-literals, which enable the easy processing of complex strings as described in detail later; here is a very simple example:


 # E sample
 def printString := `Value of x is: $x`

wherein the back-ticks denote a quasi-literal, and the dollar sign denotes a variable whose value is to be embedded in the string.

&& and || and ! have their traditional meanings for booleans; true and false are boolean constants.

Strings are enclosed in double quotes. Characters are enclosed in single quotes, and the backslash acts as an escape character as in Java: '\n' is the newline character, and '\\' is the backslash character. Strings in E are so similar to strings in Java, it is easy to conclude they are identical when they are not. The protocol for E strings is detailed in the E javadoc.

== and != are the boolean tests for equality and inequality respectively. When the equality test is used between appropriately designated link to selfless here transparent immutables, such as integers, the values are compared to see if the values are equal; for other objects the references are compared to see if both the left and right sides of the operator refer to the same object. Chars, booleans, integers, and floating point numbers are all compared by value, as in Java. In addition, Strings, ConstLists, and ConstMaps link here are also compared by value, which makes it different from, and more natural than, Java.

Other transparent immutables (notably ConstLists and ConstMaps) will be introduced later. Additional useful features of transparent immutables are discussed under Distributed Computing.

There are some special rules about the behavior of the basic operators because of E's distributed security. These rules are described in the Under the Covers section later in this chapter.

Additional flow of control

We have already seen the if/then/else structure. Other traditional structures include:

while (booleanExpression) {...}
try{...} catch errorVariable {...} finally{...}
throw (ExceptionExpressionThatCanBeAString)
break (which jumps out of a while or for loop; if the break keyword is followed by an expression, that expression is returned as the value of the loop)
continue (which jumps to the end of a while or for, and starts the next cycle)
switch (expression) {match==v1{...} match==v2{...} ... match _{defaultAction}}

One structure that is more powerful than its Java counterpart is the for loop.


 # E sample
 for i in 1..3 {
    println(i)
 }
 for j in ["a", 1, true] {println(j)}

In this simple example, i becomes 1, 2, 3 in succession. In the second, j becomes each of the elements of the list.

The for loop operates not only with number ranges, but also with lists, maps (i.e. hashtables), text files, directories, and other structures discussed later in this book. The expanded version of the for loop that is needed to get both keys and values out of maps is:


 # E syntax
 for key => value in theMap {
     println(`Key: $key Value: $value`)
 }
 # You can get the index and the value from a list at the same time the same way
 for i => each in ["a", "b"] {
     println(`Index: $i Value: $each`)
 }

You can create your own data structures over which the for loop can iterate. An example of such a structure, and a brief explanation of the iterate(function) method you need to implement, can be found in the Library Packages: emakers section later in this chapter, where we build a simple queue object.

The Secret Lives of Flow Control Structures

Flow control structures actually return values. For example, the if-else returns the last value in the executed clause:


 # E sample
 def a := 3
 def b := 4
 def max := if (a > b) {a} else {b}

This behavior is most useful when used with the when-catch construct described in the chapter on Distributed Computing.

The break statement, when used in a for or a while loop, can be followed by an expression, in which case the loop returns the value of that expression.

(Note: the following patch of code is used by updoc.e, the E testing tool, to enable execution of all the upcoming code that depends on Swing)


 ?? in new vat awtVat.e-awt
 ? pragma.syntax("0.9")

Objects and Functions

As noted earlier, if the file is to use the Swing gui toolkit, it must have a suffix of ".e-awt". If the file is to use the SWT gui toolkit, it must have a suffix of ".e-swt". If the file will run headless, it should be placed in a file with suffix ".e".

Functions

A basic function looks like this:


 # E sample
 def addNumbers(a,b) {
     return a + b
 }
 # Now use the function
 def answer := addNumbers(3,4)

You can nest the definitions of functions and objects inside other functions and objects, giving you functionality comparable to that of inner classes in Java. Nested functions and objects play a crucial role in E, notably in the construction of objects as described shortly.

A parameterless function must still have an open/close paren pair. Calls to parameterless functions must also include the parens.

Functions can of course call themselves recursively, as in


 # E sample
 def factorial(n) {
     if (n == 0) {
         return 1
     } else {
         return n * factorial(n-1)
     }
 }

Dynamic "type checking" and Guards

E guards perform many of the functions usually thought of as type checking, though they are so flexible, they also work as concise assertions. Guards can be placed on variables, parameters, and return values.

Guards are not checked during compilation. They are checked during execution, and will throw exceptions if the value cannot be coerced to pass the guard. Guards play a key role in protecting the security properties when working with untrusted code, as discussed in Secure Distributed Computing.

The available guards include the items below. Some of them are typical types (String, int). Others are used most often in distributed programming, and are explained later in the book. A detailed explanation of all the things you can do with guards is postponed to the Additional Features chapter.put in link

int
char
float64
boolean
String
void
notNull
nullOk
near
vow
rcvr
pbc
Data
Java classes
E interfaces
subranges and more complex expressions

import weakpointermaker
makevat 2 args 1)kind of vat, string"headless, awt, swt",
2)name of vat for debugging
import seedvatauthor
authorize it to get a seedvat function with uri getter
seedvat takes 2 args: 1)vat
2)string that is contents of a dot-e file except
all evaluated at once. seedvat function returns a promise for
the result of evaluating that expression. since it evaluates in foreighn vat,
it is a far reference.typical pattern: only do importing and construction 
in the expression string

Here are some quick examples of guards being declared:


 # E sample
 # guarding a variable
 def title :String := "abc"
 # guarding a parameter, and a return value. Note the guard on the 
 # return value is part of the def line for the function.
 def reciprocal(x :float64) :float64 {
     return 1 / x
 }

Different people use different strategies about how much type checking/guard information to include in their programs. In this book, the general style is to use guards sparingly, as might be typical in a rapid prototyping environment. One place where guards must be used with rigor is in the objects on the boundaries between trust realms, in security aware applications; see the Powerbox pattern in the Secure Distributed Programming section for an important example. link here

Objects

Objects, and object constructors, look considerably different in E than in Java or C++. We will start our exploration of objects with a simple singleton object.

A Singleton Object

Objects, functions, and variables are defined with the keyword "def"; all of these can be passed as arguments in parameter lists. Methods on an object, in contrast, are defined with the keyword "to":


 # E sample
 def origin {
     to getX() {return 0}
     to getY() {return 0}
 }
 # Now invoke the methods
 def myY := origin.getY()

Like functions, methods require a parenthesis pair even if there are no arguments. (But, Python programmers beware, methods are not functions. Methods are just the public hooks to the object that receive messages; functions are standalone objects).

When invoking the method, the object name and the method called are separated by a dot.

Stateful objects and object constructors

The "class" concept in Java is used to achieve multiple goals. In E, these goals are factored out in a different way. For example, Java classes supply a place to put constructors, which have a special syntax unique to constructors. In E, objects are constructed by ordinary functions.


 # E sample
 # Point constructor
 def makePoint(x,y) {
     def point {
         to getX() {return x}
         to getY() {return y}
         to makeOffsetPoint(offsetX, offsetY)  {
             return makePoint(x + offsetX, y + offsetY)
         }
         to makeOffsetPoint(offset) {
             return makePoint(x + offset, y + offset)
         }
     } 
     return point
 }
 # Create a point
 def origin := makePoint(0,0)
 # get the y value of the origin
 def y := origin.getY()

Inside the function makePoint, we define a point and return it. As demonstrated by the makeOffsetPoint method, the function (makePoint) can be referenced from within its own body. Also note that you can overload method names (two versions of makeOffsetPoint) as long as they can be distinguished by the number of parameters they take.

The (x, y) passed into the function are not ephemeral parameters that go out of existence when the function exits. Rather, they are true variables (implicitly declared with "def" ), and they persist as long as any of the objects that use them persist. Since the point uses these variables, x and y will exist as long as the point exists. This saves us the often tedious business in Java of copying the arguments from the parameter list into instance variables: x and y already are instance variables.

We refer to an object-making function such as makePoint as a "Maker". Let us look at a more serious example, with additional instance variables:


 # E sample
 def makeCar(var name) {
     var x := 0
     var y := 0
     def car {
         to moveTo(newX,newY) {
             x := newX
             y := newY
         }
         to getX() {return x}
         to getY() {return y}
         to setName(newName) {name := newName}
         to getName() {return name}
     } 
     return car
 }
 # Now use the makeCar function to make a car, which we will move and print
 def sportsCar := makeCar("Ferrari")
 sportsCar.moveTo(10,20)
 println(`The car ${sportsCar.getName()} is at X location ${sportsCar.getX()}`)

Inside the Maker, we create the instance variables for the object being made (x and y in this example), then we create the object (car). Note that the variable "name", passed into the function, is explicitly declared with "var", so that it can be altered later; in this case, it is reassigned in the setName() method.

Self-referencing objects

Sometimes in the body of an object you wish to refer to the object itself. A keyword like "this" is not required. The name given to the object is in scope in the body of the object, so just use it:


 # E sample
 def makeCar(name) {
     var x := 0
     var y := 0
     def <span class="hilite">car</span> {
         to moveDistance(newX,newY) {<span class="hilite">car</span>.moveTo(x + newX, y + newY)}
         # ....define other methods including moveTo as above ....
     }
     return car
 }

What if you need to reference the object during the object's construction, i.e., during the creation of the instance variables that precedes the definition of the object itself? In the below example, we give the car a weatherReportRadio that is supposed to alert the car to changing weather conditions. This radio requires, as a parameter during its construction, the car it will be alerting. So the radio needs the car during radio construction, and the car needs the radio during car construction.


 # E sample
 def makeRadio(car) {
     # define radios
 }
 def makeCar(name) { 
     var x := 0 
     var y := 0
     # using def with no assignment
     def car
     def myWeatherRadio := makeRadio(car)
     bind car {
         to receiveWeatherAlert(myWeatherRadio) {
             # ....process the weather report....
         } 
         to getX() {return x} 
         to getY() {return y}
         # ....list the rest of the car methods....
     }
     return car
 }

Here, we do a "def" of the car with no assignment, then we use the car, then we do a "bind" of the car which binds a value to the car. This looks and behaves like a "forward reference" from C. Under the covers, the statement "def car" creates a promise for the car, and the bind statement fulfills the promise. We discuss promises in greater depth in the Distributed Computing chapter, where they play a key role.

Secret Life of Functions, Multiple Constructors and "Static Methods"

Before we can talk about multiple constructors and the static-method-like behavior in E, it is time to reveal the truth about E functions. They are in fact simple objects with a single method, the "run" method, that is invoked by default if no other method is explicitly designated. For example, the following square function


 # E sample
 def square(x) {return x*x}

is really syntactic shorthand for


 # E sample
 def square {
     to run(x) {return x*x}
 }

In the second one, the run() method is explicitly defined. Using this explicit form in a Maker function, you can define multiple constructors, discriminated by the number of parameters they receive. Similarly, by adding methods to the Maker other than "run" methods, you get other "static methods". In the example below, we have a queue Maker with 2 constructors and a non-constructor method. The one-argument constructor requires an initial capacity; the no-argument constructor supplies an initial capacity of 10.


 # E sample
 def makeQueue {
    to run(initialCapacity) {
        # ....create a queue object with the specified initial capacity....
    }
    to run() {return makeQueue(makeQueue.getDEFAULT_CAPACITY())}
    to getDEFAULT_CAPACITY() {return 10}
 }
 # Now use both constructors
 def queue1 := makeQueue(100)
 def queue2 := makeQueue()
 println(`default capacity is: ${makeQueue.getDEFAULT_CAPACITY()}`)

Note also that one can use methods such as getDEFAULT_CAPACITY() to achieve the same effect as Java achieves with public static final variables.

Polymorphism

E enables polymorphism through method name matching. In this example, we move both a car and an airplane to a new location using a single common piece of code:


 # E sample
 def makeCar(name) {
     def car {
         to moveTo(x, y) {
              # move the car
         }
         # other methods
     }
     return car
 }
 def makeJet(name) {
     def jet { 
         to moveTo(x, y) { 
             # move the jet, very different code from the code for car 
         } 
         # other methods 
    } 
    return jet
 }
 def vehicles := [makeCar("car"), makeJet("jet")]
 for each in vehicles {
     each.moveTo(3,4)
 }

Extends and Delegation

An object can refer calls to itself to another object (a "super-object", built by the "super-constructor", faintly similar to the way one uses superclasses in Java) using the extends keyword: think of better example


 ? def makePoint(x, y) { 
 >     def point { 
 >         to getX() {return x} 
 >         to getY() {return y}
 >         to getMagnitude() {return (x*x + y*y)**0.5} 
 >     }
 >     return point
 > } 
 # value: <makePoint>  
  
 ? def makePoint3D(x,y,z) { 
 >     def point3D extends makePoint(x,y) { 
 >         to getZ() {return z} 
 >         to getMagnitude() {
 >             def xy := super.getMagnitude()
 >             return (z*z + xy*xy)**0.5
 >         } 
 >     }
 >     return point3D 
 > } 
 # value: <makePoint3D>
 
 ? def place := makePoint3D(1,2,3)
 # value: <point3D>
 
 ? def x := place.getX()
 # value: 1
 
 ? def z := place.getZ()
 # value: 3

Here makePoint3D acts as an extension of makePoint. Inside the extends clause, we run the makePoint constructor to create the Point upon which the Point3D will be built. This specially constructed point is referred to in the point3D definition as "super"; you can see super being used in the getMagnitude method.

Using extends as described above follows the delegation pattern. Delegation is a simple pattern of object composition in which an object says, "if another object calls me with a method that I don't have defined here, just route the message to this other object, and send the result back to the caller." Delegation is similar to inheritance, but it is conceptually simpler.

Extends and Full Inheritance

Some experts consider inheritance to be a dangerous feature. A discussion of the pros and cons of inheritance is beyond the scope of this book. However, none of the full-blown examples in this book actually use full inheritance. Delegation, via the simple extends keyword plus polymorphism serve most of the purposes for which inheritance was intended, and is used everywhere here.

Having said that, there are times and places where full inheritance is the right answer. The extends keyword is also used, with one additional convention, to support such full inheritance. In inheritance, the "self" to which a super-object refers is the sub-object of which it is a part, so that the super-object can use methods in the sub-object:


 # E sample 
 def makeVehicle(self) {
     def vehicle {
         to milesTillEmpty() {
             return self.milesPerGallon() * self.getFuelRemaining()
         }
     }
     return vehicle
 }
 
 def makeCar() {
     var fuelRemaining := 20
     def car extends makeVehicle(car) {
         to milesPerGallon() {return 19}
         to getFuelRemaining() {return fuelRemaining}
     }
     return car
 }
 
 def makeJet() {
     var fuelRemaining := 2000
     def jet extends makeVehicle(jet) {
         to milesPerGallon() {return 2}
         to getFuelRemaining() {return fuelRemaining}
     }
     return jet
 }
 
 def car := makeCar()
 println(`The car can go ${car.milesTillEmpty()} miles.`)

As seen in the example, the super-object constructor specifies a parameter, "self", which can be used to refer to the sub-object. The sub-object includes itself in the the call to the super-object constructor, thus becoming "self".

General method name matching and E.call()

Delegation with extends does a straight pass-through of the method call. It is possible to intercept collections of calls before delegating them, using match. In this example, we count the number of calls made to a car:


 # E sample
 def makeCalledCountCar(name) {
     def myCar := makeCar(name) 
     var myCallCount := 0
     def car {
         to getCallCount() {return myCallCount}
         match [verb,args] {
             myCallCount += 1
             E.call(myCar,verb,args)
         }
     }
     return car
 }

In "match[verb,args]", the verb is a string specifying the name of the method being called, and the args is a list of arguments. If the car is called with a method that is not defined in a "to" statement, the name of the method and the arguments are bound to the variables inside the square brackets. We then increment the call count, and finally forward the message using the E.call function. E.call(...) takes as arguments the target object for the action, the name of the method to call, and the list of arguments for the method to invoke. You can manually use E.call() like this:


 # E syntax
 def car := makeCar("mercedes")
 E.call(car, "moveTo", [3,4])
 # which is equivalent to
 car.moveTo(3,4)

In this example, the elements for the argument list are placed in square brackets to form an E ConstList, described later in this chapter.

The match construct is useful for making "adapters" when interfacing to Java. Here we build a singleton object that can be used anywhere a java.awt.event.MouseListener would be used; the match clause is used to absorb and discard events in which we are not interested:


 # E sample
 def mouseListener {
     to mouseClicked(event) {
         # process the event
     }
     match [verb,args] {}
 }

This general purpose matching is also useful in security applications when building facets and revocable capabilities, as described in the chapter on Secure Distributed Computing.

Edoc, the E equivalent of JavaDoc

E supports the construction of javadoc-style comments that can be postprocessed into HTML documentation. For this purpose, the "/** ... */" comment format has been specially reserved; comments of this style can only appear in front of a function/object definition (a "def" statement), or in front of an object method definition (a "to" statement):


 # E sample
 /**
  * Add 2 numbers together.
  * <p>
  * Currently works with any objects that support the "plus" method
  *
  * @param a the first number. 
  * @param b the second number
  * @return  the result of adding. 
  */
 def adder(a, b) {return a + b}

For more information on how to generate Edoc HTML from your E programs, see the Advanced Topics.make link here

Under the covers: Everything is an Object

We have already discussed the fact that functions are really objects with a single method, "run". Functions-as-objects have one practical consequence that would be surprising in the absence of understanding. You cannot create two functions with different numbers of parameters and have them overloaded:


 # E syntax
 def times2(a) {return a * 2}
 def compute(a,b) {
     def times2(c,d) {return (c + d) * 2}
     # ....do computation...
     # The following line will throw an exception
     def answer := times2(a)
     return answer
 }

This would throw an exception because the inner definition of the function-like object times2 completely shadows the outer times2.

Not only functions, but also built-in constants like integers and floats, are objects. Operators such as "+" are really shorthands for message passing: 3.add(4) is identical to 3 + 4. This is why the operation


 <font color="#FF0000">"The number is " + 1</font>

works but


 <font color="#FF0000">1 + " is the number" </font>

does not. A string knows how to handle a concatenate message with a number as the argument, but an integer is clueless what to do with an add of a string.

Since "+" is really just shorthand for "add", you can construct objects that work with the "+" operator just by implementing an "add(argument)" method in the object.

Under the covers: Miranda Methods

There are a number of messages to which all normal objects respond, known as Miranda Methods. One example of such a method is the printOn(textWriter) method, which defines how an object will write itself out as by default. Other Miranda methods will be described in other sections of the book. The full list of Miranda methods can be found in the Appendix. You can also see them in rune by typing help(def obj{}) duplicate of next section, fix

One important note about Miranda methods: they are not forwarded by the extends structure, and they are not intercepted by the match[verb,args] structure. They are always directly interpreted by the object that receives them.

Getting Help About an Object With Rune

Another often convenient way of finding the list of methods associated with an object, be it a Java object or an E object or an object delivered as part of the E runtime, is to use the help(object) function of E, often used in rune.


 ? def add(a, b) {
 >     return a + b
 > }
 # value: <add>
 
 ? help(add)
 # value: an org.erights.e.elang.evm.EImplByProxy
 #        interface "__main$add" {
 #
 #            to run(:any, :any) :any
 #        }
 #
 ?

In this very simple example you see the "run" method listed here, which is the implicit method for a function. The rest of the methods shown are Miranda methods. For a more sophisticated object than a simple add function, each method in the object would be listed as well.

I/O

E file objects are created with the <file:name> expression (which produces a "tamed" Java File Object, i.e., a File object that follows capability security discipline). If you can hard-code the name, you usually do not need to use quotes (unless there is a space or another invalid url character). If the name is contained in a variable or is retrieved with a function call, you must XXX place a space between the colon and the representation of the name. If the word "file" is replaced with a single letter like "c", the letter is assumed to be the drive letter on a Windows machine:


 # E sample
 #File objects for hardwired files:
 def file1 := <file:myFile.txt>
 def file2 := <file:/home/marcs/myFile.txt>
 
 #Using a variable for a file name:
 def filePath := "c:\\docs\\myFile.txt"
 def file3 := <file>[filePath]
 
 #Using a single character to specify a Windows drive
 def file4 := <c:/docs/myFile.txt>
 def file5 := <c:\docs\myFile.txt>

Note that in the file4 example, we used slashes, not backslashes, to separate directories on a Windows drive. In E, the slash always works as a directory separator no matter the underlying operating system.

When constructing the filePath string we used double backslashes because in strings the backslash must be escaped by a backslash. A double backslash was not required in the hardwired file (file5).

File objects can represent directories as well as simple files. Files inside the directory can be accessed by indexing using square brackets:


 # E syntax
 def dir := <file:/home/marcs/dataDir/>
 def file6 := dir["myFile.txt"]

Both text files and directories work in conjunction with the "for" loop. With a directory, the loop iterates through the files in the directory. With a text file, the loop iterates through the lines of the file; each line-object is terminated with a newline ('\n') character. The lines in the loop are terminated with newline regardless of the underlying operating system, regardless of the operating system's end-of-line designation.

Files respond to the following messages (see the Edoc for a complete list).

exists -- returns true if the file exists
deepReadOnly -- returns a file object that can be read, but not written. If the file is a directory, the readOnly nature is transitive to all files and directories reached via this object.
setText(textString) -- creates the file and/or replaces the file contents with the text. When written out, the end-of-line designator is automatically converted to the local end-of-line mark for the underlying operating system. On Windows, for example, each line is automatically terminated by a cr/lf pair.
getText -- returns the text from the file. Regardless of underlying operating system, the returned text uses a single newline character as the end-of-line mark.
getBytes() -- returns the bytes of the file in a byte ConstList
setBytes(byteList)

stdout and stderr are both TextWriters in the E environment.

Example: looping through a directory tree searching for a file that contains a particular line

write the example

Data Structures

In the next section, we will learn how to interface to Java, which will allow you to use most of the data structures supplied by the underlying jvm. E does offer a few data structures of its own, however, which are not only convenient, but which have special properties useful in distributed programming.

Flex and Const, List, Map and Set

There are three built-in data structures in E, Lists, Maps, and Sets. Each of these structures comes in two flavors, Flex (editable) and Const (immutable). The ConstList is the simplest:


 # E sample
 def list := ["a",2,true]
 #This is true: list[0] == "a"
 #This is true: list[2] == true
 def newList := list + ["last"]
 #This is true: newList[3] == "last"
 for each in newList {println(`Element: $each`)}
 for i => each in newList {println(`Element number $i is $each`)}
 def listSize := newList.size()
 # get subrange starting at 0, running up to element 2, but not including element 2
 def subrange := list(0,2)
 #This is true: subrange == ["a",2]

Lists are numerically indexed starting from 0, use the "+" operator to create a new list which is the concatenation of lists. Lists work with the for loop. The "size" method returns the number of elements. The E String type is a kind of ConstList in which all the elements are characters. So, for example, the mechanism for taking a subrange shown above gives you a substring if the ConstList is a String.

You can make a FlexList from a ConstList with the diverge method:


 # E sample
 def newList := []
 def editable := newList.diverge()
 editable.push(100)
 if (editable.pop() == 100) {
     println("Yeah, push and pop make a list work like a stack")
 }
 editable[0] := "b"
 def frozen := editable.snapshot()

All the methods that work on a ConstList also work on a FlexList. In addition, there are editing operations for FlexLists, including push/pop (which allows the FlexList to behave like a stack) and element replacement that uses Java array-style syntax. You can get a ConstList from a FlexList with the snapshot method. Just as Java Strings are like ConstLists in which all elements are characters, Java StringBuffers are like FlexLists in which all elements are characters.

Maps are composed of key/value pairs. In the following example, in the ConstMap table, "a" is a key, and 1 is a value:


 # E sample
 def table := ["a" => 1, 2 => "b"]
 # This is true: table["a"] == 1
 # This is true: table[2] == "b"
 def emptyTable := [].asMap()
 def keyTable := ["a",1,true].asKeys()
 # This is true: keyTable[true] == null 
 # This is true: keyTable.maps("a") == true
 for key => value in table {println(`Key: $key Value: $value`)}
 for each in table {println(`Value: $each`)}
 def mapSize := table.size()

Elements in a map are retrieved using an array-like syntax, using the key as the index in the square brackets. Maps can be made from lists using asMap and asKeys; when you use asKeys, the values are nulls. The for loop works nicely with the map structures.

FlexMaps can be made from ConstMaps with the diverge method:


 # E sample
 def editableMap := table.diverge()
 editableMap["c"] := 3
 editableMap["a"] := "replacement"
 editableMap.removeKey(2)
 def frozenMap := editableMap.snapshot()

Values in a FlexMap can be added and replaced with array-like syntax. Key-value pairs can be removed with removeKey(key). The snapshot method creates a ConstMap from a FlexMap.

Sets are quite similar, with ["a","b"].asSet() producing a ConstSet with 2 elements. Documentation for all the operations on Const and Flex lists, maps, and sets can be reached directly from the Javadoc For E index.

A String is actually a ConstList of characters. You can create a FlexList of elements of a specific type by specifying the type in the diverge/snapshot method:


 # E sample
 def aString := [].diverge(char)

This aString will not accept elements which are not of type char; the variable aString has many of the characteristics of a StringBuffer from Java.

One feature of E that Java/C programmers will find surprising but useful is the ability to define multiple variables by using a list:


 # E sample
 def [a,b] := [2,3] 
 #a holds the value 2
 #b holds the value 3

While this is an amusing way to initialize a random bunch of variables at once, the structure is most valuable when creating groups of variables that have no meaning in the absence of one another. The method Ref.promise(), described in Distributed Computing, is an important user of this pattern.

Equality Testing for Structures

One of the biggest differences between Flex and Const structures is the test for equality. Const structures are compared by value, and as such are considered equal if their contents are identical. The test for equality is, in other words, the same as the test for equality between Java integers.

Two Flex structures are considered equal if and only if they are the same structure, i.e., both of the variables being tested are references to a single object. This test for equality is, in other words, the same as the test for equality between Java StringBuffers.

Interfacing to Java

Importing classes from the Java API

We can import a class from the underlying Java virtual machine with the import statement, and speak to the Java object much as we would speak to an E object: replace vector as example


 # E sample
 #create a single vector with a direct call to Java
 def myVector := <unsafe:java.util.makeVector>()
 myVector.addElement("abc")
 #create a makeVector function which can be called repeatedly to make more vectors
 def makeVector := <unsafe:java.util.makeVector>
 def vector2 := makeVector()
 # create a shorthand for the java.util package, that gives quick access to all the 
 # classes in java.util
 def <util> := <unsafe:java.util.*>
 def vector3 := <util:makeVector>()

In the example, we showed 3 ways of getting a Java object, which are roughly comparable to the different styles of using "import" in Java. If you just want one vector, you can get it by directly calling the vector constructor. If you plan to make many vectors, you can import the class into a variable. And if you plan to use many classes in a particular package, you can create your own representative for the package that you can use instead of "unsafe:". fixNote the suffix "__uriGetter" on the util variable. This is a special suffix that allows the variable to be used in statements of the form <uri:name>.

We have now seen 3 of these uriGetters, file:, unsafe:, and the programmer-defined util:. Four other uriGetters are also predefined, swing: (for accessing javax.swing) and awt: (for accessing java.awt), resource: (for read-only access to resource files such as images, sounds, and static texts), and import:, described next.

The import: uriGetter is similar to unsafe:, except it only imports those parts of the Java API that have been audited for capability security and found to convey no authority (see the Appendix for a definition of "authority").put in link, think of better example. Remove vector from the book Since the Vector class conveys no authority, you could also get a vector with import:


 def vector4 := <unsafe:java.util.makeVector>()

As discussed later with Library Packages and Secure Mobile Code, emakers cannot use unsafe: unless the unsafe__uriGetter is explicitly handed to them. So import: is often useful in these security-aware situations. A complete list of safe versus unsafe classes, and the small percentage of Java API methods which are suppressed for security reasons, are listed in the Appendix.link

resource: mention it is safe, can be used in emakers

getting static public constants from Java: must put parens after the name as if it was a method returning a value, not a variable.

As noted earlier, E does not have an expression to directly represent public static final variables. To use such static finals from a Java class, put parentheses at the end of the variable name, making it syntactically look like a function call, prefix it with "get", uppercase the first letter, and E will get the value for you:


 # E sample
 <unsafe:java.util.makeCalendar>.getYEAR()

Speaking to Java objects with superclass/subclass overloaded methods

Speaking to Java objects is usually as easy as shown above, where we simply sent myVector an addElement(object) message as if it were an E object. A problem arises with some Java objects if they have overloaded methods for which the only distinguishing mark is the static typing of the parameters in which one of the methods specifies a type that is a superclass of the type in the other method--a rare but not unheard-of situation. coercion causes same problemIn that case, we need to revert to a more descriptive messaging convention.

We introduced the E.call() function earlier for communicating with E objects. It can also be used to call Java objects and to specify the signature of an overloaded method with the types of the parameters. In this example, we see that the print function for the System.out object is overloaded for both String and Object, with String being a subclass of Object, so the full signature is required:


 ? def out := <unsafe:java.lang.makeSystem>.getOut()
 # value: <a PrintStream>
 
 ? out.print("abc")
 # example problem: <IllegalArgumentException: ...>
 
 ? E.call(out, "print(String)", ["abc"])
 ? def myLabel := E.call(<swing:makeJLabel>, "run(String)",["label text"])

If you encounter one of these special cases that requires multiple parameters, the signatures must be laid out with exact spelling and exact spacing, notably with exactly one space between the comma and the next signature:


 E.call(javaObject, "method(String, int)", ["abc", 23])

Arrays and primitive types

It is possible to make Java arrays of Java primitive types, as in this example:


 # E sample
 def makeFlexList := <elib:tables.makeFlexList>
 def byteArray := makeFlexList.fromType(<type:byte>, 300)
 byteArray.setSize(300)
 byteArray[0] := 3

Here we have created a 300-element editable array of bytes. The individual elements can be accessed with square bracket notation.

XXX Now that this example has been corrected, does it still serve its purpose? Also, it's not technically correct to say this makes a Java array. It makes an E FlexList, which, on E-on-Java, currently happens to be implemented by wrapping a Java array. However, if your program depends on this fact, it is probably broken.

Java Adapters and Interfaces

As described earlier, you can use the match[verb,args] construct to aid in writing adapters and other objects that must meet a Java interface specification. E will automatically manipulate the resulting E objects and the java virtual machine so that Java understands that the E object meets the interface specification. It is not possible to make subclasses of Java classes in E. However, because the developers of the Java API have wisely moved aggressively to make sure that interfaces, rather than subclasses, are core to Java object interoperability, there is virtually no Java interfacing goal that cannot be achieved with this machinery.

The Java API versus capability security

A final note: almost all of the objects and methods in the Java API are available in E for version 1.0 through the unsafe_uriGetter; unfortunately very few have been audited sufficiently to be included with the import__uriGetter. In the future, more of the API will be accessible through the import__uriGetter; however, some parts of the Java API will be altered and/or suppressed even in unsafe__uriGetter to achieve a more secure yet easier to use computing framework. This is discussed further in the chapter on Mobile Code. You can see the list of suppressed methods and unsafe classes in the Javadoc.

Quasi-Literals and Quasi-Parsers

E supports quasi-parsers. A quasi-parser allows one to compress large numbers of operations into a succinct notation (a quasi-literal) in a specific problem domain. Writing your own quasi-parsers (which can be done in E itself, as the JPanel quasiparser described below was written) is beyond the scope of this book. However, E comes with several quasi-parsers built in: a simple quasi-parser, a regular expression quasi-parser, a JPanel quasi-parser for Swing, and a swtGrid quasi-parser for SWT.

Simple quasi-parser

The default quasi-parser is a text manipulating parser capable of extracting data from strings and constructing new strings. In its simplest form, it is a clean and simple way of constructing strings for printing:


 # E sample
 def a := 3
 def answerString := `The value a is $a, and a times two is ${2 * a}.`
 println(answerString)

Here we use a simple quasi-parser to build an output string in a fashion similar to the printf statement in C. Quasi literals are enclosed in back-ticks. A dollar sign denotes the beginning of a description of a value to be inserted at the dollar sign location. If the dollar sign is immediately followed by a variable name, the value of that variable is used. If the dollar sign is followed by an open brace, everything up to the close brace is evaluated to compute the value to be substituted (so you could put "$" inside the braces to put a dollar sign in the string, as well as doing arithmetic as in the above example). Quasi-literals can span multiple lines, in which case the carriage return is part of the structure.

A more sophisticated use of simple quasi-literals is for pattern matching. Here we parse a sentence:


 # E sample
 def line := "By the rude bridge that arched the flood"
 if (line =~ `@word1 @{word2} rude @remainder`) {
     println(`text matches, word1 = $word1`)
 }

The string on the left of =~ is compared to the quasi literal on the right, evaluating true if the string can be parsed in conformance with the quasi literal. The "@" asserts that any text can match this part of the string, and the variable declared after the "@" contains that text at the end of the evaluation. The variable "word2" is enclosed in braces to offset it from the word "rude" immediately following it, which would look like part of the variable name without the offset.

In this example, the minimal string that can get a match would be space-space-"rude ", in which case the data extracted for variables word1, word2, and remainder would all be zero-length strings. As it is, at the end of the evaluation, word1=="By", word2=="the", and remainder == "bridge that arched the flood".

A single quasi-literal can contain dollar signs as well as "@"'s, in which case the results of the dollar sign evaluations will be included in the matching conditions.

Quasi-literals can almost always be treated as strings. They accept almost all of the string protocol (technically, the quasi-literals are of type "twine"). The one place where they cannot be treated as strings is in comparisons to actual strings. To compare a quasi-literal to a string, use the "bare" method: this is now wrong! all strings seem to now be twines

def equalStrings := "abc".bare() == `abc`.bare()

Regular expression quasi parser

The regular expression quasi-parser gives E much of the CGI scripting power that Perl and Python share. Since E runs on top of a jvm with all the startup time such jvms entail, using E for CGI scripts per se is not recommended. However, if one uses the distributed computing power of E to run CGI-like E programs as services for a Web server, one can achieve the same effect, and receive a number of bonuses unavailable in Perl and Python. The example Web server written in E, shown at the end of the book, was designed with just this thought in mind.

JPanel

The JPanel quasi-parser processes visually understandable strings into complex window panel layouts for gui applications. It is a most remarkable and useful example of quasi-parsers in action, giving the developer a rather WYSIWYG presentation of his windows. Thus the E programmer has no need to resort to the typical inflexible IDE-specific drawing tools that produce code no one can read and absolutely no one can edit. Under the covers, the JPanel uses the GridBagLayout manager to compose the panel, giving it a flexibility comparable to the TK layout system from TCL (which actually inspired the JPanel). Unlike the typical visual layout editors in Java IDEs, the JPanel system is able to define a broad range of resizable windows simply and intuitively.


 # E syntax
 # define the panels explanation,label, field, okButton, cancelButton, logo
 # pad1, pad2, which are label fields before 
 # this example begins
 def composedPanel := 
 JPanel`$explanation.Y     >              >
 $label                    $field         >
 $okButton                 $cancelButton  $pad1.X
 V                         $pad2          $logo`

In this layout, the explanation (presumably a textArea) is at the top of the composedPanel, with the label and field left-to-right underneath, and the okButton to the left of the cancelButton/logo area arranged top-to-bottom. This is a layout for a 3-wide, 4-high grid of cells, though some the panes fill multiple cells, and the rules for which cells grow are sophisticated, as described next:

The ".Y" says that the explanation should soak up any extra vertical space. The ".X" says the field should soak up any extra horizontal space. The two ">" symbols say that the explanation should span all three of the columns of this pane. The field fills two horizontal cells as denoted by the ">" which follows it. The "V" in the lower lefthand corner says that the okButton should fill two vertical cells.

When this pane is part of a resizable window, enlarging vertically makes the explanation larger. Enlarging the window horizontally enlarges the field but not the label. Both the cancel button and the okButton should remain the same size regardless of resizing since the extra space is being soaked up elsewhere.

If several elements have ".Y", the extra vertical space is divided evenly among them; similarly fields with ".X" share extra horizontal space.

The space characters used to separate the elements of this layout have no meaning to the quasi-parser; we have used the space to create a visual representation of the layout that makes it easy to see the layout even though this is just code.

It is not possible to lay out all possible compositions with a single JPanel, but JPanels can dramatically reduce the nesting of panels compared to Java applications, while making the layout visually clear in the code itself. And of course, you can always place JPanel-laid-out panels inside of other JPanel layouts. The result is tremendously more compact, easier to understand, and easier to maintain than the result of nesting large numbers of Swing Box layouts.

A similar quasi-parser, the swtGrid, is included for layout of SWT panels. The main difference, as shown in later example code, is that the swtGrid requires a first entry that is the parent panel for the laid out components improve this discussion

Library Packages: emakers

The E library package system is based on emakers. An emaker is an E source file named with ".emaker" as the suffix.

When an emaker is imported into an application, the code is executed at the time of import, and the result of that execution is returned to the importing program.


 # E sample
 def makeQueue() {
     var head := null
     var tail := null
     def makeCarrier(obj) :near {
         var next := null
         def carrier {
             to attach(nextCarrier) {next := nextCarrier}
             to get() {return obj}
             to next() {return next}
         }
     }
     def queue {
         to push(obj) {
             if (head == null) {
                 head := makeCarrier(obj)
                 tail := head
             } else {
                 tail.attach(makeCarrier(obj))
                 tail := tail.next()
             }
         }
         to pop() {
             def current := head
             head := head.next()
             return current.get()
         }
         to iterate(func) {
             var current := head
             var i := 0
             while (current != null) {
                 func(i, current.get())
                 current := current.next()
                 i += 1
             }
         }
     }
     return queue
 }

Side Note: ''This queue does have one interesting characteristic: the iterate method is the feature required to work correctly with E's for-loop. Iterate receives a function that expects 2 arguments: a key and an object. In this queue, the key value is filled with the index of the value in the queue. Iterate walks the entire data structure, invoking the function once for each element.

Place this queuemaker in a file named makeQueue.emaker, and put the file in the classpath, either with the -cp command line argument to Java, or by placing the file in a subdirectory under lib/ext in the java directory system. You can use Java-style package specifications: as in Java, you can put the file in a jar in lib/ext. In the below example, we place the file under lib/ext/emakers/com/yourdomain/e/queueMaker.emaker (in your jre directory), and import:


 # E syntax
 def makeQueue := <import:com.yourdomain.e.makeQueue>
 def queue := makeQueue()
 queue.push(1)
 queue.push(2)
 for each in queue {println(each)}

There are several ways of making E aware of the availability of an emaker, corresponding to the several ways Java can become aware of a class. You can place it in a zip or a jar and place it in the jvm's ext directory. Or you can place it in a subfolder in the jvm's ext directory. Or you can place it, or a jar that contains it, on the classpath when you start up the jvm.

Emakers have an important security property: they come to life contained in a world with no authority. Such a world is even more restrictive than the Java sandbox used for applets. However, this world is more flexible than the sandbox because authority can be granted and revoked during operation using capabilities, as described in the chapter on Secure Distributed Computing.

The makeQueue function example is a nice first example of emakers in action because makeQueue and the queues it makes need no authority. For emakers that require authority, by convention we use the Authorizer pattern. Here is an infoWindowMakerAuthor: the infoWindowMaker needs the authority to create windows, so we wrap it in an Authorizer:


 # E syntax
 #emaker in file lib/ext/com/skyhunter/infoWindowMakerAuthor.emaker
 def infoWindowMakerAuthor(frameMaker) {
     def infoWindowMaker(infoText) {
         def frame := frameMaker("Information")
         def label := <swing:makeJLabel>(infoText)
         frame.getContentPane().add(label)
         frame.pack()
         frame.show()
         return frame
     }
     return infoWindowMaker
 }
 #.....in using program....
 def makeInfoWindow := <import:com.skyhunter.infoWindowMakerAuthor> (<swing:makeJFrame>)
 def infoBox := makeInfoWindow("First Bit Of Info")
 def detailedInfoBox := makeInfoWindow("Second Bit Of Info")

By convention, authors follow the pattern of functions, using an implied run() method to return the Maker that is being wrapped.

The meticulous reader may have noticed that the JFrame was a capability that needed to be authorized, whereas the JLabel was not. The vast bulk of the Java API is non-capability-transferring, and can just be acquired using import:. Commonly-used exceptions are the JFrame, everything have to do with files in java.io, and the URL object in java.net. For a complete listing of suppressed methods (which are inaccessible in E though documented in Java), safe classes (which can be imported directly by emakers), and unsafe classes (which can only be imported using the unsafe__uriGetter, which is not directly available to emakers), see the JavaDoc for E.

Emakers can also just be obsolete functions, in which case the naming convention uses "Func" to distinguish it from a Maker:


 # E syntax
 #emaker in file lib/ext/org/erights/computeSquareFunc.emaker
 def computeSquareFunc(number) {
     return number * number
 }
 
 #...in using program...
 def computeSquare := <import:org.erights.computeSquareFunc>
 def squareOfThree := computeSquare(3)

There are also functions that require capabilities before they can become operational, in which case they are by convention wrapped in Authorizers, for example, analyzeOutlineFuncAuthor.

The good news is that, because emakers come to life without authority, they can always be imported with import:, so any emaker can bring in any other emaker (though you won't be able to run the authorizer without sufficient authority). The bad news is that, if you are writing standalone E applications in which the emakers are fully trustworthy (or at least as trustworthy as the program that calls them), it can seem a substantial nuisance at first to be granting lists of authorities just to break your program into packages. If you are writing pure E applications that use emakers of your own construction, emakers which you trust totally with the full authority of the system, and you have no qualms about flouting the wisdom of architectural purists around the world, you can take a shortcut by simply granting the unsafe__uriGetter. For example:


 # E sample
 def powerfulObjectMakerAuthor(unsafe__uriGetter) {
     def file := <unsafe:java.io.File>("name")
     def swing__uriGetter := <unsafe:javax.swing.*>
     def frame := <swing:makeJFrame>("powerful object window title")
     def powerfulObjectMaker() {
         #....define the objectMaker and the object it makes...
     }
     return powerfulObjectMaker()
 }

Note that in this example, one of the things we created from our unsafe__uriGetter was our own swing__uriGetter. Emakers, when they come to life, do have a swing__uriGetter of their own; however, their built-in swing: accesses only the safe subset of swing, much as import: accesses only the safe subset of unsafe:. In the example we create our own swing: that overrides the default swing:, which enables us access unsafe classes such as the JFrame.

For even more information on the security properties of emakers, see the chapter on Secure Mobile Code.

Ordinary Computing Examples

Pretty E

Racetrack Game for a single computer

Below is a simple game of racetrack: 3 cars are set on the track, to race between walls around curves to the finish line. Each driver can choose to accelerate or decelerate his car by +/- 1 space/turn during each turn. Do not build up too much velocity, you won't be able to slow down!

The example has just about everything in it: JPanels, objects, functions, Java API calls, it's all there. We will come back to this example later in the book, to make the track distributed and secure. Then we shall invite Satan for a little competition, with souls on the line.


 # E sample
  
 #!/usr/bin/env rune
 
 # Copyright 2002 Combex, Inc. under the terms of the MIT X license
 # found at http://www.opensource.org/licenses/mit-license.html
 pragma.syntax("0.9")
 
 def traceln(text) { stderr.println(text) }
 
 def attachAction(component,target,verb) {
     def listener {
         to actionPerformed(event) {
             E.call(target, verb, [])
         }
     }
     component.addActionListener(listener)
 }
 
 def newButton(labelText, verb, target) {
     def button := <swing:makeJButton>(labelText)
     button.setBackground(<awt:makeSystemColor>.getControl())
     attachAction(button,target,verb)
     return button
 }
 
 def abs(number) {return if (number >= 0) {number} else {-number}}
 
 def makeCoord(x,y) {
     def coord {
         to getX() {return x}
         to getY() {return y}
         to printOn(writer) {writer.print(`coord: $x,$y`)}
         to samePlace(coord2) :boolean {
             return x == coord2.getX() &&  y == coord2.getY()
         }
 
         /**
          * The "add" method is the underlying function for the "+" operator.
          * Here, by writing an "add" method, we make coordinates work with "+"
          */
         to add(coord2) {return makeCoord(x + coord2.getX(),y + coord2.getY())}
 
         /**
          * The "subtract" method is the underlying function for the "-" operator
          */
         to subtract(coord2) {return makeCoord(x - coord2.getX(),y - coord2.getY())}
     }
     return coord
 }
 
 def makeInstrumentPanel(car) :near {
     def makeIndicator(speed,positiveText,negativeText):pbc {
         var answer := ""
         var direction := positiveText
         if (speed < 0) {direction := negativeText}
         for i in 1..abs(speed) {answer := answer + direction}
         if (speed == 0) {answer := "0"}
         return answer
     }
     def makeXIndicator(speed) {return makeIndicator(speed,">","<")} 
     def makeYIndicator(speed) {return makeIndicator(speed,"^\n","V\n")} 
     def frame := <swing:makeJFrame>(`Car ${car.getName()} Instrument Panel`)
     def lbl(text) {return <swing:makeJLabel>(text)} 
     def xLabel := lbl("Horizontal Speed:") 
     def xIndicator := <swing:makeJTextArea>() 
     xIndicator.setText("0") 
     def yLabel := <swing:makeJTextArea>("V \ne\nr\nt\ni\nc\na\nl") 
     yLabel.setBackground(<awt:makeSystemColor>.getControl()) 
     def yIndicator := <swing:makeJTextArea>() 
     yIndicator.setText("0") 
     def statusPane := lbl("Running...") 
     def instrumentPanel 
     def btn(name,action) {return newButton(name,action,instrumentPanel)} 
     def submitButton := btn("Submit","submit") 
     var acceleration := makeCoord(0,0) 
     def realPane :=JPanel`
         ${lbl("")}  $xLabel     >                      >                  > 
         V           $xIndicator >                      >                  > 
         $yLabel.Y   $yIndicator ${btn("\\","upLeft")}  ${btn("^","up")}   ${btn("/","upRight")} 
         V           V           ${btn("<","left")}     ${btn("0","zero")} ${btn(">","right")}
         V           V           ${btn("/","downLeft")} ${btn("V","down")} ${btn("\\","downRight")}
         V           V           $submitButton.X        >                  >
         $statusPane >           >                      >                  >`
     frame.setDefaultCloseOperation(<swing:makeWindowConstants>.getDO_NOTHING_ON_CLOSE())
     frame.getContentPane().add(realPane)
     frame.pack()
     frame.show()
     bind instrumentPanel {
         to submit() {
             submitButton.setEnabled(false)
             car.accelerate(acceleration)
         }
         to prepareForNextTurn() {
             xIndicator.setText(makeXIndicator(car.getVelocity().getX()))
             yIndicator.setText(makeYIndicator(-(car.getVelocity().getY())))
             acceleration := makeCoord(0,0)
             submitButton.setEnabled(true)
             # Note, public static transferFocus on awt Component is not Java API, added in E environment
             <awt:makeComponent>.transferFocus([frame.getContentPane()], statusPane)
         }
         to setStatus(status) {statusPane.setText(status)}
         to upLeft() {acceleration := makeCoord(-1,-1)}
         to up() {acceleration := makeCoord(0,-1)}
         to upRight() {acceleration := makeCoord(1,-1)}
         to left() {acceleration := makeCoord(-1,0)}
         to zero() {acceleration := makeCoord(0,0)}
         to right() {acceleration := makeCoord(1,0)}
         to downLeft() {acceleration := makeCoord(-1,1)}
         to down() {acceleration := makeCoord(0,1)}
         to downRight() {acceleration := makeCoord(1,1)}
     }
 }
 
 def makeCar(name,startLocation,raceMap)  {
     var location := startLocation
     var acceleration := makeCoord(0,0)
     var velocity := makeCoord(0,0)
     var hasCrashed := false
     var hasFinished := false
     def instrumentPanel
     def sign(x) {
         return if (x > 0) {
             1
         } else if (x < 0) {
             -1
         } else {0}
     }
     
     def accelReactors := [].asMap().diverge()
 
     /**
      * Compute the path the car will take from the location at the
      * beginning of this turn to the end; return the result
      * as a list of coords
      */
     def computeIntermediateLocations(start,finish)  {
         def locations := [].diverge()
         def slope := (finish.getY() - start.getY()) / (finish.getX() - start.getX())
         def computeRemainingLocations(current) {
             var nextX := current.getX()
             var nextY := current.getY()
             var distToGo := 0
             #if the car is traveling faster in the x direction than
             #in the y direction, increment x position by one along
             #the path and compute the new y
             if (slope < 1.0 && slope > -1.0) {
                 distToGo := finish.getX() - current.getX()
                 nextX += sign(distToGo)
                 def distTraveled := nextX - start.getX()
                 nextY := start.getY() + ((slope * distTraveled) + 0.5) //1
                 #if the car is traveling faster in the y direction than
                 #in the x direction, increment y position by one along
                 #the path and compute new x
             } else {
                 distToGo := finish.getY() - current.getY()
                 nextY += sign(distToGo)
                 def distTraveled := nextY - start.getY()
                 nextX := start.getX() + ((distTraveled/slope) + 0.5) //1
             }
             def next := makeCoord(nextX,nextY)
             locations.push(next)
             if (!(next.samePlace(finish))) {
                 computeRemainingLocations(next)
             }
         }
         computeRemainingLocations(start)
         return locations
     }
     def car {
         to accelerate(accel) {
             traceln(`accelerating car $name`)
             acceleration := accel
             for each in accelReactors {
                 each.reactToAccel(car)
             }
         }
         to move(){
             traceln("into move")
             velocity += acceleration
             def newLocation := location + velocity
             traceln("got newlocation")
             def path := computeIntermediateLocations(location,newLocation)
             location := newLocation
             traceln("assigned  location")
             hasCrashed := hasCrashed || raceMap.causesCrash(path)
             hasFinished := hasFinished || raceMap.causesFinish(path)
             traceln("got crash finish")
             if (hasCrashed) {
                 instrumentPanel.setStatus("Crashed")
             } else if (hasFinished) {instrumentPanel.setStatus("Finished")}
             traceln("out of move")
         }
         to getLocation() {return location}
         to getVelocity() {return velocity}
         to hasCrashed() {return hasCrashed}
         to hasFinished() {return hasFinished}
         to getName() {return name}
         to prepareForNextTurn() {instrumentPanel.prepareForNextTurn()}
         to addAccelReactor(reactor) {accelReactors[reactor] := reactor}
         to removeAccelReactor(reactor) {accelReactors.remove(reactor)}
     }
     bind instrumentPanel := makeInstrumentPanel(car)
     return car
 }
 
 def makeTrackViewer(initialTextMap)  {
     def frame := <swing:makeJFrame>("Track View")
     def mapPane := <swing:makeJTextArea>(initialTextMap)
     def statusPane := <swing:makeJLabel>(" ")
     def realPane :=
       JPanel`$mapPane.Y
              $statusPane`
     frame.getContentPane().add(realPane)
     def windowListener {
         to windowClosing(event) {
             interp.continueAtTop()
         }
         match [verb,args] {}
     }
     frame.addWindowListener(windowListener)
     frame.pack()
     frame.show()
     def trackViewer {
         to refresh(textMap) {mapPane.setText(textMap)}
         to showStatus(status) {statusPane.setText(status)}
     }
     return trackViewer
 }
 
 def makeRaceMap() {
     def baseMap := [
         "..........W...............",
         "..........W...........FFFF",
         "......W...WW..............",
         "......W....W..............",
         "......W....WWW............",
         "......W........W..........",
         "......W.....W.............",
         "......W.....W.............",
         "......W...................",
         "......W..................."]
 
     def isWall(coord) :boolean {return baseMap[coord.getY()] [coord.getX()] == 'W' }
     def isFinish(coord) :boolean {return baseMap[coord.getY()] [coord.getX()] == 'F'}
     def pointCrash(coord) :boolean {
         var result := false
         if (coord.getX() < 0 || coord.getY() < 0 ||
               coord.getX() >= baseMap[0].size() || coord.getY() >= baseMap.size()) {
             result := true
         } else if (isWall(coord)) {
             result := true
         }
         return result
     }
     def raceMap {
         to getAsTextWithCars(cars) {
             def embedCarsInLine(index,line) {
                 def inBounds(xLoc) :boolean {return xLoc >= 0 && xLoc < line.size()}
                 var result := line
                 for each in cars {
                     if (each.getLocation().getY() == index && 
                           inBounds(each.getLocation().getX())) {
                         def editable := result.diverge(char)
                         editable[each.getLocation().getX()] := (each.getName())[0]
                         result := editable.snapshot()
                     }
                 }
                 return result
             }
             var result := ""
             for i => each in baseMap {
                 result := result + embedCarsInLine(i,each) + "\n"
             }
             return result
         }
         to causesCrash(path) :boolean {
             var result := false
             for each in path {
                 if (pointCrash(each)) {
                     result := true
                     break()
                 }
             }
             return result
         }
         to causesFinish(path) :boolean {
             var result := false
             for each in path {
                 if (pointCrash(each)) {
                     break()
                 } else if (isFinish(each)) {
                     result := true
                     break()
                 }
             }
             return result
         }
     }
     return raceMap
 }
 
 /**
  * create the cars, place them in a flex map to be used as a set
  */
 def makeCars(raceMap) {
     def carList := [ 
         makeCar("1",makeCoord(1,9),raceMap),
         makeCar("2",makeCoord(2,9),raceMap),
         makeCar("3",makeCoord(3,9),raceMap)]
     def carSet := [].asMap().diverge()
     for each in carList {carSet[each] := each}
     return carSet
 }
 
 /**
  * @author [mailto:marcs@skyhunter.com Marc Stiegler]
  */
 def makeRaceTrack() {
     def raceMap := makeRaceMap()
     def cars := makeCars(raceMap)
     var carsReadyToMove  := [].asMap().diverge()
     def mapViewer := makeTrackViewer(raceMap.getAsTextWithCars(cars))
     def raceTrack {
         to reactToAccel(car) {
             traceln("racetrack reacting to accel")
             carsReadyToMove[car] := car
             if (carsReadyToMove.size() >= cars.size()) {
                 raceTrack.completeNextTurn()
             }
         }
         to completeNextTurn() {
             def winners := [].diverge()
             for each in cars {
                 each.move()
                 if (each.hasCrashed()) {
                     cars.removeKey(each)
                 } else if (each.hasFinished()) {
                     winners.push(each)
                 }
             }
             mapViewer.refresh(raceMap.getAsTextWithCars(cars) )
             if (winners.size() == 1) {
                 mapViewer.showStatus(`Car ${winners[0].getName()} has won!`)
             } else if (winners.size() > 1) {
                 mapViewer.showStatus("It's a tie!")
             } else if (cars.size() == 0) {
                 mapViewer.showStatus("Everyone's dead!")
             } else {raceTrack.prepareForNextTurn()}
         }
         to prepareForNextTurn() {
             traceln("into prepare for next turn")
             carsReadyToMove := [].asMap().diverge()
             for each in cars {
                 each.prepareForNextTurn()
             }
         }
     }
     for each in cars {each.addAccelReactor(raceTrack)}
     return raceTrack
 }
 
 makeRaceTrack()
 # In actual code, the following line would not be commented out
 # interp.blockAtTop()

@@ Line 1,603: / Line 1,603: @@
 </pre>
-==Distributed Computing==
-Multiple threads form the basis of conventional models of concurrent programming. Remarkably, human beings engage in concurrent distributed computing every day even though people are generally single threaded (there are exceptions: Walter Cronkite routinely listened to one broadcast with one ear, a different broadcast with the other, while simultaneously taking notes on another topic and speaking authoritatively to an audience of millions. But most people, including this author, live single-threaded lives).
-How do we simple creatures pull off the feat of distributed computing without multiple threads? Why do we not see groups of people, deadlocked in frozen tableau around the coffepot, one person holding the sugar waiting for milk, the other holding milk waiting for sugar?
-The answer is, we use a sophisticated computational mechanism known as a ''nonblocking promise''.
-Let us look at a conventional human distributed computation. Alice, the CEO of Evernet Computing, needs a new version of the budget including R&D numbers from the VP of Engineering, Bob. Alice calls Bob: "Could you get me those numbers?"
-Bob jots Alice's request on his to-do list. "Sure thing, Alice, I promise I'll get them for you after I solve this engineering problem."
-Bob has handed Alice a promise for the answer. He has ''not '' handed her the answer. But neither Bob nor Alice sits on their hands, blocked, waiting for the resolution.
-Rather, Bob continues to work his current problem. And Alice goes to Carol, the CFO: "Carol, when Bob gets those numbers, plug 'em into the spreadsheet and give me the new budget,okay?"
-Carol: "No problem." Carol writes Alice's request on her own to-do list, but does not put it either first or last in the list. Rather, she puts it in the conditional part of the list, to be done when the condition is met--in this case, when Bob fulfills his promise.
-Conceptually, Alice has handed to Carol a copy of Bob's promise for numbers, and Carol has handed to Alice a promise for a new integrated spreadsheet. Once again, no one waits around, blocked. Carol ambles down the hall for a contract negotiation, Alice goes back to preparing for the IPO.
-When Bob finishes his calculations, he signals that his promise has been fulfilled; when Carol receives the signal, she uses Bob's fulfilled promise to fulfill her own promise; when Carol fulfills her promise, Alice gets her spreadsheet. A sophisticated distributed computation has been completed so simply that no one realizes an advanced degree in computer science should have been required.
-In this simple example, we see why human beings never get trapped in the thread-based deadlock situations described endlessly in books on concurrent programming. People don't deadlock because they live in a concurrent world managed with a promise-based architecture. And so it is with <span class="e">''E''</span>.
-This chapter on distributed computing is the longest and most challenging part of the book. The Promise Architecture of <span class="e">''E''</span> is very different from the threads, synchronized methods, guarded objects, and RMI of Java. One might expect the Security chapter and its Capability paradigm to be equally new and challenging. But in fact, the implementation of security is embedded so deeply in E's infrastructure that much of the effort merely involves realizing the power inherent in constructs we have already learned. Security with <span class="e">''E''</span> is more a matter of architecture than of coding.
-Distributed computation, however, still requires gritty effort. We start simply, with the eventually operator.
-===Eventually Operator===
-All distributed computing in <span class="e">''E''</span> starts with the eventually operator, "<-":
-<pre>
- <nowiki># E syntax
- car <- moveTo(2,3)
- println("car will eventually move to 2,3. But not yet.")</nowiki>
-</pre>
-The first statement can be read as, "car, eventually, please moveTo(2,3)". As soon as this eventual send has been made to the car, the program immediately moves on to the next sequential statement. The program does not wait for the car to move. Indeed, as discussed further under Game Turns below, it is guaranteed that the following statement (println in this case) will execute before the car moves, even if the car is in fact running on the same computer as this code. The request to move the car has been entered on a to-do list (actually sent to the appropriate event queue, for those already familiar with event loops).
-Since the program does not wait around for the eventual send, an eventual send is very different from a traditional object-oriented method call (referred to here as an ''immediate call'' to distinguish it from an ''eventual send''<nowiki>; the statement "car.moveTo(2,3)" is an immediate call). In general, you do not know, and cannot know, exactly when the car will move; indeed, if the car is on a remote computer, and the communication link is lost, the car may never move at all (and creates a </nowiki>''broken promise'' that you can catch and process, described later).
-This brings us to the most interesting feature of an eventual send: just as you do not know when the operation will complete, you also do not know, and ''do not need to know'', which computer in your distributed system is executing the car's code. The car could be a local object running on the same machine with the program... or it could be on a computer a thousand miles away across the Internet. Regardless, <span class="e">''E''</span> keeps track of the car's Universal Resource Identifier (URI) and delivers the message for you. Moreover, if the car is indeed remote, <span class="e">''E''</span> sets up a secure communication link between the program and the car; and since the URI for the car includes an unguessable random string of characters, no one can send a message to the car or extract information from the car except someone who has explicitly and intentionally received a reference to it from someone who already has the reference. Thus a computation running on five computers scattered across five continents, all publicly accessible by the whole world of the Web, can be as secure as a computation running on a box locked in your basement.
-Another very interesting feature of the eventual send: because the program continues on to the next statement immediately, without waiting for the eventual send to finish, ''deadlock can never occur''.
-Finally, note that the eventual send invoked an ordinary object method ("moveTo(x,y)") in the car. The programmer who created the makeCar constructor defines the cars to have ordinary methods, with ordinary returns of values. He does not know and does not care whether objects that invoke those methods use calls or sends, and neither knows nor cares whether those invoking objects are local or remote.
-===Promises===
-When you make an eventual send to an object (referred to hereafter simply as a ''send'', which contrasts with a ''call'' to a local object that waits for the action to complete), even though the action may not occur for a long time, you immediately get back a promise for the result of the action:
-<pre>
- <nowiki># E syntax
- def carVow := makeCar <- ("Mercedes")
- carVow <- moveTo(2,3)</nowiki>
-</pre>
-In this example, we have sent the makeCar function the default "run" message. Eventually the carMaker will create the new car on the same computer where the carMaker resides; in the meantime, we get back a promise for the car.
-Once we've got a promise, pipelining comes into the picture: ''We can immediately start making eventual sends to the promise just as if it were indeed the car''. Enormous queues of operations can be shipped across the poor-latency comm network while waiting for the car to be created, confident that those operations will be executed as soon as possible.
-But don't try to make an immediate call on the promise. Don't try it even if the car maker (and therefore the car it creates) actually live on the same computer with the program. To make immediate calls on the promised object, you must set up an action to occur when the promise resolves, using a when-catch construct:
-<pre>
- <nowiki># E syntax
- def temperatureVow := carVow <- getEngineTemperature()
- when (temperatureVow) -> {
-     println(`The temperature of the car engine is: $temperatureVow`)
- } catch prob {
-     println(`Could not get engine temperature: $prob`)
- }
- println("execution of the when-catch waits for resolution of the promise,")
- println("but the program moves on immediately to these printlns")</nowiki>
-</pre>
-We can read the when-catch statement as, "when the promise for a temperature becomes done, and therefore the temperature is locally available, perform the main action block... but if something goes wrong, catch the problem in variable prob and perform the problem block". In this example, we have requested the engine temperature from the carVow. Eventually the carVow resolves to a car and receives the request for engine temperature; then eventually the temperatureVow resolves into an actual temperature. The when-catch construct waits for the temperature to resolve into an actual (integer) temperature, but only the when-catch construct waits (i.e., the when catch will execute later, out of order, when the promise resolves). The program itself does not wait: rather, it proceeds on, with methodical determination, to the next statement following the when-catch.
-Inside the when-catch statement, we say that the promise has been ''resolved''. A resolved promise is either ''fulfilled'' or ''broken''. If the promise is fulfilled, the main body of the when-catch is activated. If the promise is broken, the catch clause is activated.
-Notice that after ''temperatureVow'' resolves to ''temperature'', the when clause treats temperature as a local object. This is always safe to do when using vows. A ''vow'' is a reference that always resolves to a local object. In the example, variable names suffixed with "vow" remind us and warn others that this reference is a vow. We can reliably make eventual sends on the vow and immediate calls on what the vow resolves to, but we cannot reliably make immediate calls to the vow itself. A more detailed discussion of these types of warnings can be found in the Naming Conventions section later.
-Not all references can guarantee to resolve to a local object. A ''receiver'' is a reference that can resolve to a local or remote object. Since we cannot ascertain beforehand whether it is local or remote, we must treat it as a remote object, i.e., we must interact with it only using eventual sends. We can use either the suffix Rcvr on the variable name as a reminder, or we can use the rcvr guard when defining the variable as a reminder. If you use Rcvr as a suffix, you will be more reliably reminded not to use immediate calls, but it does produce long variable names.
-<pre>
- <nowiki># E syntax
- def car :rcvr := makeCarRcvr <- ("Mercedes")
- car <- moveTo(2,3)</nowiki>
-</pre>
-In this example, makeCarRcvr is a reference to a makeCar function that we have reason to believe may be remote, and therefore can only be spoken to reliably with eventual sends. We could name the vehicle a carRcvr, since it's a reference to a car local to the makeCar function, which therefore is also probably remote to us (if makeCar is remote, so is the car). Instead, we have chosen to use the rcvr guard to remind us to only use eventual sends when interacting with this car.
-<font color="#FF0000">Under the covers, the "done(value)" part of the when-catch is actually the definition of a function. You can make up your own names for "done", such as "finished". Indeed, if a single object uses more than one when-catch, each "done" function must have a distinct name, such as done1, done2, etc.</font>
-<font color="#FF0000">The function nature of the "done" element of the when-catch is useful for making when-catch create promises for you, as discussed later.</font>
-When-catch, like try-catch, has an optional ''finally'' clause that always executes:
-<pre>
- <nowiki># E syntax
- when (tempVow) -> {
-     #...use tempVow
- } catch prob {
-     #.... report problem
- } finally {
-     #....log event
- }</nowiki>
-</pre>
-===Multiway when-catch===
-If you need to resolve several references before making a computation, use a multiway when-catch, in which you specify several arguments in the structure:
-<pre>
- <nowiki># E syntax
- def maxTempVow := vehicleSpecsRcvr <- getMaxEngineTemperature(carType)
- def engineTempVow := carRcvr <- getEngineTemperature()
- when (engineTempVow,maxTempVow) -> {
-     if (engineTempVow > maxTempVow) {println("Car overheating!")}
- } catch e {println(`Lost car or vehicleSpecs: $e`)}</nowiki>
-</pre>
-In this when-catch, since all the arguments are vows, the corresponding parameters (engineTemp and maxTemp, to the right of the "->") are simply local objects (integers in this case). How do we know that these integers will be local, not remote, even though we retrieved them from Rcvrs? Because integers are passed by construction, as discussed next.
-===Pass By Construction and Pass By Proxy, References Far and Near===
-In the above example, the temperature is an integer and is guaranteed to resolve to a local integer object upon which you can make immediate calls, even if the car is remote. Transparent immutable objects, such as integers, floating point numbers, booleans, strings, and the <span class="e">''E''</span> data structures ConstLists and ConstMaps, are always ''passed by copy''(which is the most common form of ''pass by construction''), so you always get a local copy of the object on resolution if one of these is returned by a method call or send. This local copy can of course accept immediate calls.
-Mutable objects, like the car in this example, reside on the machine upon which they were constructed. Such an object is ''passed by proxy''. If such an object is on a different machine from the one on which your piece of the system is running, even when the promise resolves it will only resolve into a ''far reference'' (as opposed to a ''near reference'' for a local object). Far references accept eventual sends, but cannot accept immediate calls.
-So in general, if you created the car using an eventual send to a possibly remote object (a receiver), you would probably have to interact with the car using eventual sends forever, since only such sends are guaranteed to work with remote objects.
-<pre>
- <nowiki># E syntax
- def carRcvr := carMakerRcvr <- ("Mercedes")
- carRcvr <- moveTo(2,3)
- carRcvr <- moveTo(5,6)
- carRcvr <- moveTo(7,3)
- def fuelVow := carRcvr <- fuelRemaining()</nowiki>
-</pre>
-===Partial Ordering Of Sent Messages===
-The above example moves the carRcvr around repeatedly and then asks for the amount of fuel remaining. This displays another important property of eventual sends: if object A sends several messages via a single reference to object B, it is guaranteed that those messages will arrive and be processed in the order of sending. This is only a partial ordering, however. From B's point of view, there are no guarantees that the messages from A will not be interspersed with messages from C, D, etc. Also, from A's point of view, there are no guarantees that, if A sends messages to both B and C, the message to B will arrive before (or after) the message to C, regardless of the order in which A initiates the messages. Furthermore, if A happens to have 2 different references to B (such as 2 promises that both will eventually resolve to B), the guarantee only applies to messages being sent down one reference.
-Despite those uncertainties, however, in the example the partial ordering is sufficient to guarantee that fuelPromise will resolve to the quantity of fuel remaining after all three of the moveTo() operations have occurred. It also guarantees that those moveTo()s will have been performed in the specified sequence.
-On first introduction, it is hard to fully appreciate the relationship between partial ordering and when-catch delayed activation. Here is a more sophisticated example.
-<pre>
- <nowiki># E syntax
- def cars := [car1,car2,car3]
- for each in cars {
-     def nameVow := each <- getName()
-     def moveVow := each <- moveTo(3,4)
-     when (nameVow, moveVow) -> {
-         println(`Car $nameVow has arrived`)
-     } catch e {println("A car did not make it")}
- }
- println ("Cars have been told to move, but no print of any arrivals has yet occurred")
- </nowiki>
-</pre>
-In this example, getName and moveTo messages are sent to all the cars in the list in rapid-fire succession, never waiting for any answers to get back. The "Cars have been told to move" message at the bottom is guaranteed to print before any "has arrived" messages print. We cannot predict which of the 3 cars will arrive first, second, or third. It all depends on where they are running, how slow the connections are, how loaded the processors are. We cannot even predict which will receive the moveTo message first: though the program is guaranteed to fire off the message to car1 first, the processor upon which car1 executes might be several thousand miles away across the Internet, across a dozen bottlenecked routers. And car2 could be running on a computer two feet away, a short hop down an Ethernet connection. In that case car2 would probably be first to receive its message, and be first to actually arrive, and be the first to return its resolution so the arrival message could print--all three of those events being independent, and the first car to do one is not necessarily the first car to do the next.
-Meanwhile, it is guaranteed that each car will get the getName message before it gets the moveTo message. It is ''not'' guaranteed that the nameVow will resolve to an answer before the moveVow has resolved, so you must use a multi-vow when-catch to use the name inside the when body with confidence. And if the moveTo promise is broken, which activates the catch clause, we do not know the resolution of the name--it could have fulfilled before the moveTo promise broke, or the name promise could be waiting (and on the verge of being broken or fulfilled) as well. We could use the E isBroken() function described later if we wanted to try to print the name of the car in the catch clause in those situations where the name was fulfilled though the moveTo was broken.
-Also it is worth noting that the moveTo method, when used in an eventual send, returns a promise even though the moveTo method is of type "void" (i.e., "does not return a value"). This promise, if fulfilled, will always become the uninteresting value of null...but as shown in this example, sometimes it is valuable to know that fulfillment has occurred, or that fulfillment has failed, even if you do not care what the fulfilled value may be.
-Sometimes you want to ensure that car1 arrives before car2, and car2 before car3. In a simple problem you could use nested when-catches, described later. In this example, where you don't necessarily know how many cars there are, you would use the recursive when-while pattern or the sendValve utility, both described at the end of the chapter.
-===Naming conventions===
-In the examples up to this point we have been using a number of naming conventions. Here are some common conventions.
-'''car''' -- an object that you can treat as a near object, using immediate calls or eventual sends as you wish.
-'''carVow''' -- a car that will be near, available for immediate calls, once you resolve the vow inside a when-catch clause.
-'''carRcvr''' -- a car that must be treated as a remote object, spoken to only with eventual sends, never with immediate calls, because although it might sometimes be a near car, it can also be remote, and only eventual sends are safe. As noted earlier, another way of denoting that a car may be remote is to use the ":rcvr" guard.
-'''getCar(licensePlate)''' -- a function or a method that returns a local car (local to the object implementing getCar)
-'''getCarVow(licensePlate)''' -- a function or a method that returns a vow for a car, not the car itself. If you are calling this method on a local object, once you resolve the vow, the car is local.
-'''getCarRcvr (licensePlate)''' -- This method returns a car which the author of the method has reason to believe may be a remote car. Consequently, it is a warning that you should only interact with the returned object with eventual sends.
-'''getCarVow(licensePlateVow, titlePapersRcvr)''' -- this method explicitly names the parameters licensePlateVow and titlePapersRcvr. Whereas the suffixes Vow and Rcvr are ''warnings'' when used in a method or variable name (warnings to avoid the use of immediate calls), when used as parameter suffixes they are ''commitments''. In this example, the developer of the getCarVow method is making the commitment to users of the method that he will not make immediate calls on the licensePlate until he has resolved the plate in a when-catch block. And he is making the commitment that he will only interact with the titlePapers using eventual sends. In general, if at least one of the parameters for a method is either a Vow or a Rcvr, the method itself cannot return a near object: if the method must wait on eventual sends to gather the info to return an object, it cannot reasonably return the object immediately. No doubt, however, someone reading this will be the first person to invent a situation that breaks this general rule. We congratulate you in absentia.
-'''makeCar (name)''' -- a carMaker that is local, can be immediately called, and makes cars that can be immediately called.
-'''makeCarVow (name)''' -- an object maker like a carMaker, but which is dependent on construction that may only resolve eventually, so it can only send you a promise for the car.
-'''makeCarRcvr(name) '''-- a local carMaker that may make the car on a remote system, and therefore the cars should be treated as Rcvrs.
-'''carMakerRcvr(name)''' -- a carMaker that may itself be on a remote system, that should only be spoken to with eventual sends. Rather than having a very wordy term for remote Makers that make remote cars (which are local to the Maker), since such a Maker is almost always going to create cars that you must treat as Rcvrs, we use carMakerRcvr to also designate makers that we might be tempted to name "carRcvrMakerRcvr". This name, carMakerRcvr, is a first and only example you will see here of the more generalized naming convention used when constructors and authorizers and rcvrs are interrelated in a complex way. Rather than depending on a prefix that might refer to any chunk of the name, we stack up the descriptions as suffixes. Multiple levels of constructors and authorizers play an important role in achieving E's security goals, so while these complicated structures are uncommon in most of the code in a system, there are likely to be a few parts in a secure system where such naming conventions play a role.
-===Testing for Equality in a Distributed System===
-As noted above, you can send eventual messages to both promises and far references. So if you plan to treat the fulfilled object as a far reference, using only eventual sends, there is usually no reason to use a when-catch to wait for resolution. Just go ahead and start sending messages, uncaring of whether the promise has yet been fulfilled.
-There are four reasons to use a when-catch construct to resolve the promise for a far object.
-* To find out that the original request succeeded, or otherwise, to get the problem
-* To flush out all previous messages sent via a reference to an object before taking an action
-* To use the result as a key in a hash table (a promise cannot be used as a hash key)
-* To test for equality, i.e., to see whether the promised object is the same object that you received from another activity.
-Here is a test for equality:
-<pre>
- <nowiki># E syntax
- def polePositionCarRcvr := raceTrack <- getPolePositionCar()
- when (polePositionCarRcvr) -> {
-     if (polePositionCarRcvr == myCar) {
-         println("My car is in pole position")
-     }
- } catch prob {}</nowiki>
-</pre>
-Note that the catch clause is empty. Because remote references across a network are unreliable, you will usually want to handle the problem that triggered the catch clause. However, if you have many pending actions with a single remote object, all the catch clauses for all those actions will start up if the connection fails, so you may want to disregard most of the catch clauses and focus on handling the larger problem (loss of connection) in one place. Often in this situation you will want to set up a whenBroken message, described later.
-But in this example, there is no compelling special action to take if you can't find out whether your car is in pole position, so no action is taken.
-===Making your own Promises===
-If you write a function or method that must get values from a far object before returning an answer, your function should return a promise for the answer, and fulfill that answer later. You can create your own promises using Ref.promise() in <span class="e">''E''</span><nowiki>:</nowiki>
-<pre>
- <nowiki># E sample
- def calcMilesBeforeEmptyVow(carRcvr) {
-     def [milesBeforeEmptyPromise, milesBeforeEmptyResolver] := Ref.promise()
-     def fuelRemainingVow := carRcvr <- getFuelRemaining()
-     def mpgVow := carRcvr <- getEfficiency()
-     when (fuelRemainingVow, mpgVow) -> {
-         milesBeforeEmptyResolver.resolve(mpgVow * fuelRemainingVow)
-     } catch prob {
-         milesBeforeEmptyResolver.smash(`Car Lost: $prob`)
-     }
-     return milesBeforeEmptyPromise
- }
- #....Meanwhile, somewhere else in the program....
- def myCar {
-     to getFuelRemaining() {return 5}
-     to getEfficiency() {return 2}
- }
- def milesVow := calcMilesBeforeEmptyVow(myCar)
- when (milesVow) -> {
-     println(`miles before empty = $milesVow`)
- } catch e {println(`Error: $e`)}</nowiki>
-</pre>
-This example highlights several different features of promises. The basic idea of the example is that the function calcMilesBeforeEmptyVow(carRcvr) will eventually compute the number of miles the car can still travel before it is out of fuel; later in the program, when this computation is resolved, the program will print the value. However, before we can do the computation, we must first get both the fuelRemaining and the milesPerGallon values from the remote car.
-The promise and the resolver for that promise are created as a pair using Ref.promise(). They are "normal" variables in the sense that they can be passed as arguments, returned from methods as answers, and sent eventual messages. Resolvers truly are ordinary objects. There are 3 restrictions on the promises: they cannot accept immediate calls, they cannot be tested for equality, and they cannot be used as keys in hash tables.
-In this example, the function returns the milesBeforeEmptyPromise to the caller just as it would return any other kind of value. To cause the promise to resolve, the function calls the resolver (or sends to the resolver if the resolver may be remote to your program) with the "resolve(value)" method. To break the promise (which produces a problem that will cause the catch clause of a when-catch to execute), call the resolver with the "smash(problem)" method.
-It is possible to chain resolutions: you can resolve a promise by handing the resolver another promise (though if you hand the resolver the promise which it is intended to resolve, <span class="e">''E''</span> will detect the problem and automatically break the promise--a promise resolved to itself can never be fulfilled). If you resolve a promise with another promise, the original promise is not yet considered resolved, i.e., the when-catch body will not be activated by such a resolution. The when-catch body will only be activated when the entire promise chain is resolved, and there is an actual reference to an actual object available.
-===Letting When-Catch make a Promise For You===
-As noted in chapter 1 under the Secret Lives of Flow Control Structures, control structures return values. When used as described up to this point, the return value of the when--catch expression has been ignored. In fact, the when-catch expression returns a promise for the value that the done function will return. If the done function does not return a value, then it will always resolve to null. However, if the <font color="#FF0000">done(value) function</font> of the when-catch returns a value, the when-catch returns a promise that will be fulfilled by the last value in the executed clause. Rewriting the calcMilesBeforeEmptyVow using this feature, we get: <span class="warn">not right, not right, fix</span>
-<pre>
- <nowiki># E sample
- def calcMilesBeforeEmptyVow(carRcvr)  {
-     def fuelRemainingVow := carRcvr <- getFuelRemaining()
-     def mpgVow := carRcvr <- getEfficiency()
-     return when (fuelRemainingVow, mpgVow) -> {
-         mpgVow * fuelRemainingVow
-     } catch prob {
-         throw(`Car Lost: $prob`)
-     }
- }</nowiki>
-</pre>
-Here the when-catch creates the promise which is returned by the function, and resolution is automatic at the end of the when-catch execution. <font color="rgb(255, 0, 0)">What does the promise resolve to during a catch and/or a finally?</font>
-===Broken Promise Contagion===
-When chaining promises, what happens if one of the promises in the middle or the far end breaks? The problem that breaks the far promise is propagated down all the promises dependent on it. As a consequence, broken promises work their way through the system in a similar way to exceptions being caught in try/catch blocks.
-===State Transitions for References===
-Having worked our way through near, far, broken, and promised references, let us put all the transitions among these together in a single place. The following diagram shows all the kinds of references <span class="e">''E''</span> distinguishes between, and it shows the two possible transitions:
-<font color="rgb(255, 0, 0)"> [[Image:ref-mech-0.gif|state transition diagram]]</font>
-The 2 transitions are:
-* A promise may transition (resolve) into a resolved reference, which can be near or far or broken..
-* A far ref may transition to a broken ref.
-That is the complete collection of transitions.
-===Guards for distributed systems===
-Very early in the book, we presented a list of <span class="e">''E''</span> types, including any, integer, float64, etc. In that list were "rcvr", "vow", "pbc" and "near". "pbc" means that the type of the value is required to be "pass by construction". Transparent immutables are generally pbc, and can be passed through this type declaration. Strings, integers, floats, booleans, ConstMaps and ConstLists are all pbc. Objects that are pbc are copied when they are sent, so that even if the object originated on a remote computer, when you get it you can use immediate calls on it. Also, since pbc objects do not embody any code, pbc objects passed across a trust boundary can be used with far fewer security concerns: the pbc object may contain bad data, but it cannot play any tricky games in its execution.
-"Near" means that the value must be local. Promises and far references will not pass the near guard. Anything that passes a near guard can be sent messages with immediate calls.
-At this time, "rcvr" and "vow" have the same algorithmic meaning as "any", but can be used as hints to the programmer about how to interact with the object (a vow should be referenced only eventually until it is resolved; a rcvr should always be referenced only eventually).
-===Nested When-Catch constructs===
-As discussed earlier, we can guarantee the ordering of messages sent from one object to another object. But when a program sends messages to several objects, on different machines, the order in which answers will be received cannot be predicted. Suppose you need to perform a computation involving two far answers, and the algorithm depends on the result from the first answer. You can nest when-catch clauses to await the outcome of the dependency:
-<pre>
- <nowiki># E syntax
- def fileRcvr := fileCacheRcvr <- getFile()
- when (def exists := fileRcvr <- exists()) -> {
-     if (exists) {
-         when (def text := fileRcvr <- getText()) -> {
-             println(`File has text: $text`)
-         } catch p2 {println(`Problem with existing file: $p2`)}
-     } else {println("File does not exist")}
- } catch prob {println(`Problem reaching file: $prob`)}
-     </nowiki>
-</pre>
-Here, we want to print the text of a farFile, but we want to be sure the file exists first. So we ask the file if it exists, and only after we determine that it does indeed exist do we proceed to get the text.
-As noted earlier, <font color="#FF0000">the "done(variable)" clause </font>of the when-catch construct is actually the declaration of a function and a series of parameters. The reasons for this are beyond the scope of this book, but the operational consequence is that you must use different function names if you have multiple when-catch clauses in the same scope.
-Nested when-catch clauses put the "done" functions into the same scope. In the example here, we gave the inner when-catch "done" function the name "done2" to prevent name collision. We also gave the error-containing variables in the catch clauses different names, e and e2.
-===Live Refs, Sturdy Refs, and URIs===
-Up to this point we have carefully dodged a critical question. How does a program acquire its very first reference to an object on a different computer? In all our examples up to this point, we have always started out with a reference to at least one remote object, and we retrieved other remote objects by asking that object for other objects: for example, we asked a remote carMakerRcvr for a new (remote) carRcvr, and were able to immediately work with the car just like any other remote object. How did we get the reference to the carMakerRcvr in the first place?
-In <span class="e">''E''</span>, the reference to an object can be encoded as a Universal Resource Identifier string, known as a ''uri'' (the familiar url of the Web is a type of uri). This uri string can be passed around in many fashions; one good secure way of passing a uri is to save it as a text file, encrypt and sign it with PGP, and send it in email. If you wish to run a seriously secure distributed <span class="e">''E''</span> system, encrypting the uris is crucial: indeed, the passing of the uris from machine to machine is the main security issue that <span class="e">''E''</span> cannot address for you (and is a problem shared by all security systems, a problem that will diminish with time as secure systems like PGP email are deployed). Other ways uris have been passed in operational <span class="e">''E''</span> systems have been to send the uri over an ssh connection, and (less securely) by reading the uri off over a telephone! If you are using <span class="e">''E''</span> on a local area network and have no security concerns, but are using <span class="e">''E''</span> simply because it is simpler, safer, and more maintainable for distributed computing, the uris can be stored in files on a shared file system and read directly by the programs on different computers as they start up.
-The functions makeURI(object) and objFromURI(uri) detailed in the <span class="e">''E''</span> Quick Reference Card perform the basic transformations you need to hook up objects on multiple computers. These routines use sturdy refs and liverefs in their computations. A sturdyRef is an object that contains an enduring description of where an object can be found; sturdyRefs and URIs are simple transformations of one another. LiveRefs are actual connections to objects that disappear any time a connection goes down. LiveRefs carry the actual traffic in <span class="e">''E''</span> communication. When you request a remote object from another remote object (as in farCarMaker <- ("mercedes")), what you actually get is a liveRef. If you want to continue to connect with that particular car across multiple sessions, you will need to explicitly get a sturdyRef from the car (and the car will have to have an explicit method for granting the sturdyRef. The sturdyref function is an important capability, not one handed out by default).
-Each program that expects to work with remote objects needs to invoke the command
-<pre>
- <nowiki># E sample
- introducer.onTheAir() </nowiki>
-</pre>
-before starting any remote connections, including the making or using of uris. An example of these functions working together can be found in eChat.
-===blockAtTop and continueAtTop===
-E programs never block. They never just sit and wait around for results. However, most programs will toss out some windows, or set up some services, and then desire to wait for someone or some thing to use them. Often, the first version of a program written by a new <span class="e">''E''</span> programmer will set everything up, execute the last line of the program, and then shut down. It is quite disconcerting to watch your windows briefly light up and then disappear, along with the java virtual machine underlying the entire program.
-The command
-<pre>
- interp.blockAtTop()
-</pre>
-causes the <span class="e">''E''</span> interpreter to wait for requests to come in. The command
-<pre>
- interp.continueAtTop()
-</pre>
-causes the <span class="e">''E''</span> interpreter to stop waiting. These commands are used in the eChat sample at the end of this chapter: the last line of the program initiates blockAtTop, and continueAtTop is invoked when the user closes his chat window.
-===A bit of Philosophy when using Promises for the first time===
-If a method accepts a promise or far reference as a parameter, the returned value almost certainly cannot be a local object. Why is this? If the computation of the returned object depends on something eventual, the computation will have to wait for an answer, which means the best the object can do for immediately returning something is to return a promise. So a method like getCar(licensePlateVow) has almost certainly violated the naming convention, one way or the other.
-As a consequence of this and other characteristics of promises, beginning E programmers often experience a moment of breathlessness soon after they first try to use them. This moment occurs when the programmer erroneously concludes that, once you let a promise into your system, the program has tumbled down a slippery slope from which there is no recovery. It feels as if you will never be able to have a real value in your hands again; you'll spend the rest of your life making eventual sends, coupled with endless when-catch constructs just to get to the next step.
-The breathlessness can metastasize into a feeling of having lost control of the software: everything is off computing somewhere else and all you have is a bunch of promises. Since <span class="e">''E''</span> never (really, never!) blocks, you can never tell things, "just stop for a moment while I catch my breath and gather up all the values" :-)
-In fact, there are several patterns and tools for getting control of things again. The basic multi-promise when-catch, and the promiseAllResolved and Summoner patterns at the end of this chapter are just a few examples of structures specifically designed to reduce the frequency with which you need when-catch. They allow you to get quickly back into local computation after a distributed action. You really can catch your breath.
-And once the moment of breathlessness passes, you will feel freedom, for you will never have to deal with thread synchronization again; you will never lie awake at night wondering if an unexplored race condition will cause deadlock a few days after the production load level hits your system. <font color="#ff0000">How early can I put this paragraph easily? AHK proposes right after Promises.</font>
-===Additional Promise-Related Operations===
-* whenBroken
-* E isBroken
-* whenResolved Use this when your action will be the same once the promise resolves, regardless of whether it resolves broken or not.
-* E isResolved
-* E send(object,verb,arguments) This function is identical to the E call() function described earlier, but does an eventual send rather than an immediate call.
-* E sendOnly
-* E join(a,b) Guarantees sends to result of join are delivered only after messages to a and b have been delivered, sort of a test for equality on-the-fly
-===Under the Covers: Vats and Game Turns===
-<font color="#ff0000">Each vat has a separate event loop, each game turn corresponds to the processing of a single event to conclusion with no interruptions. There are frontend vats, which all share the swing event queue for queuing messages to their event loops, and there are backend queues, each of which has its own separate event queue and runs on a separate thread. Frontend vats have the advantage that they can interact directly with user interface widgets. The initial vat created by default at the start of an E program is a frontend vat. You might want multiple frontend vats if you want to shut down whole subsystems in one fell swoop: you can tell a vat to shut down, and it will terminate all its connections to the outside world, making it available for garbage collection. Have markm review this and tell me what is wrong with this description.</font>
-<font color="#ff0000">creating a second frontend vat on a single jvm. creating a backend vat on a jvm</font>
-===Example: Alice, Bob, and Carol as Code===
-We started this chapter with a description of a human interaction, with Alice as the CEO of Evernet Computing in search of a new spreadsheet for her IPO preparation. What would that distributed problem look like in code? Though we present only a skeleton of this human operation here, it is perhaps nonetheless informative. It might also be informative, after one has read how to do the example in <span class="e">''E''</span>, to think about how it would be done with threads, in Java or C++. That, however, is left as an exercise for the reader.
-<pre>
- <nowiki># E sample
- #---- Bob Code
- def bobRcvr {
-     to handleExplosionInNetworkServerRoom() {
-        # handle the explosion
-     }
-     to getCostNumbers() :pbc {
-         return ["R&D" => 10000]
-     }
- }
- #------------ Carol Code
- def carolRcvr {
-     to attendMeeting(room, time) {
-         # attend the meeting
-     }
-     to integrateSpreadsheetVow(RDNumbersVow) {
-         def sheetVow := when (RDNumbersVow) -> {
-             ["Marketing" => 50000] | RDNumbersVow
-         } catch prob {
-             println("No numbers!")
-             prob
-         }
-         return sheetVow
-     }
- }
- #--------- Alice Code
- def aliceRcvr {
-     to prepareIPOVow()  {
-         def RDNumbersVow := bobRcvr <- getCostNumbers()
-         def spreadsheet := carolRcvr <- integrateSpreadsheetVow(RDNumbersVow)
-         return when (spreadsheet) -> {
-             println(`Appendix: Budget Spreadsheet: $\n$spreadsheet`)
-         } catch prob {
-             aliceRcvr <- fireSomebody([bobRcvr, carolRcvr])
-         }
-         # do other IPO preparations
-     }
-     to fireSomebody(candidateRcvrs) {
-         # get rid of culprit
-     }
- }
- bobRcvr <- handleExplosionInNetworkServerRoom()
- carolRcvr <- attendMeeting(1,2)
- aliceRcvr <- prepareIPOVow()</nowiki>
-</pre>
-===Example: minChat version 1===
-In order to focus on the distributed computation features of this chat tool, we have gone to extreme lengths to make the user interface machinery a very short piece of code. Hence, this should properly be called "minChat", because the user interface is so brutally minimal. Even with such minimization, however, the user interface still requires more lines of code than the actual distributed computation!
-The chatController at the bottom of the example is the heart and soul of the computation.
-<pre>
- <nowiki>#?? in new vat minChatVat.e-swt</nowiki>
-</pre><pre>
- <nowiki>## E sample
- #!/usr/bin/env rune
- #eChat with minimalist user interface
- pragma.syntax("0.9")
- def <widget> := <swt:widgets.*>
- def SWT := <swt:SWT>
- introducer.onTheAir()
- # return the object represented by the URI
- def getObjectFromURI(uri)  {return introducer.sturdyFromURI(uri).getRcvr()}
- def makeURIFromObject(obj) :String {
-     # This implementation assumes a non-persistent single incarnation
-     def [sr, _, _] := identityMgr.makeKnown(obj)
-     </nowiki><font color="#FF0000"><nowiki>#XXX not a uri if bracketed, bug, markm?</nowiki></font><nowiki>
-     def bracketed := introducer.sturdyToURI(sr)
-     if (bracketed =~ `<@uri>`) {return uri}
-     return bracketed
- }
- def chatController
- def chatArea
- def chatUI {
-     to show() {
-         def frame := <widget:Shell>(currentDisplay)
-         frame.setText("eChat"); frame.setBounds(30, 30, 600, 300)
-         def winDisposeListener {to widgetDisposed(event) {interp.continueAtTop()}}
-         frame.addDisposeListener(winDisposeListener)
-         bind chatArea := <widget:Text>(frame,
-             (SWT.getMULTI() | SWT.getWRAP()) | (SWT.getBORDER() | SWT.getV_SCROLL()))
-         def commandLine := <widget:Text>(frame, SWT.getSINGLE() | SWT.getBORDER())
-         def enterKeyListener {
-             to keyPressed (event) {
-                 if (event.getKeyCode() == 27) {
-                     if (commandLine.getText() =~ `@command @argument`) {
-                         commandLine.setText("")
-                         switch (command) {
-                             match == "save" {chatController.save(<file: argument>)}
-                             match == "load" {chatController.load(<file: argument>)}
-                             match == "send" {chatController.send(argument)}
-                             match _ {commandLine.setText("Error. Try save load, or send")}
-                         }
-                     } else {commandLine.setText("Error. Try save, load, or send")}
-                 }
-             }
-             match [verb, args] {}
-         }
-         commandLine.addKeyListener(enterKeyListener)
-         def label := <widget:Label>(frame, SWT.getLEFT())
-         label.setText("save, load, send. No quotes for path. Use Escape to start operation. ")
-         swtGrid`$frame: $chatArea.X.Y
-                         $label.X
-                         $commandLine.X`
-         frame.open()
-     }
-     to showMessage(initiator, text) {chatArea.append(`$initiator: $text $\n`)}
- }
- def friend
- bind chatController {
-     to send(message) {
-         when (friend<-receive(message)) -> {
-             chatUI.showMessage("self", message)
-         } catch prob {chatUI.showMessage("system", "connection lost")}
-     }
-     to receive(message) {chatUI.showMessage("friend", message)}
-     to receiveFriend(friendRcvr) {
-         bind friend := friendRcvr
-         chatUI.showMessage("system", "friend has arrived")
-     }
-     to save(file) {file.setText(makeURIFromObject(chatController))}
-     to load(file) {
-         bind friend := getObjectFromURI(file.getText())
-         friend <- receiveFriend(chatController)
-     }
- }
- chatUI.show()
- # In actual code, the following line would not be commented out
- # interp.blockAtTop()</nowiki>
-</pre>
-There are only 5 methods in making chat happen: sending a message to the friend, receiving a message from the friend, being informed that the friend has found you (the ''receivedFriend ''method), saving the URI where your friend can find you, and loading the URI that describes where you can find your friend.
-A quick run through can be done by putting the source in a file (file extension ".e-swt", this example uses SWT for user interface) and launching the file twice to get 2 chat windows. In one window, type "save ~/me.minchat" and press the Escape key. This creates a file (in your home directory) that contains a cap: URI describing where your chat session can be found (a chat session that can only be found by someone to whom this file has been given--the location cannot be found or guessed by anyone else). In the other window, type "load ~/me.minchat" and press Escape. In the first window you should see a message pop up that the "friend has arrived". Now in either window type "send hi y'all", and you will see the message appear in both windows.
-In minChat , every time you start up the program, it comes to life with a new uri that must be sent to the friend with whom you wish to chat; the old uri from the previous session is useless. MinChat would be far more useful if you could create a minChat session with Bob, and continue that session even after you have rebooted your computer. We look at building such a persistent chat in the chapter on Persistent Secure Distributed Computing--after first looking at minChat here through the eyes of a security reviewer (or a cybercracker) in the chapter on Secure Distributed Computing.
-===Patterns of Promises===
-====resolveAllVow====
-Suppose you have a computation that cannot be performed until you have received answers from multiple remote objects. Your first thought would be to use a multi-vow when-catch. But further suppose you do not know beforehand how many vows there are (i.e., suppose you have an arbitrary list of promises). In this case neither the multi-vow when-catch construct nor the nested when-catch pattern will work. For this situation, you can use the resolveAllVow utility described here.
-The resolveAllVow utility has another distinction compared to a multi-vow when-catch: whereas the multi-vow activates the catch clause as soon as it hits a broken promise, resolveAllVow sends no resolution until everything in the list is resolved one way or the other. So, even if several of the promises were broken, with resolveAllVow you can be sure that the rest have been fulfilled when the catch clause is activated.
-In this example, we use resolveAllVow to sum a list of contributions. We do not know beforehand how many contributions there are (perhaps thousands), and we want to sum them up even if some of the requests for donations return broken promises.
-E isBroken(obj) does not work. what does?
-<pre>
- <nowiki># E sample
- # Given a List of promises, when all the promises have been resolved,
- # resolve the returned vow, either fulfilling it with the list of fulfillments (if
- # all the promises were fulfilled) or by smashing the returned promise
- # with one of the broken promises (if at least one promise was broken).
- def resolveAllVow(promises) {
-     def [resultVow, resolver] := Ref.promise()
-     var count := promises.size()
-     var resolution := promises
-     var noneBroken := true
-     if (count == 0) {resolver.resolve(promises)}
-     for promise in promises {
-         when (promise) -> {
-             # success processed in finally clause
-         } catch prob {
-             resolution := prob
-             noneBroken := false
-         } finally {
-             count -= 1
-             if (count == 0) {
-                 if (noneBroken) {
-                     resolver.resolve(resolution)
-                 } else {resolver.smash(resolution)}
-             }
-         }
-     }
-     return resultVow
- }
- #now use the promiseAllResolved to sum contributions, where the
- #number of contributions is unknown prior to execution
- def printTotalContributions(amountsList) {
-     var total := 0
-     for each in amountsList {
-         if (!(Ref.isBroken(each))) {total += each}
-     }
-     println(`Total contributions are: $total`)
- }
- # scaffold contributors: real contributors would be remote Rcvrs
- def makeContributer(donation) {
-     return def contributor { to getDonation() :int {return donation} }
- }
- def contributorRcvrsList := [makeContributer(5), makeContributer(6)]
- def amountsVows := [].diverge()
- for each in contributorRcvrsList {
-     amountsVows.push(each <- getDonation())
- }
- when (def amounts := resolveAllVow(amountsVows)) -> {
-     printTotalContributions(amounts)
- } catch prob {
-     #due to the nature of resolveAllVows, in this catch clause
-     #we are guaranteed everything in amountsVows is resolved to
-     #either an amount or a broken reference
-     printTotalContributions(amountsVows)
- }</nowiki>
-</pre>
-The basic behavior of resolveAllVow is this: when initiated, the function takes a count of how many promises there are, then immediately spins off when-catches for all of them. Each time a promise resolves, the count of outstanding promises is decremented. When the counter drops to zero, implying all the promises have been resolved, the single promise initially returned by resolveAllVow is finally resolved.
-====dialogVowMaker====
-Java's standard dialog boxes, found in JOptionPane, are seriously flawed for use in a distributed <span class="e">''E''</span> system: those convenience dialogs are fully blocking. As a consequence, if your computer is part of a distributed computation, and you go home for the night, if a Java dialog box pops up, your machine is effectively offline until you return in the morning. Included in the <span class="e">''E''</span> distribution is a dialog box tool, the dialogVowMaker:
-<font color="#ff0000">code here</font>
-====Recursion for send sequencing====
-As discussed earlier, putting a when-catch inside a for loop does not give you any guarantees on which when-catch will activate first: it only guarantees which message is sent first, which is mostly uninteresting. For general-purpose ensured sequencing of resolution, you must use recursion.
-Earlier, we had an example in which we told a list of cars to moveTo the same location. Suppose we wished to ensure that the cars arrived in the order in which they appear in the list:
-<pre>
- <nowiki># E sample
- def moveAllCarsInSequence(carRcvrs,toX,toY) {
-     var carI := 0
-     def moveRemainingCars() {
-         if (carI < carRcvrs.size()) {
-             def nextCarRcvr := carRcvrs[carI]
-             carI += 1
-             def nameVow := nextCarRcvr <- getName()
-             when (nameVow,nextCarRcvr <- moveTo(toX,toY)) -> {
-                 println(nameVow + " arrived, next car about to start moving")
-             } catch e {
-                 println(`car died: $e`)
-             } finally {moveRemainingCars()}
-         }
-     }
-     moveRemainingCars()
- }
- # scaffold carmaker
- def makeCarRcvr(name) {
-     def carRcvr {
-         to getName() :String {return name}
-         to moveTo(x, y) {
-             #move the car
-         }
-     }
-     return carRcvr
- }
- moveAllCarsInSequence([makeCarRcvr("car1"),makeCarRcvr("car2")],3,4) </nowiki>
-</pre>
-Inside the moveAllCarsInSequence function, we declare the recursive moveRemainingCars function, then simply invoke moveRemainingCars. The function moveRemainingCars tells the next car to move; once that movement has resolved, moveRemainingCars invokes itself once again.
-In this version of moveAllCarsInSequence, if a car is lost (i.e., its promise to move is broken), the recursion continues. If we wanted to abort after a problem occurred, we would simply delete the call to moveRemainingCars() from the finally clause, and place it in the when clause.
-====sendValve====
-As we have seen, it is possible to spin off large numbers of eventual sends in the blink of an eye. In fact, tossing off vast numbers of such sends can sometimes consume a lot of resources for no good purpose. In the eDesk program at the end of the book, it is possible for the user to request the transfer of whole directories full of files. It would be possible for eDesk to initiate transfer of all of those files simultaneously. But the processing bottleneck is probably bandwidth, so initiating them all at once won't get the whole transfer done any faster, and meanwhile each individual file transfer consumes buffer space once initiated. Starting all the transfers at once could actually slow down the transfer if enough buffers thrash virtual memory.
-What you want is a ''valve'', which can be opened and closed depending on the situation. The program can still set up all the operations in a single swoop, but the valve will constrain the number of such operations that are actually active at a given moment. The sendValve below performs this function.
-<pre>
- <nowiki>#sendValve. If you have numerous eventual sends to initiate,
- # but initiating them all at once would consume vast resources
- # and/or would actually slow down processing, queue the actions
- # through a valve.
- #An ActionTrio is the list of [obj,"verb",[arguments]]
- # that can be used in an E send()
- #The actions are guaranteed to be initiated in the sequence in
- # which they are placed in the valve, though of course there is
- # no guarantee as to which will terminate first (unless you have
- # special knowledge of such sequencing outside the valve).
- #The numSimultaneousAllowed is the number of actions that can
- #  be run concurrently through this valve.
- # E sample
- def makeSendValve (numSimultaneousAllowed) {
-     var actionQueue := []
-     var numRunning := 0
-     def startNext() {
-         if (!(actionQueue.size()==0)) {
-             def [actionTrio, resolver] := actionQueue[0]
-             actionQueue := actionQueue(1, actionQueue.size())
-             numRunning += 1
-             def completeVow := E.send(actionTrio[0],actionTrio[1],actionTrio[2])
-             resolver.resolve(completeVow)
-             when (completeVow) -> {
-             } catch prob {
-             } finally {
-                 numRunning -= 1
-                 startNext()
-             }
-         }
-     }
-     def  valve {
-         to makeActionVow(actionTrio) {
-             def [completeVow, resolver] := Ref.promise()
-             actionQueue := actionQueue.with([actionTrio, resolver])
-             if (numRunning < numSimultaneousAllowed) {
-                 startNext()
-             }
-             return completeVow
-         }
-     }
-     return valve
- }</nowiki>
-</pre>
-The sendValve utility, if used with numSimultaneousAllowed==1, can also perform the send sequencing function described earlier. However, the earlier general send sequencing pattern is still useful. For example, if the moveAllCarsInSequence operation should abort upon a encountering a broken resolution, this version of sendValve would not give the correct result.
-====Summoning====
-====Transparent forwarder====
-It is possible to have a network of machines in which the machines do not all have direct access to one another. Suppose in the network with machine A, B, and C, A and C cannot form a direct connection because of network topology, but B can reach everything. If A needs a capability on C, we can put a transparent forwarder on B such that A sends its messages to the forwarder on B:
-<pre>
- <nowiki># E sample
- def makeTransparentForwarder(representedRcvr) {
-     def forwarder {
-         match [verb,args] {E.send(representedRcvr,verb,args)}
-     }
-     return forwarder
- }</nowiki>
-</pre>
-Create the forwarder on B, and hand the reference to the forwarder to the appropriate object on A. An example can be found in the eDesk example at the end of the book, in which a forwarder is used if the system detects that two of the file servers are unable to directly connect. Note that the "delegate" keyword does not quite work here: delegate generates immediate calls, not eventual sends. So we had to revert to the more general purpose matching process.
-====acceptOnlyMoreRecentVow====
-Suppose you are periodically requesting a particular piece of information from a far object. Suppose the far object cannot supply the answer in a single game turn, i.e., it must ask other objects for information to get the answer, and so it sends you a promise rather than a result. It is possible for the resolutions of these promises to occur out-of-order, i.e., the resolution on the second request could get to you after the resolution of the third request has already occurred. In this situation, it will appear that the answer to the second request is newer and more up-to-date than the third request.
-<font color="#000000">In this situation, to ensure you are getting only new information, not stale information, use the acceptOnlyMoreRecentVow utility.</font>
-<pre>
- def acceptOnlyMoreRecentVow
-</pre>
-<font color="#ff0000">code here</font>
-This situation, while rare, actually arises in the Marketplace example in the Secure Distributed Computing chapter.
-<font color="#ff0000">something about time, the race construct, timeout construct</font>
-====eDesk overwrite copy jewel====
-The following is not really a pattern so much as it is an example of all the more novel (i.e., not-like-Java) elements of <span class="e">''E''</span> playing together. The problem, taken from the eDesk program in the Examples at the end of the book, is this:
-example
-===Data Lock===
-Though <span class="e">''E''</span> is safe from deadlock, in which several objects compete for acquisition to a set of resources, there is a related dilemma that <span class="e">''E''</span> programs can encounter. If two or more "when" clauses wait for each other to resolve before they can resolve themselves, this causes ''data lock''. A complete discussion of data lock and why it is far less of a risk than deadlock is beyond the scope of this book. Briefly, both theory and current experience suggest that data locks are more difficult to create in the wild than deadlocks. Furthermore, when datalocks do occur, they are less likely to freeze up important subsystems on a grand scale: unlike the deadlock, they only choke a few "when" clauses, not a set of "critical sections" which have been named "critical" in thread programming for good reasons. And lastly, datalocks are consistent, reproducible, and therefore fixable, unlike the deadlocks that appear mysteriously when some incredibly arcane race condition occurs.
-Here is a simple though foolish example of datalock. It is the E implementation of the English sentence, "This sentence is false."
-<pre>
- def sentence := sentence <- not()
-</pre>
-In this construction, the sentence will forever be an unresolved promise. As noted above, the failure of this to resolve will not impede the progress of the rest of the program in the least. And it is very reliable: the unresolvability of the promise will appear the first time you run the program, and the second, and in every debugging pass thereafter.
-At the time of this writing, data lock has been seen only once in the wild. In that instance, a widely used object (call it WUO),contained one piece of mutable state and one piece of immutable state. The object that computed new versions of WUO's mutable state needed the immutable part of the state, and requested the current version of WUO from the owner of the object. Unfortunately, the owner knew that a new version was under construction, and was only sending out promises for WUO until the update was resolved. The solution in this case was to refactor WUO. This resulted in an architecture that was cleaner even by normal object design criteria, without regard to the distributed usage behavior. Insufficient data is yet available to assess how commonly this type of solution will suffice.