Kevin Reid: incorporate content I wrote for E (object)

Kevin Reid — Wed, 20 Apr 2011 23:16:04 GMT

incorporate content I wrote for E (object)

New page

The object known as "E" in the [[safeEnv]] is the primitive with which variable-argument calls and sends may be made, and also provides shortcuts for converting objects to strings.

(Note: [[Caja-CapTP]], which borrows E's reference/call/send system, conflates this object with [[Object Ref|Ref]].)

Note that even though [[SendExpr|send expressions]] (<code><-</code>) are defined in terms of the E object, it does not solely constitute the authority to [[eventual send]]; [[Miranda whenMoreResolved|Miranda __whenMoreResolved]] means every object provides this authority.

==Protocol==

{{instance msgdoc|call|3|<var>recipient</var>, <var>verb</var> :[[String]], <var>args</var> :[[List]]|[[any]]}}

{{XXX|copied javadoc - review appropriateness as spec language}}

An E immediate call -- ask 'rec' to immediately do the request described by <var>verb</var> using the supplied <var>args</var>.

See [http://www.erights.org/elib/concurrency/msg-passing.html#call The Immediate Call].

{{instance msgdoc|callWithPair|3|<var>recipient</var>, <var>message</var> :Tuple<nowiki>[</nowiki>[[String]], [[List]]<nowiki>]</nowiki>|[[any]]}}

{{specbycode|E.call(<var>recipient</var>, <var>message</var>[0], <var>message</var>[1])}}

Defined in order to be more efficient when forwarding [[matcher]] messages than E.call.

The E implementation is not required to use a guard on <var>message</var> as strict as shown, though the guards for E.call's arguments must of course be applied. {{XXX|Review - is this a good idea? EoJ coerces to array but doesn't check the length, which is what I'm trying to capture here. --[[User:Kevin Reid|Kevin Reid]] 16:14, 12 August 2009 (CDT)}}

{{instance msgdoc|send|3|<var>rec</var>, <var>verb</var> :[[String]], <var>args</var> :[[List]]|[[Promise]]}}

{{XXX|copied javadoc - review appropriateness as spec language}}

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 [http://www.erights.org/elib/concurrency/msg-passing.html#pipe-send The Pipelined Send].

{{instance msgdoc|sendOnly|3|<var>rec</var>, <var>verb</var> :[[String]], <var>args</var> :[[List]]|[[void]]}}

{{XXX|copied javadoc - review appropriateness as spec language}}

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.

Return value: 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. {{XXX|Review: [[User:Kevin Reid]] recalls discussing deprecating this return value since it is not particularly useful and only available in the sendOnly case.}}

See [http://www.erights.org/elib/concurrency/msg-passing.html#sendOnly The Eventual Send: sendOnly].

{{instance msgdoc|toString|1|<var>object</var>|[[String]]}}

{{specbycode|<pre>def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()
tw.print(object)
return sb.toString()</pre>}}

{{XXX|copied javadoc - review appropriateness as spec language. Also, this particular one was edited from the toTwine doc to explain toString. Note that toTwine is not a method of EoJ E4E. Is this an oversight or a silent deprecation? --[[User:Kevin Reid|Kevin Reid]] 16:14, 12 August 2009 (CDT)}}

Prints obj, and returns this printed form.

E programmers should generally call "E.toString(obj)", rather than "obj.toString()". This applies both to E language programmers and to
ELib programmers. However, E programmers should not generally call
E.toString(obj) from within [[Miranda printOn|__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.

{{instance msgdoc|toQuote|1|<var>object</var>|[[String]]}}

{{specbycode|<pre>def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()
tw.quote(object)
return sb.toString()</pre>}}

{{XXX|Review Twine vs. String. EoJ E4E has Twine here but only String for non-quoting version. Seems incoherent --[[User:Kevin Reid|Kevin Reid]] 16:14, 12 August 2009 (CDT) }}

Like toString, but gets the quoted form.

[[Category:ELib specification]]

Kevin Reid: sketch documentation w/ copied javadoc

Kevin Reid — Wed, 12 Aug 2009 21:14:14 GMT

sketch documentation w/ copied javadoc

←Older revision		Revision as of 21:14, 12 August 2009
Line 1:		Line 1:
-	The object known as "E" in the [[safeEnv]] ~~is the primitive with which variable-argument calls and sends may be made, and also~~ provides ~~shortcuts~~ for ~~converting~~ objects ~~to strings~~.	+	The object known as "E" in the [[safeEnv]] provides facilities for invoking other objects.

	(Note: [[Caja-CapTP]], which borrows E's reference/call/send system, conflates this object with [[Object Ref\|Ref]].)		(Note: [[Caja-CapTP]], which borrows E's reference/call/send system, conflates this object with [[Object Ref\|Ref]].)
Line 7:		Line 7:
	==Protocol==		==Protocol==

-	{{instance msgdoc\|call\|3\|<var>~~recipient~~</var>, <var>verb</var> :[[String]], <var>args</var> :[[List]]\|[[any]]}}	+	{{instance msgdoc\|call\|3\|<var>rec</var>, <var>verb</var> :[[String]], <var>args</var> :[[List]]\|[[any]]}}

	{{XXX\|copied javadoc - review appropriateness as spec language}}		{{XXX\|copied javadoc - review appropriateness as spec language}}
Line 16:		Line 16:


-	{{instance msgdoc\|callWithPair\|3\|<var>~~recipient~~</var>, <var>message</var> :Tuple<nowiki>[</nowiki>[[String]], [[List]]<nowiki>]</nowiki>\|[[any]]}}	+	{{instance msgdoc\|callWithPair\|3\|<var>rec</var>, <var>message</var> :Tuple<nowiki>[</nowiki>[[String]], [[List]]<nowiki>]</nowiki>\|[[any]]}}

-	{{specbycode\|E.call(<var>~~recipient~~</var>, <var>message</var>[0], <var>message</var>[1])}}	+	{{specbycode\|E.call(<var>rec</var>, <var>message</var>[0], <var>message</var>[1])}}

	Defined in order to be more efficient when forwarding [[matcher]] messages than E.call.		Defined in order to be more efficient when forwarding [[matcher]] messages than E.call.
Line 52:		Line 52:
	See [http://www.erights.org/elib/concurrency/msg-passing.html#sendOnly The Eventual Send: sendOnly].		See [http://www.erights.org/elib/concurrency/msg-passing.html#sendOnly The Eventual Send: sendOnly].

-	{{instance msgdoc\|toString\|1\|<var>~~object~~</var>\|[[String]]}}	+	{{instance msgdoc\|toString\|1\|<var>obj</var>\|[[String]]}}
-		+
-	~~{{specbycode\|<pre>def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()~~	+
-	~~tw.print(object)~~	+
-	~~return sb.toString()</pre>~~}}	+

	{{XXX\|copied javadoc - review appropriateness as spec language. Also, this particular one was edited from the toTwine doc to explain toString. Note that toTwine is not a method of EoJ E4E. Is this an oversight or a silent deprecation? --[[User:Kevin Reid\|Kevin Reid]] 16:14, 12 August 2009 (CDT)}}		{{XXX\|copied javadoc - review appropriateness as spec language. Also, this particular one was edited from the toTwine doc to explain toString. Note that toTwine is not a method of EoJ E4E. Is this an oversight or a silent deprecation? --[[User:Kevin Reid\|Kevin Reid]] 16:14, 12 August 2009 (CDT)}}
Line 69:		Line 65:
	cycle before calling __printOn(TextWriter) on its argument.		cycle before calling __printOn(TextWriter) on its argument.

-	{{instance msgdoc\|toQuote\|1\|<var>~~object~~</var>\|[[String]]}}	+	{{instance msgdoc\|toQuote\|1\|<var>obj</var>\|[[String]]}}
-		+
-	~~{{specbycode\|<pre>def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()~~	+
-	~~tw.quote(object)~~	+
-	~~return sb.toString()</pre>~~}}	+

	{{XXX\|Review Twine vs. String. EoJ E4E has Twine here but only String for non-quoting version. Seems incoherent --[[User:Kevin Reid\|Kevin Reid]] 16:14, 12 August 2009 (CDT) }}		{{XXX\|Review Twine vs. String. EoJ E4E has Twine here but only String for non-quoting version. Seems incoherent --[[User:Kevin Reid\|Kevin Reid]] 16:14, 12 August 2009 (CDT) }}

Object E - Revision history

Kevin Reid: incorporate content I wrote for E (object)

Kevin Reid: sketch documentation w/ copied javadoc