Class ReturnRetention

java.lang.Object
org.ek9lang.compiler.support.ReturnRetention
public final class ReturnRetention extends Object
THE reading of what a call's RESULT may share with what it was called on - the return half of the CommonValues.RETAINS declaration. Use this wherever a check must know whether the value a call hands back can be a view of something else; never parse the RETAINS text again.

The built-ins DECLARE it (@Ek9Retains, stamped at bootstrap by OperationFactory); phase 5 DERIVES the same marker, with the same meaning, for a user method or operator that returns one of its own properties or a view of one (phase5/ReceiverInteriorReturns), so built-ins and user code follow one rule. The derived value is RECEIVER_INTERIOR, exactly the text a built-in declares.

A result MAY ALIAS when its callee declares any of:

  • return <- receiver-interior - a view of the receiver (JSON.get, DictEntry.value, Iterator.next);
  • return <- <parameter> - possibly an argument itself (List.getOrDefault's return <- defaultValue);
  • unknown - the inexpressible-retention opt-out, so nothing may be assumed.

It also answers the ARGUMENT half a caller needs: whether the callee may keep one of its arguments (retainsArgument(ScopedSymbol, int), e.g. List.+='s receiver <- item). Every rule is read through RetentionRule, which names a parameter by its declared EK9 name - so the rules are matched by FORM, never by a literal parameter name.

A member of a parameterised type is a substituted copy that may have been made before phase 5 derived the marker, so the generic's own member is read too (GenericTemplateMember).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    RECEIVER_INTERIOR
    The RETAINS rule saying a call's result is (part of) the object it was called on.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Optional<ScopedSymbol>
    calleeOf(EK9Parser.ExpressionContext expression, Function<org.antlr.v4.runtime.tree.ParseTree, ISymbol> recorded)
    The method, operator or function an expression CALLS when the whole expression is that call - a.get(k), first(), a + b, (a.get(k)) - so its value is whatever the call handed back.
    static Optional<ScopedSymbol>
    calleeOf(ISymbol recorded)
    The method or function a recorded symbol CALLS, when it is a call that hands back a value made elsewhere: a method, operator or function call - never a constructor, whose result is always fresh.
    static void
    markReturnsReceiverInterior(MethodSymbol method)
    Record, on a user method or operator, that what it returns is (part of) its receiver.
    static boolean
    mayAlias(ScopedSymbol callee)
    Does what callee returns possibly share an object with its receiver or an argument.
    static boolean
    retainsArgument(ScopedSymbol callee, int parameterIndex)
    May callee keep (a reference to) the argument it is given at parameterIndex - into its receiver, another argument, its result or anywhere else (receiver <- item, return <- other, or unknown)? An argument the callee keeps is no longer the caller's alone.
    static boolean
    returnsReceiverInterior(ScopedSymbol callee)
    Does what callee returns possibly share an object with its RECEIVER.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • RECEIVER_INTERIOR

      public static final String RECEIVER_INTERIOR
      The RETAINS rule saying a call's result is (part of) the object it was called on.
      See Also:

  • Method Details

    • calleeOf

      public static Optional<ScopedSymbol> calleeOf(ISymbol recorded)
      The method or function a recorded symbol CALLS, when it is a call that hands back a value made elsewhere: a method, operator or function call - never a constructor, whose result is always fresh.

    • calleeOf

      public static Optional<ScopedSymbol> calleeOf(EK9Parser.ExpressionContext expression, Function<org.antlr.v4.runtime.tree.ParseTree, ISymbol> recorded)
      The method, operator or function an expression CALLS when the whole expression is that call - a.get(k), first(), a + b, (a.get(k)) - so its value is whatever the call handed back. Empty for a literal, an identifier, a constructor, a dynamic function, a list or dict literal and the control forms.
      Parameters:
      expression - the expression, as the compiler parsed it
      recorded - the recorded-symbol lookup of the phase asking (symbolsAndScopes or parsedModule)

    • mayAlias

      public static boolean mayAlias(ScopedSymbol callee)
      Does what callee returns possibly share an object with its receiver or an argument.

    • returnsReceiverInterior

      public static boolean returnsReceiverInterior(ScopedSymbol callee)
      Does what callee returns possibly share an object with its RECEIVER.

    • retainsArgument

      public static boolean retainsArgument(ScopedSymbol callee, int parameterIndex)
      May callee keep (a reference to) the argument it is given at parameterIndex - into its receiver, another argument, its result or anywhere else (receiver <- item, return <- other, or unknown)? An argument the callee keeps is no longer the caller's alone.

    • markReturnsReceiverInterior

      public static void markReturnsReceiverInterior(MethodSymbol method)
      Record, on a user method or operator, that what it returns is (part of) its receiver.