org.erights.e.elib.prim
Class E

java.lang.Object
  |
  +--org.erights.e.elib.prim.E

public class E

extends Object

Safe: This class is most of the normal application programmer's API to the ELib functionality. In particular, the send methods below are what E's "<-" turn into.

NOTE! All the methods of this class trust their callers to 1) only provide interned strings as verbs, and 2) not modify an args array after passing it in. Btw, all source code literal strings are automatically intern()ed. ELib itself will never modify a passed-in args array.

This class is not intended to be used directly from E-language programs. Rather, the name "E" in the safe scope contains a thin wrapper for this class for the E language programmer to use instead.

Author:

Mark S. Miller

Field Summary

private static boolean	Backtracing XXX SECURITY ALERT: This is a semantically visible mutable static variable, used to suppress infinite regress when the attempt to generate a meaningful backtrace string results in another exception that needs to be backtraced.
static Object[]	NO_ARGS Enabled:

Constructor Summary

private

E() prevent instantiation

Method Summary

private static void	abbrev(StringBuffer buf, String str, int[] budget) To make the backtrace be pretty
static Object	as(Object specimen, Class targType) Enabled: These are E's implicit coercions to Java Class types, using Java's (not E's) null and non-near acceptance behavior.
static Object	as(Object specimen, Class targType, OneArgFunc optEjector) Enabled:
static boolean	asBoolean(Object specimen) Enabled: As a "boolean" scalar.
static char	asChar(Object specimen) Enabled: As a "char" scalar
static double	asFloat64(Object specimen) Enabled: As a "double" scalar
static int	asInt(Object specimen) Enabled: As an "int" scalar
static RuntimeException	asRTE(Object problem) Enabled: As a RuntimeException
static RuntimeException	backtrace(Throwable ex, Object rec, String verb, Object[] args) Enabled: Return 'ex' annotated with a compact description of 'rec.verb(args)'.
static Object	call(Object rec, String verb) Enabled: A 0-argument immediate call
static Object	call(Object rec, String verb, Object arg1) Enabled: A 1-argument immediate call
static Object	call(Object rec, String verb, Object arg1, Object arg2) Enabled: A 2-argument immediate call
static Object	call(Object rec, String verb, Object arg1, Object arg2, Object arg3) Enabled: A 3-argument immediate call
static Object	call(Object rec, String verb, Object arg1, Object arg2, Object arg3, Object arg4) Enabled: A 4-argument immediate call
static Object	callAll(Object rec, String verb, Object[] args) Enabled: An E immediate call -- ask 'rec' to immediately do the request described by 'verb' using the supplied 'args'.
static void	require(boolean cond) Enabled: 'problem' defaults to "required condition failed"
static void	require(boolean cond, Object problem) Enabled: If cond isn't true, report problem or problem().
static Ref	send(Object rec, String verb) Enabled: A 0-argument eventual send
static Ref	send(Object rec, String verb, Object arg1) Enabled: A 1-argument eventual send
static Ref	send(Object rec, String verb, Object arg1, Object arg2) Enabled: A 2-argument eventual send
static Ref	send(Object rec, String verb, Object arg1, Object arg2, Object arg3) Enabled: A 3-argument eventual send
static Ref	send(Object rec, String verb, Object arg1, Object arg2, Object arg3, Object arg4) Enabled: A 4-argument eventual send
static Ref	sendAll(Object rec, String verb, Object[] args) Enabled: Queue the described delivery.
static Throwable	sendAllOnly(Object rec, String verb, Object[] args) Enabled: Like sendAll(rec, verb, args), except that "Only" means we don't care about the result (including whether it succeeded), as is appropriate for event notifications.
static Throwable	sendOnly(Object rec, String verb) Enabled: A 0-argument eventual sendOnly
static Throwable	sendOnly(Object rec, String verb, Object arg1) Enabled: A 1-argument eventual sendOnly
static Throwable	sendOnly(Object rec, String verb, Object arg1, Object arg2) Enabled: A 2-argument eventual sendOnly
static Throwable	sendOnly(Object rec, String verb, Object arg1, Object arg2, Object arg3) Enabled: A 3-argument eventual sendOnly
static Throwable	sendOnly(Object rec, String verb, Object arg1, Object arg2, Object arg3, Object arg4) Enabled: A 4-argument eventual sendOnly
static Twine	toQuote(Object obj) Enabled: Like toTwine, but gets the quoted form.
static String	toString(Object obj) Enabled: Like E.toTwine(obj), but returns a String.
static Twine	toTwine(Object obj) Enabled: Prints obj into a Twine if necessary, and returns this printed form.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_ARGS

public static final Object[] NO_ARGS

Enabled:

Backtracing

private static boolean Backtracing

XXX SECURITY ALERT: This is a semantically visible mutable static variable, used to suppress infinite regress when the attempt to generate a meaningful backtrace string results in another exception that needs to be backtraced.

This is a rare case of something I don't know how to do as well in a pure capability pattern.

Constructor Detail

E

private E()

prevent instantiation

Method Detail

call

public static Object call(Object rec,
                          String verb)

Enabled: A 0-argument immediate call

See Also:

callAll(Object, String, Object[])

call

public static Object call(Object rec,
                          String verb,
                          Object arg1)

Enabled: A 1-argument immediate call

See Also:

callAll(Object, String, Object[])

call

public static Object call(Object rec,
                          String verb,
                          Object arg1,
                          Object arg2)

Enabled: A 2-argument immediate call

See Also:

callAll(Object, String, Object[])

call

public static Object call(Object rec,
                          String verb,
                          Object arg1,
                          Object arg2,
                          Object arg3)

Enabled: A 3-argument immediate call

See Also:

callAll(Object, String, Object[])

call

public static Object call(Object rec,
                          String verb,
                          Object arg1,
                          Object arg2,
                          Object arg3,
                          Object arg4)

Enabled: A 4-argument immediate call

See Also:

callAll(Object, String, Object[])

callAll

public static Object callAll(Object rec,
                             String verb,
                             Object[] args)

Enabled: An E immediate call -- ask 'rec' to immediately do the request described by 'verb' using the supplied 'args'.

See Also:

The Immediate Call

abbrev

private static void abbrev(StringBuffer buf,
                           String str,
                           int[] budget)

To make the backtrace be pretty

backtrace

public static RuntimeException backtrace(Throwable ex,
                                         Object rec,
                                         String verb,
                                         Object[] args)

Enabled: Return 'ex' annotated with a compact description of 'rec.verb(args)'.

Returns:

a RuntimeException that wraps ex with a description of the call 'rec.verb(args...)', without a preceding "***". the description is a line of text approximately in E call notation, but abbreviated to fit on one long line. Removed text is replaced with "...".

send

public static Ref send(Object rec,
                       String verb)

Enabled: A 0-argument eventual send

See Also:

sendAll(Object, String, Object[])

send

public static Ref send(Object rec,
                       String verb,
                       Object arg1)

Enabled: A 1-argument eventual send

See Also:

sendAll(Object, String, Object[])

send

public static Ref send(Object rec,
                       String verb,
                       Object arg1,
                       Object arg2)

Enabled: A 2-argument eventual send

See Also:

sendAll(Object, String, Object[])

send

public static Ref send(Object rec,
                       String verb,
                       Object arg1,
                       Object arg2,
                       Object arg3)

Enabled: A 3-argument eventual send

See Also:

sendAll(Object, String, Object[])

send

public static Ref send(Object rec,
                       String verb,
                       Object arg1,
                       Object arg2,
                       Object arg3,
                       Object arg4)

Enabled: A 4-argument eventual send

See Also:

sendAll(Object, String, Object[])

sendAll

public static Ref sendAll(Object rec,
                          String verb,
                          Object[] args)

Enabled: Queue the described delivery.

Rather than providing an explicit Resolver as input argument, this method returns a promise that represents the outcome. When the actual outcome is determined, the returned reference will reflect that outcome.

This should only synchronously throw an exception if invoked while there's no current Vat.

See Also:

The Pipelined Send

sendOnly

public static Throwable sendOnly(Object rec,
                                 String verb)

Enabled: A 0-argument eventual sendOnly

See Also:

sendAllOnly(Object, String, Object[])

sendOnly

public static Throwable sendOnly(Object rec,
                                 String verb,
                                 Object arg1)

Enabled: A 1-argument eventual sendOnly

See Also:

sendAllOnly(Object, String, Object[])

sendOnly

public static Throwable sendOnly(Object rec,
                                 String verb,
                                 Object arg1,
                                 Object arg2)

Enabled: A 2-argument eventual sendOnly

See Also:

sendAllOnly(Object, String, Object[])

sendOnly

public static Throwable sendOnly(Object rec,
                                 String verb,
                                 Object arg1,
                                 Object arg2,
                                 Object arg3)

Enabled: A 3-argument eventual sendOnly

See Also:

sendAllOnly(Object, String, Object[])

sendOnly

public static Throwable sendOnly(Object rec,
                                 String verb,
                                 Object arg1,
                                 Object arg2,
                                 Object arg3,
                                 Object arg4)

Enabled: A 4-argument eventual sendOnly

See Also:

sendAllOnly(Object, String, Object[])

sendAllOnly

public static Throwable sendAllOnly(Object rec,
                                    String verb,
                                    Object[] args)

Enabled: Like sendAll(rec, verb, args), except that "Only" means we don't care about the result (including whether it succeeded), as is appropriate for event notifications.

Returns:

Why wasn't this event queued? It isn't queued if this vat or comm connection is shut down, in which case the returned problem explains why. If null is returned, then the event was queued, though it may still not arrive.

See Also:

The Eventual Send: sendOnly

toString

public static String toString(Object obj)

Enabled: Like E.toTwine(obj), but returns a String.

toTwine

public static Twine toTwine(Object obj)

Enabled: Prints obj into a Twine if necessary, and returns this printed form.

E programmers should generally call "E.toTwine(obj)", rather than "obj.toString()". This applies both to E language programmers and to ELib programmers. However, E programmers should not generally call E.toTwine(obj) from within __printOn(TextWriter) methods, as that will circumvent the cycle-breaking logic in TextWriter. Instead, you should usually call a TextWriter.*print*(obj) method, as it will check for a cycle before calling __printOn(TextWriter) on its argument.

toQuote

public static Twine toQuote(Object obj)

Enabled: Like toTwine, but gets the quoted form.

See Also:

org.erights.e.elib.oldeio.TextWriter#quote

as

public static Object as(Object specimen,
                        Class targType)

Enabled: These are E's implicit coercions to Java Class types, using Java's (not E's) null and non-near acceptance behavior.

Given that specimen is NEAR, when targType isPrimitive(), then

    E.as(specimen, targType)

is like

    targType.coerce(specimen, null)

Otherwise

E.as(specimen, targType)

is like

nullOk(targType).coerce(specimen, null)

If specimen is not near and targType isn't a rubber stamping interface, then either of the above coerce calls will fail, but E.as will succeed if the specimen is a Java-instanceof the targType.

as

public static Object as(Object specimen,
                        Class targType,
                        OneArgFunc optEjector)

Enabled:

asBoolean

public static boolean asBoolean(Object specimen)

Enabled: As a "boolean" scalar.

asInt

public static int asInt(Object specimen)

Enabled: As an "int" scalar

asFloat64

public static double asFloat64(Object specimen)

Enabled: As a "double" scalar

asChar

public static char asChar(Object specimen)

Enabled: As a "char" scalar

asRTE

public static RuntimeException asRTE(Object problem)

Enabled: As a RuntimeException

require

public static void require(boolean cond)

Enabled: 'problem' defaults to "required condition failed"

require

public static void require(boolean cond,
                           Object problem)

Enabled: If cond isn't true, report problem or problem().

If problem coerces to a Thunk, then reassign problem to be the result of calling this thunk with 'run()'. Then, in either case, coerce this problem to a RuntimeException and throw it.

This is used by the implementation of the 'require' function in the E language's universal scope.