by Marc Stiegler
Copyright (C) 2000, Marc Stiegler. All Rights Reserved.
Table of Contents
Java, Perl, Python, C++, TCL, and on and on. Don't we have enough languages already? How could we justify bringing yet another programming language into the world?
In fact, there is still a compelling reason for developing better programming languages: we keep on writing more complicated programs. And worse, we keep on writing more complicated systems of interdependent programs.
We have entered the age of globally distributed computing with a vengeance. Anyone who has cobbled together a major system with a hodgepodge of Web servers, Java, JSP, SQL, CGI, CORBA, RMI, XML, and Perl knows that this cannot be the toolset we will use in 20 years. The sooner we move up to the tools of 20 years hence, the better off we will be. Into this situation we introduce E:
These qualities cannot be achieved with traditional security approaches. Do not expect the next release of Java, Windows, or Linux to fix the problem: the flaws in these systems lie at the heart of their architectures, unfixable without breaking upward compatibility, as we shall discuss in the chapter on Secure Distributed Programming. Of course, there is nothing to prevent people from advertising that they are releasing a new, upward compatible, totally-secure version of a product. Just don't jump off the Brooklyn Bridge to buy it.
E wraps these strengths in a C/Java syntax to make it quickly comfortable for a large number of software engineers. It is built with objects at the core of its design, making it easy to write modular, readable, maintainable software using the strategies familiar from Java. It has the kind of powerful string handling that will be recognized and seized upon by the Perl programmer. For both better and for worse, E is a dynamically typed language like Smalltalk, not a statically typed language like Java. Users of Perl and Python will immediately assert this is an advantage; Java and C++ programmers will not be so sure. A discussion of the merits and demerits of static typing could fill a book the size of this one. Many of the most complex yet most reliable systems in the world today have been developed with dynamically typed languages. If you are a Java programmer, unshakably convinced of the perfect correctness of static typing, all we can do is urge you to try E first and form your conclusions later. We believe you will find the experience both pleasant and productive, as the long heritage of programmers from Scheme to Smalltalk to Perl and Python have found in the past.
E is not a panacea. The current implementation of E runs on top of the java virtual machine. As such, it is not a good language for low level machine manipulation. So do not try to use E for writing device drivers. And E's performance is quite unfavorable compared to raw C, so do not write the real time kernel of a missile guidance system with it, either.
Actually, most arguments over performance miss the most important points about software development. One of the few time-tested truths of software development is, "first get it to work, then get it to work fast". E is an excellent language for getting a system to work. Once it is working, you can gain the performance rewards by profiling to see which portions of the code actually affect performance, then rewriting those (typically small) portions in Java, or C, or assembler, depending on your needs. In fact, for many traditional compute-intensive activities, E is just as performance-efficient as anything else: when creating windows and buttons on the screen, you use the gui widgets from the underlying jvm. Since the jvm uses native drawing machinery, there is little distinction among languages when working the windows.
So perhaps E is in fact almost a panacea. But not quite.
This book is intended as an introductory text for practical E programming. Comparisons to Java are frequent, so some understanding of Java is desirable. If you wish to write software with point-and-click user interfaces, familiarity with either the Java Swing classes or the IBM Standard Widget Toolkit (SWT) is practically required.
This book is not a language specification. This book is an introduction to get you started and productive. If you encounter some surprising behavior not explained here, please join the e-lang discussion group and ask there: many helpful people can be found. If you need a precise specification, look to the reference materials posted by the language author and keeper, Mark Miller, at the ERights web site. You can join the e-lang discussion group at the same site.
When a very early version of E and E in a Walnut were presented to a programmer chat group, this was one of the comments:
"I think the key to hooking someone is to make them read the whole walnut cause it just looks like another scripting language until you get into the security and distribution then its like fireworks."
Though E is a powerful language with which to write single-cpu programs, the main power of E becomes evident only after you move into distributed programming. It would be tempting to introduce the distributed computing features first...except that you can't really do any meaningful computing without the basic data, flow, function, and object structures. So this book introduces "Ordinary Programming" Part I before getting into the serious distributed computing facilities. However, since E was designed in the C/Java syntax tradition, an experienced programmer can probably glean enough from the Quick Reference Card to skip directly to Part II on Distributed Computing. If you are short of time and have the requisite background, we recommend that strategy. Go back and read Part I when you are convinced that E's power for distributed programming meets your needs.
If you have read this far, you will probably want to retrieve a current version of E from www.erights.org. Follow the installation directions in the distribution.
You will find the rune interactive interpreter by going into the E directory and typing
java -jar e.jar --rune
Rune will be your friend for experimentation as you learn E. Indeed, you may find, as others have, that rune is useful even when developing ordinary Java: with this scratchpad you can quickly explore what the API for Java really does when you use it, quickly and easily, before you put Java code into the middle of a program that is difficult to test.
Crucial note: At the time of this writing, E is in transition to a return-keyword based syntax for returning values from methods and functions. The following examples will only work if you put the following pragmas at the top of E source files:
# E sample
pragma.syntax("0.9")
Using Rune: One-line commands start with a question mark prompt and return the result on the next line in a comment:
? 2 + 2 # value: 4
Commands that cannot be completed in a single line will receive close-angle-bracket continuations when you press carriage return at the end of the first line; the whole set of lines from the question mark down to the end of the command (the closing brace) will be evaluated when you close the statement:
? if (3 < 5) {
> println("is less")
> }
is lessAnother one of the wonderful little E features that helps enormously in rune is the help(obj) function. Type "help(interp)" into rune, and you will get a complete listing of all the methods you can call on the interp object. You will be surprised at first glance by the number of methods there; these methods are explained throughout the course of the book, starting at the end of the discussion of E objects.
We will present examples both as straight E source and as rune source, depending on how complex the example is.
The Trace Log will be one of your best friends when you step outside of rune and start writing E programs. When you install E, one of the items in the "eprops.txt" file is a specification of the directory where trace information should be written when a program fails during execution. Find your etrace directory(on Windows95, c:\windows\temp\etrace), and go there when you need debugging information. This is an important resource--more than one early adopter of E has kicked himself for forgetting that it is there, then spending several hours trying to understand a problem that was simple and obvious if you just looked at the log.
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.
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.
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
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:
# E sample def x := 3 def printString := "Value of x is: " + x
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.
We have already seen the if/then/else structure. Other traditional structures include:
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.
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")
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".
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)
}
}
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
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, 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.
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.
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.
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 car {
to moveDistance(newX,newY) {car.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.
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.
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)
} 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.
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".
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.
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
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
"The number is " + 1
works but
1 + " is the number"
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.
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.
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.
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).
stdout and stderr are both TextWriters in the E environment.
write the example
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.
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.
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.
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 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])
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.
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.
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.
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.
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()
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.
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
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.
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 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()
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 E.
This chapter on distributed computing is the longest and most challenging part of the book. The Promise Architecture of E 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 E is more a matter of architecture than of coding.
Distributed computation, however, still requires gritty effort. We start simply, with the eventually operator.
All distributed computing in E starts with the eventually operator, "<-":
# E syntax
car <- moveTo(2,3)
println("car will eventually move to 2,3. But not yet.")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; 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 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, E keeps track of the car's Universal Resource Identifier (URI) and delivers the message for you. Moreover, if the car is indeed remote, E 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.
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:
# E syntax
def carVow := makeCar <- ("Mercedes")
carVow <- moveTo(2,3)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:
# 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")
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.
# E syntax
def car :rcvr := makeCarRcvr <- ("Mercedes")
car <- moveTo(2,3)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.
The function nature of the "done" element of the when-catch is useful for making when-catch create promises for you, as discussed later.
When-catch, like try-catch, has an optional finally clause that always executes:
# E syntax
when (tempVow) -> {
#...use tempVow
} catch prob {
#.... report problem
} finally {
#....log event
}
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:
# 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`)}
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.
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 E 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.
# E syntax
def carRcvr := carMakerRcvr <- ("Mercedes")
carRcvr <- moveTo(2,3)
carRcvr <- moveTo(5,6)
carRcvr <- moveTo(7,3)
def fuelVow := carRcvr <- fuelRemaining()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.
# 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")
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.
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.
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.
Here is a test for equality:
# E syntax
def polePositionCarRcvr := raceTrack <- getPolePositionCar()
when (polePositionCarRcvr) -> {
if (polePositionCarRcvr == myCar) {
println("My car is in pole position")
}
} catch prob {}
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.
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 E:
# 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`)}
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 promis