Proxy

From Erights

(Difference between revisions)
Jump to: navigation, search
(new page: add description of proxies, and makeProxy protocol)
(makeProxy: explain resolutionSlot)
 
Line 15: Line 15:
Methods:
Methods:
-
* <code>run</code>(''handler'' :[[#ProxyHandler|ProxyHandler]], ''resolutionSlot'' :[[vow]]<nowiki>[</nowiki>[[FinalSlot]]<nowiki>]</nowiki>, ''far'' :[[boolean]]) :rcvr
+
[[Category:Message run/3]]
-
: Creates a new proxy. ''handler'' is the handler for messages sent to the proxy; ''resolutionSlot'' specifies the resolution (see below); ''far'' is true if the proxy is to be a [[Far ref]] and false for a [[remote promise]].
+
* <code>run</code>(<var>handler</var> :[[#ProxyHandler|ProxyHandler]], <var>resolutionSlot</var> :[[vow]]<nowiki>[</nowiki>[[FinalSlot]]<nowiki>]</nowiki>, <var>far</var> :[[boolean]]) :rcvr
 +
: Creates a new proxy. <var>handler</var> is the handler for messages sent to the proxy; <var>resolutionSlot</var> specifies the resolution (see below); <var>far</var> is true if the proxy is to be a [[Far ref]] and false for a [[remote promise]].
-
For a given ''handler'' and ''resolutionSlot'',  
+
For a given <var>handler</var> and <var>resolutionSlot</var>,  
-
* all results of makeProxy.run(''handler'', ''resolutionSlot'', [[false]]) are the [[same]].
+
* all results of makeProxy.run(<var>handler</var>, <var>resolutionSlot</var>, [[false]]) are the [[same]].
-
* all results of makeProxy.run(''handler'', ''resolutionSlot'', [[true]]) between which ''resolutionSlot'' has not further resolved (as in [[TraversalKey]]) are the [[same]].
+
* all results of makeProxy.run(<var>handler</var>, <var>resolutionSlot</var>, [[true]]) between which <var>resolutionSlot</var> has not further resolved (as in [[TraversalKey]]) are the [[same]].
-
The ''resolutionSlot'' should be a [[vow]] for a [[FinalSlot]] whose value is the reference to which this proxy resolves. As soon as ''resolutionSlot'' is itself resolved, the proxy will turn into its resolution; ''handler'' will never again be invoked.
+
The <var>resolutionSlot</var> should be a [[vow]] for a [[FinalSlot]] whose value is the reference to which this proxy resolves. As soon as <var>resolutionSlot</var> is itself resolved, the proxy will turn into its resolution; <var>handler</var> will never again be invoked.
-
Far proxies may only be resolved to [[broken reference|broken references]]; if the resolution is something else, or if ''resolutionSlot'' resolves to something not a [[FinalSlot]], then the proxy will resolve to a [[broken reference]] whose (sealed, if applicable) problem indicates that error.
+
Far proxies may only be resolved to [[broken reference|broken references]]; if the resolution is something else, or if <var>resolutionSlot</var> resolves to something not a [[FinalSlot]], then the proxy will resolve to a [[broken reference]] whose (sealed, if applicable) problem indicates that error.
-
Send and sendOnly on a proxy send the corresponding <code>handle*</code> messages to ''handler''. [[Object Ref#optSealedDispatch|Ref.optSealedDispatch]] on a proxy calls ''handler''<code>.handleOptSealedDispatch</code> immediately.
+
Send and sendOnly on a proxy send the corresponding <code>handle*</code> messages to <var>handler</var>. [[Object Ref#optSealedDispatch|Ref.optSealedDispatch]] on a proxy calls <var>handler</var><code>.handleOptSealedDispatch</code> immediately.
 +
 
 +
===Rationale for resolutionSlot===
 +
 
 +
The old ProxyResolver facility was a [[Resolver]] which could resolve the proxy. The problem with this interface is that, since it is imperative, the proxy's total behavior depends on the holder of the resolver and not solely on its components. Therefore, ProxyResolver clients could make two proxies which are allegedly the [[same]] but actually differ in behavior (different resolutions). Using a promise to specify the resolution avoids this possibility because promises can be compared.
 +
 
 +
The reason a promise for a slot containing the resolution is used, rather than a promise for the resolution, is so that the resolution itself being a promise can be distinguished from the resolution not having occurred yet.
== ProxyHandler ==
== ProxyHandler ==
Line 35: Line 42:
Methods:
Methods:
-
* handleSend(''verb'' :[[String]], ''args'' :[[List (guard)|List]]) :[[any]]
+
* handleSend(<var>verb</var> :[[String]], <var>args</var> :[[List (guard)|List]]) :[[any]]
-
* handleSendOnly(''verb'' :[[String]], ''args'' :[[List (guard)|List]]) :[[any]]
+
* handleSendOnly(<var>verb</var> :[[String]], <var>args</var> :[[List (guard)|List]]) :[[any]]
-
* handleOptSealedDispatch(''brand'') :[[any]]
+
* handleOptSealedDispatch(<var>brand</var>) :[[any]]
 +
[[Category:Message handleSend/2]]
 +
[[Category:Message handleSendOnly/2]]
 +
[[Category:Message handleOptSealedDispatch/1]]
XXX document these
XXX document these
 +
 +
[[Category:ELib specification]]
 +
[[Category:Protocols]]

Latest revision as of 13:03, 25 July 2009

A proxy is an eventual reference whose behavior is specified by other references.

In current implementations, all eventual references are either primitive promises or proxies, and proxies are the only way to create far references and pipelining remote promises.

Contents

makeEProxyResolver

See [1] for documentation. This protocol is deprecated because clients of it may break sameness by creating proxies with the same identity but different behavior.

makeProxy

The new proxy maker protocol, which is robust and available as a safe import. See [2] and the nearby thread for the discussion of its creation.

FQN (importable): org.erights.e.ref.makeProxy

Methods:

Creates a new proxy. handler is the handler for messages sent to the proxy; resolutionSlot specifies the resolution (see below); far is true if the proxy is to be a Far ref and false for a remote promise.

For a given handler and resolutionSlot,

  • all results of makeProxy.run(handler, resolutionSlot, false) are the same.
  • all results of makeProxy.run(handler, resolutionSlot, true) between which resolutionSlot has not further resolved (as in TraversalKey) are the same.

The resolutionSlot should be a vow for a FinalSlot whose value is the reference to which this proxy resolves. As soon as resolutionSlot is itself resolved, the proxy will turn into its resolution; handler will never again be invoked.

Far proxies may only be resolved to broken references; if the resolution is something else, or if resolutionSlot resolves to something not a FinalSlot, then the proxy will resolve to a broken reference whose (sealed, if applicable) problem indicates that error.

Send and sendOnly on a proxy send the corresponding handle* messages to handler. Ref.optSealedDispatch on a proxy calls handler.handleOptSealedDispatch immediately.

Rationale for resolutionSlot

The old ProxyResolver facility was a Resolver which could resolve the proxy. The problem with this interface is that, since it is imperative, the proxy's total behavior depends on the holder of the resolver and not solely on its components. Therefore, ProxyResolver clients could make two proxies which are allegedly the same but actually differ in behavior (different resolutions). Using a promise to specify the resolution avoids this possibility because promises can be compared.

The reason a promise for a slot containing the resolution is used, rather than a promise for the resolution, is so that the resolution itself being a promise can be distinguished from the resolution not having occurred yet.

ProxyHandler

Protocol for the handler supplied by the client of makeProxy.

Methods:

XXX document these

Personal tools
more tools