Proxy - Revision history

Kevin Reid: /* makeProxy */ explain resolutionSlot

2009-07-25T13:03:39Z

makeProxy: explain resolutionSlot

New page

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 reference|far references]] and [[pipelining]] [[remote promise|remote promises]].

== [http://erights.org/javadoc/org/erights/e/elib/ref/ProxyResolver.html makeEProxyResolver] ==

See [http://erights.org/javadoc/org/erights/e/elib/ref/ProxyResolver.html] 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 [http://www.eros-os.org/pipermail/e-lang/2007-March/011918.html] and the nearby thread for the discussion of its creation.

FQN (importable): <code>org.erights.e.ref.makeProxy</code>

Methods:

[[Category:Message run/3]]
* <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 <var>handler</var> and <var>resolutionSlot</var>,

* all results of makeProxy.run(<var>handler</var>, <var>resolutionSlot</var>, [[false]]) 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 <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 <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 <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 ==

Protocol for the handler supplied by the client of makeProxy.

Methods:

* handleSend(<var>verb</var> :[[String]], <var>args</var> :[[List (guard)|List]]) :[[any]]
* handleSendOnly(<var>verb</var> :[[String]], <var>args</var> :[[List (guard)|List]]) :[[any]]
* handleOptSealedDispatch(<var>brand</var>) :[[any]]
[[Category:Message handleSend/2]]
[[Category:Message handleSendOnly/2]]
[[Category:Message handleOptSealedDispatch/1]]

XXX document these

[[Category:ELib specification]]
[[Category:Protocols]]

Kevin Reid: /* ProxyHandler */ missing msg cat arity

2008-08-11T17:16:38Z

ProxyHandler: missing msg cat arity

←Older revision		Revision as of 17:16, 11 August 2008
Line 41:		Line 41:
	[[Category:Message handleSend/2]]		[[Category:Message handleSend/2]]
	[[Category:Message handleSendOnly/2]]		[[Category:Message handleSendOnly/2]]
-	[[Category:Message handleOptSealedDispatch]]	+	[[Category:Message handleOptSealedDispatch/1]]

	XXX document these		XXX document these

Kevin Reid: message cats, italic -> var tags

2008-07-02T02:41:22Z

message cats, italic -> var tags

←Older revision		Revision as of 02:41, 2 July 2008
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.

	== ProxyHandler ==		== ProxyHandler ==
Line 35:		Line 36:
	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]]

	XXX document these		XXX document these

Kevin Reid: categories

2008-07-02T02:37:07Z

Kevin Reid: new page: add description of proxies, and makeProxy protocol

2007-04-18T19:27:38Z

new page: add description of proxies, and makeProxy protocol

←Older revision		Revision as of 19:27, 18 April 2007
Line 15:		Line 15:
	Methods:		Methods:

-	~~[[Category:Message run/3]]~~	+	* <code>run</code>(''handler'' :[[#ProxyHandler\|ProxyHandler]], ''resolutionSlot'' :[[vow]]<nowiki>[</nowiki>[[FinalSlot]]<nowiki>]</nowiki>, ''far'' :[[boolean]]) :rcvr
-	* <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. ''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]].
-	: 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 ~~<var>~~handler~~</var>~~ and ~~<var>~~resolutionSlot~~</var>~~,	+	For a given ''handler'' and ''resolutionSlot'',

-	* all results of makeProxy.run(~~<var>~~handler~~</var>~~, ~~<var>~~resolutionSlot~~</var>~~, [[false]]) are the [[same]].	+	* all results of makeProxy.run(''handler'', ''resolutionSlot'', [[false]]) 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]].	+	* all results of makeProxy.run(''handler'', ''resolutionSlot'', [[true]]) between which ''resolutionSlot'' has not further resolved (as in [[TraversalKey]]) are the [[same]].

-	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.	+	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 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.	+	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.

-	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.	+	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.
-		+
-	~~===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 42:		Line 35:
	Methods:		Methods:

-	* handleSend(~~<var>~~verb~~</var>~~ :[[String]], ~~<var>~~args~~</var>~~ :[[List (guard)\|List]]) :[[any]]	+	* handleSend(''verb'' :[[String]], ''args'' :[[List (guard)\|List]]) :[[any]]
-	* handleSendOnly(~~<var>~~verb~~</var>~~ :[[String]], ~~<var>~~args~~</var>~~ :[[List (guard)\|List]]) :[[any]]	+	* handleSendOnly(''verb'' :[[String]], ''args'' :[[List (guard)\|List]]) :[[any]]
-	* handleOptSealedDispatch(~~<var>~~brand~~</var>~~) :[[any]]	+	* handleOptSealedDispatch(''brand'') :[[any]]
-	~~[[Category:Message handleSend/2]]~~	+
-	~~[[Category:Message handleSendOnly/2]]~~	+
-	~~[[Category:Message handleOptSealedDispatch/1~~]]	+

	XXX document these		XXX document these
-
-	~~[[Category:ELib specification]]~~
-	~~[[Category:Protocols]]~~

←Older revision		Revision as of 02:37, 2 July 2008
Line 40:		Line 40:

	XXX document these		XXX document these
		+
		+	[[Category:ELib specification]]
		+	[[Category:Protocols]]