Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JDT Core Programmer Guide/ECJ/Bindings"

Line 50: Line 50:
 
* If the nested type is '''static''', any type parameters from its outer class are irrelevant for the nested type, as it cannot access them without an outer instance.
 
* If the nested type is '''static''', any type parameters from its outer class are irrelevant for the nested type, as it cannot access them without an outer instance.
 
* If the nested type is '''non-static''', reference to this type are represented by a ParameterizedTypeBinding even if the nested type itself declares no type parameters, because here the nested type can refer to type variables of the enclosing type & instance (this was wrong prior to {{Bug|460491}}).
 
* If the nested type is '''non-static''', reference to this type are represented by a ParameterizedTypeBinding even if the nested type itself declares no type parameters, because here the nested type can refer to type variables of the enclosing type & instance (this was wrong prior to {{Bug|460491}}).
 +
 +
==Flag vectors==
 +
* <code>tagBits</code> (TypeBinding,MethodBinding,VariableBinding): set of bits as declared in <code>TagBits</code>
 +
** Is*: fine grained classification of a binding
 +
** Begin*, End*: pairs of flags that indicate when a given processing step is active / complete (used to avoid re-entrance / recursion).
 +
** AreFieldsComplete, AreFieldsSorted, AreMethodsComplete, AreMethodsSorted: describes that status of arrays <code>fields</code> and <code>methods</code>
 +
** Has*: various diagnostics
 +
** Annotation*: marks when a given annotation has been applied to the element.
 +
* <code>extendedTagBits</code> (TypeBinding): overflow from tagBits, constants are in <code>ExtendedTagBits</code>.<br>'''New bits should preferrably be allocated here, rather than the crowded TagBits'''.
 +
* <code>typeBits</code> (ReferenceBinding): classification of types, constants in <code>TypeIds</code>:
 +
