Re: [WebIDL] Would it make sense to add annotations for "creates a new object each time" and "always returns the same object"?

On Oct 18, 2012, at 7:45 AM, Marcos Caceres wrote:

> 
> I would be in favor of this. For example, the JS i18n API returns you a different object when you ask it for "resolved options". As an author, it would be nice to see at a glance that you get a distinct object. And as a tester, it could add some trivial automation to testing a method's behavior.  
> 
> -- 
> Marcos Caceres
> 

We used something similar to this for defining the class library interfaces for the ANSI Standard (http://wiki.squeak.org/squeak/172) for the Smalltalk language.  We had several attributes we could use with return values (see below).  It turned out that the most important attribute wasn't "new", instead it was "state" which which means that the returning object was also retained, as part of its internal state,  a reference to the returned object.

Specify whether or not parameter values were retained by an object also proved to be important.

Here is the description of the return value annotations from the Smalltalk standard:

Parameter Specification
...
Aliasing information (for example, whether a parameter is stored, or whether a returned value is new or returned state) is specified to avoid having implementors use defensive programming techniques which result in unnecessary object creation and copying, incurring a performance penalty. We differentiate between incidental aliasing and essential aliasing, both for parameters and for return values. Essential aliasing forms a critical part of the behavior of the interface, and as such it must be specified by the interface designer. Incidental aliasing should not be specified since it is a side effect of implementation choices, and is not fundamental to the specified functionality of the interface.

Essential aliasing of parameters is described using a parameter aliasing attribute:
captured	The receiver always retains a reference to the parameter, directly or indirectly, as a result of this message.
uncaptured 	The receiver never retains a reference to the parameter, directly or indirectly, as a result of this message.
unspecified 	It is unspecified as to whether or not a reference is retained as a result of this message i.e. either case may occur.


Return value specification

A return value specification is defined by a return value protocol and a return value aliasing attribute. Whereas the parameter description is prescriptive in that it states requirements to which the parameters must conform, the return value information is descriptive in that it provides information about the result being returned. Whereas a protocol makes a conformance requirement statement about parameters, it makes a conformance commitment concerning the return value. The specification guarantees that the return value will conform to the specified protocol.

A message specification may have multiple distinct return value specifications. Conversely, a single return value specification may describe multiple return values if the return value specification applies to all such values. Multiple return value specifications are required for cases where a message is defined to return objects conforming to different protocols, on a case-specific basis. These are conveniently described with separate conformance statements and aliasing annotations. In order to establish correspondence between sets of return value specifications, we do not permit two distinct return value specifications which promise conformance to the same protocol.

If a message specification has no return value specification (that is, the return value is  not specified), then it is not prepared to guarantee anything about the behavior of the returned object. In this case we denote the return value as UNSPECIFIED. This can be used to separate procedural messages from functional messages; to allow for inconsequential differences in implementations; or to allow conforming implementations which return different results but are otherwise operationally equivalent.

In order to relate return values through conformance, we define the return value interface definition for a message specification to be the single return value protocol, or the logical OR of the protocols in each distinct return value specification.

Information concerning retained references to return values (by the message receiver) is described using a return value aliasing attribute, which is one of the following identifiers:
state	        The receiver retains a reference (direct or indirect) to the returned object after the method returns i.e. the object is returned state.
new	                The object is newly created in the method invocation and no reference (direct or indirect) is retained by the receiver after the method returns.
unspecified	No information is provided as to the origin or retained references to the object (Note this is different from saying that the return value itself is UNSPECIFIED.  Here we are committing that the return value conforms to some protocol, but making no commitment about the aliasing behavior).

Note that we do not attempt to describe the aliasing of the state variables of the return value itself—the attribute applies only to the first level returned object. The implication is that second and subsequent level aliasing of the return value is always unspecified. An exception occurs in the case where the returned state is an object which the client originally gave the service provider for safekeeping. This occurs with element retrieval in collections, for example. In such cases only the client knows the implications of modifying second level state of the return value.