@SlowPath renaming discussion

[Christian Wirth]

Hi,

Roland, I see your point. However, I think "@JavaCode" it is heavily 
confusing in the sense that all Truffle code is Java code as well.

-- Christian



Am 29.09.2014 11:33, schrieb Roland Schatz:
> A completely different suggestion, if you want to avoid the technical 
> term "partial evaluation":
>
> You could call it @JavaCode (or similar).
>
> The reasoning behind this is that, from now on, you're no longer 
> executing "Truffle" code, but vanilla "Java" code.
> What the annotation does is, it marks the boundary between the code of 
> the guest language interpreter, which is somehow special, and 
> transitioning to library code which is written in plain Java.
>
> This would be along the lines of @TruffleBoundary, but formulated 
> positively (i.e. what begins here, instead of what stops here).
> That way, the name describes what the annotation "means", as opposed 
> to what it "does".
>
> Just my 2¢.
>
> - Roland
>
> On 09/26/2014 04:11 PM, Christian Humer wrote:
>> Hi Folks,
>>
>> I've heard from a few people (including myself) that the @SlowPath
>> annotation naming might be misleading. That is why I want to raise a
>> discussion on this list, which will hopefully lead to a good permanent
>> decision for a new name.
>>
>> I would suggest these names:
>> @Boundary
>> @TruffleBoundary
>> @PartialEvaluationBoundary (or @PEBoundary)
>>
>> Please add more suggestions and vote for whatever you think is best.
>>
>> ---
>>
>> Here are some additional thoughts regarding the old name:
>>
>> The @SlowPath annotation marks the border for the Truffle partial
>> evaluator. So methods marked with @SlowPath are not partially 
>> evaluated and
>> treated as if they would be normal Java methods.
>>
>> Here is an example:
>>
>> @SlowPath
>> String stringConcat(String s1, String s2) {
>>     return new StringBuilder(s1).append(s2).toString();
>> }
>>
>> If there would be no @SlowPath annotation on this method then the 
>> partial
>> evaluator would just inline through the constructor and the append 
>> method.
>> This will produce too much code and is not desirable. Another issue 
>> is that
>> the implementation of append is not under the control of the guest 
>> language
>> implementation and might contain e.g. recursions which will make the
>> partial evaluator fail.
>>
>> Virtual objects like VirtualFrame instances must not be passed to 
>> @SlowPath
>> annotated methods because they leave the scope of the partial evaluator.
>> Such cases are considered Truffle compilation errors.
>>
>> To summarize:
>>   * @SlowPath should be applied on every call to a method that is not 
>> under
>> the control of the guest language implementation.
>>   * @SlowPath should be applied on guest language methods that are 
>> very big
>> and might produce too much code.
>>   * Virtual objects must not be passed to @SlowPath annotated methods.
>>
>> These are arguments against using "SlowPath" as name:
>>   * Its name does not explain the semantics in any way
>>   * @SlowPath might also be used for "fast path" code.
>>   * The use of @SlowPath does not imply slow execution.
>>
>>
>>
>> - Christian Humer
>