@SlowPath renaming discussion

[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