** classification of resources (below <code>Closeable</code>), see [[JDT Core Programmer Guide/ECJ/Analyse#Black_lists_.2F_white_lists|Analysis->Black lists / white lists]]
 +
** BitUninitialized
 +
** BitUninternedType: classify JDT's own types <code>TypeBinding</code> (compiler) and <code>ITypeBinding</code> DOM as not suitable for reference comparison (<code>==</code>, <code>!=</code>), unless documented <code>$IDENTITY-COMPARISON</code>.
 +
** Bit*Null*Annotation: detect annotation types, configured for use by ECJ's annotation based null analysis.
 +
** BitMap, BitCollection, BitList: mark types which have methods with well-known problems (see [[ JDT Core Programmer Guide/ECJ/AST#Algorithm_implementations|UnlikelyArgumentCheck]]).
 +
  
 
==Synthetic Bindings==
 
==Synthetic Bindings==
Line 56: Line 72:
 
==Other classes in the lookup package==
 
==Other classes in the lookup package==
  
''the structure of section should be improved.''
+
''the structure of this section should be improved.''
  
  
 
===Constants===
 
===Constants===
* TagBits - big bag of flags in bitset <code>tagBits</code>
+
* TagBits - big bag of flags in bitset <code>tagBits</code>, see [[#Flag Vectors]]
* ExtendedTagBits
+
* ExtendedTagBits, see [[#Flag Vectors]]
 
* ExtraCompilerModifiers - will appear in fields <code>modifier</code> but are never found in .class files
 
* ExtraCompilerModifiers - will appear in fields <code>modifier</code> but are never found in .class files
 
* ProblemReasons - constants used in Problem*Binding
 
* ProblemReasons - constants used in Problem*Binding
 
* TypeConstants - not only type, also well-known method names etc
 
* TypeConstants - not only type, also well-known method names etc
* TypeIds
+
* TypeIds - integer constants relating to types
  
 
===Management of variants of a type binding===
 
===Management of variants of a type binding===

Revision as of 18:45, 4 July 2020

Note.png
Bindings implement what some text books call "Symbols": unique values used for linking name references to their target.


Main Kinds of Bindings

See the type hierarchy of org.eclipse.jdt.internal.compiler.lookup.Binding. This class also declares constants which define possible answers from Binding.kind().

  • One reason why kinds are or-able bits: a NameReference can use an int as bitset to encode if it can legally resolve to a variable, or a type, or both, where variable can be either a field or a local.


As a special type, UnresolvedReferenceBinding is a placeholder for a not-yet resolved ReferenceBinding. Resolving an UnresolvedReferenceBinding will update its holder, too.


Another group of bindings is synthesized by the compiler from thin air, see #Synthetic Bindings.

General rules for Bindings

No null

In constrast to AST, where null is typically a legal field value, bindings typically use constants of the NO_* family to denote "nothing here". null would typically indicate "not initialized".

Comparison

Since bindings are unique by construction, it would normally be OK to compare bindings using == or !=. Specifically with the introduction of TYPE_USE annotations, even the same type can be represented by different bindings to account for attached annotations. For that reason, specific comparison methods have been added, which should be used throughout:

  • TypeBinding.equalsEquals()
  • TypeBinding.notEquals()

These methods ignore difference only in annotations. Those rare cases where annotation difference should indeed be considered have to be marked in source with //$IDENTITY-COMPARISON$, to suppress a warning implemented specifically for the compiler's own sake.

Internally, each TypeBinding has an id. Low values correspond to well-known types (see TypeIds), while higher values are allocated dynamically. Ids are interesting as the family of all type bindings derived from the same original share the same id. Ids also simplify checks for well-known types.

Non-Uniqueness

Contrary to the general rule, a number of reasons exist, why the same source entity can be represented by several distinct bindings:

  • When the same package exists in several modules, we create one PackageBinding per module, plus a SplitPackageBinding to combine the slices into one. The current strategy concerning SplitPackageBinding was developed via bug 547181 which has a lot of explanations.
  • From a generic type (SourceTypeBinding or BinaryTypeBinding) a number of parameterizations can be created using ParameterizedTypeBinding.
    • For each contained MethodBinding a ParameterizedMethodBinding is created to carry the instantiation of type variables.
    • For each contained FieldBinding a ParameterizedFieldBinding is created to carry the instantiation of type variables.
  • From a generic method (MethodBinding) a number of parameterizations can be created using ParameterizedGenericMethodBinding. While ParameterizedMethodBinding captures type variables of the declaring class, ParameterizedGenericMethodBinding captures type variables declared by the method itself.
  • From each TypeBinding a number of "clones" (of the same type) can be created with different sets of TYPE_USE annotations. Indeed, method TypeBinding.clone() is used for this process, and TypeBinding.prototype() will answer the original from which an annotated type was cloned.
  • From each WildcardBinding a number of CaptureBinding can be created, but that's not of ECJ's invention, but specified in JLS.


When comparing bindings, it is sometimes necessary, to explicitly strip a wrapper binding using one of these methods:

  • TypeBinding.original() strips annotations, and erases parameterized, raw and array types
  • TypeBinding.erasure() full erasure (no type arguments), but may or may not retain annotations
  • TypeBinding.unannotated() strips annotations only
  • TypeBinding.actualType() answers the erasure from ParameterizedTypeBinding and WildcardBinding, null otherwise
  • ParameterizedTypeBinding.genericType(): like actualType() but performes lazy resolving of UnresolvedReferenceBinding
  • MethodBinding.genericMethod(): strips instantiation of a method's own type variables
  • MethodBinding.original(): strips any parameterization
  • MethodBinding.shallowOriginal(): strips instantiation of a method's own type variables, but leaves instantiations of class parameters in place (unclear if different from genericMethod()).

Parameterization and nesting

A plain method inside a ParameterizedType will be represented by a ParameterizedMethodBinding. But what about a nested type inside a generic outer type?

  • If the nested type is static, any type parameters from its outer class are irrelevant for the nested type, as it cannot access them without an outer instance.
  • If the nested type is non-static, reference to this type are represented by a ParameterizedTypeBinding even if the nested type itself declares no type parameters, because here the nested type can refer to type variables of the enclosing type & instance (this was wrong prior to bug 460491).

Flag vectors

  • tagBits (TypeBinding,MethodBinding,VariableBinding): set of bits as declared in TagBits
    • Is*: fine grained classification of a binding
    • Begin*, End*: pairs of flags that indicate when a given processing step is active / complete (used to avoid re-entrance / recursion).
    • AreFieldsComplete, AreFieldsSorted, AreMethodsComplete, AreMethodsSorted: describes that status of arrays fields and methods
    • Has*: various diagnostics
    • Annotation*: marks when a given annotation has been applied to the element.
  • extendedTagBits (TypeBinding): overflow from tagBits, constants are in ExtendedTagBits.
    New bits should preferrably be allocated here, rather than the crowded TagBits.
  • typeBits (ReferenceBinding): classification of types, constants in TypeIds:
    • classification of resources (below Closeable), see Analysis->Black lists / white lists
    • BitUninitialized
    • BitUninternedType: classify JDT's own types TypeBinding (compiler) and ITypeBinding DOM as not suitable for reference comparison (==, !=), unless documented $IDENTITY-COMPARISON.
    • Bit*Null*Annotation: detect annotation types, configured for use by ECJ's annotation based null analysis.
    • BitMap, BitCollection, BitList: mark types which have methods with well-known problems (see UnlikelyArgumentCheck).


Synthetic Bindings

TBC

Other classes in the lookup package

the structure of this section should be improved.


Constants

  • TagBits - big bag of flags in bitset tagBits, see #Flag Vectors
  • ExtendedTagBits, see #Flag Vectors
  • ExtraCompilerModifiers - will appear in fields modifier but are never found in .class files
  • ProblemReasons - constants used in Problem*Binding
  • TypeConstants - not only type, also well-known method names etc
  • TypeIds - integer constants relating to types

Management of variants of a type binding

  • TypeSystem
    • AnnotatableTypeSystem

Type Inference

Here be draggons, read [JLS §18] first.

  • InferenceContext18 (variant InferenceContext is used only below 1.8 - not really maintained any more)
  • BoundSet
  • InferenceVariable
  • ReductionResult
    • TypeBound
    • ConstraintFormula
      • ConstraintExpressionFormula
      • ConstraintExceptionFormula
      • ConstraintTypeFormula
  • InferenceSubstitution

Scopes

see JDT Core Programmer Guide/ECJ/Lookups#Scopes


Reading .class files

  • SignatureWrapper: incremental interpretation of a signature in binary format

Visiting

  • TypeBindingVisitor


Null Annotations

  • ImplicitNullAnnotationVerifier: check if method overriding is valid wrt null annotations
  • ParameterNonNullDefaultProvider: implements the effect of @NonNullByDefault on method parameters
  • ExternalAnnotationSuperimposer: See hierarchy of org.eclipse.jdt.internal.compiler.env.ITypeAnnotationWalker.


Post-resolution computations

  • MethodVerifier
    • MethodVerifier15

Copyright © Eclipse Foundation, Inc. All Rights Reserved.