Type Members

1.  final type AnalysisKey = PropertyKey[Null]
2.  class AnalysisScenario[A] extends AnyRef

   Provides functionality to determine whether a set of analyses is compatible and to compute a schedule to execute a set of analyses.

3.  final type ComputationResults = IterableOnce[SomeFinalEP]

   The result of a computation if the computation derives multiple properties at the same time.

4.  trait ComputationSpecification[A] extends AnyRef

   Specification of the properties and the life-cycle methods of a fixpoint computation (FPC) which are required when computing the correct scheduling order and actually executing the fixpoint computation.

   Specification of the properties and the life-cycle methods of a fixpoint computation (FPC) which are required when computing the correct scheduling order and actually executing the fixpoint computation.

   Note

   The PropertyStore can be used without using ComputationSpecifications and AnalysisScenarios; both latter classes just provide convenience functionality that ensures that common issues are identified early on/are avoided.

5.  sealed trait ComputationType extends AnyRef

   Determines how and when an analysis is executed.

6.  case class ContextNotAvailableException(context: AnyRef, completeContext: Map[Class[_], AnyRef]) extends RuntimeException with Product with Serializable

   Thrown if a context object is requested, but could not be found.

   Thrown if a context object is requested, but could not be found.

   Context objects are generally unrelated to entities and properties. They just store information that may be required by fixpoint computations executed using the property store.

   Note

   If the org.opalj.br.ProjectInformationKey is used to get the property store, the Project is stored in the context.

7.  final type Continuation[P <: Property] = (Entity, P) => PropertyComputationResult

   A function that continues the computation of a property.

   A function that continues the computation of a property. It takes the entity and property of the entity on which the computation depends.

8.  sealed trait EOptionP[+E <: Entity, +P <: Property] extends AnyRef

   An entity associated with the current extension of a property or None if no (preliminary) property is already computed.

9.  sealed trait EOptionPSet[E <: Entity, P <: Property] extends Iterable[EOptionP[E, P]]

   An semi-mutable set storing EPKs and interim properties.

   An semi-mutable set storing EPKs and interim properties.

   The set is semi-mutable in the sense that the concrete property values associated with a specific entity can be updated, but as soon as dependencies to other E/PKs are added or removed a new set is created; this behavior is required by the property store since the list of dependees w.r.t. the entity/property kind must not change

   The set never contains FinalEPs and can (should) therefore directly be used as the dependency set passed to InterimResults.

10.  final class EPK[+E <: Entity, +P <: Property] extends EOptionP[E, P]

    A simple pair consisting of an Entity and a PropertyKey.

11.  sealed trait EPS[+E <: Entity, +P <: Property] extends EOptionP[E, P]

    A pairing of an Entity and an associated Property along with its state.

    A pairing of an Entity and an associated Property along with its state.

    Note

    Entities and properties are compared using equals.

12.  final type Entity = AnyRef

    The type of the values stored in a property store.

    The type of the values stored in a property store.

    Basically, a simple type alias to facilitate comprehension of the code.

13.  trait ExplicitlyNamedProperty extends Property

    A property which has an explicit name.

    A property which has an explicit name. This is particularly useful when we want to refer to a property in the context of some test cases. In general, it should be tried that the name is reasonably unique w.r.t. its usage scenario.

14.  final type FallbackPropertyComputation[E <: Entity, P <: Property] = (PropertyStore, FallbackReason, E) => P

    The FallbackReason specifies the reason why a fallback property is required.

    The FallbackReason specifies the reason why a fallback property is required. This information can be used to handle situations where the fallback should be different based on the information whether a corresponding analysis was executed or not.

15.  sealed trait FallbackReason extends AnyRef

    Specifies the reason why a fallback is used.

16.  final class FinalEP[+E <: Entity, +P <: Property] extends EPS[E, P]

    Encapsulate the final property P for the entity E.

    Encapsulate the final property P for the entity E.

    For a detailed discussion of the semantics of lb and ub see EOptionP.ub.

17.  sealed abstract class FinalPropertyComputationResult extends PropertyComputationResult with ProperPropertyComputationResult

    Encapsulates the final result of the computation of a property.

    Encapsulates the final result of the computation of a property. I.e., the analysis determined that the computed property will not be updated in the future.

    A final result is only to be used if no further refinement is possible or may happen and if the bounds are correct/sound abstractions.

    Note

    The framework will invoke and deregister all dependent computations (observers). If – after having a result - another result w.r.t. the given entity and property is given to the property store the behavior is undefined and may/will result in immediate and/or deferred failures!

18.  case class IncrementalResult[E <: Entity](result: ProperPropertyComputationResult, nextComputations: Iterator[(PropertyComputation[E], E)]) extends PropertyComputationResult with ProperPropertyComputationResult with Product with Serializable

    Encapsulates some result and also some computations that should be computed next.

    Encapsulates some result and also some computations that should be computed next. In this case the property store DOES NOT guarantee that the result is processed before the next computations are triggered. Hence, nextComputations can query the e/pk related to the previous result, but should not expect to already see the value of the given result(s).

    Incremental results are particularly useful to process tree structures such as the class hierarchy.

    Note

    All computations must compute different e/pk pairs which are not yet computed/scheduled or for which lazy computations are scheduled.

    ,

    To ensure correctness it is absolutely essential that all entities - for which some property could eventually be computed - has a property before the property store reaches quiescence. Hence, it is generally not possible that a lazy computation returns IncrementalResult objects.

19.  final class InterimELBP[+E <: Entity, +P <: Property] extends InterimEP[E, P]
20.  final class InterimELUBP[+E <: Entity, +P <: Property] extends InterimEP[E, P]

    Encapsulates the intermediate lower- and upper bound related to the computation of the respective property kind for the entity E.

    Encapsulates the intermediate lower- and upper bound related to the computation of the respective property kind for the entity E.

    For a detailed discussion of the semantics of lb and ub see EOptionP.ub.

21.  sealed trait InterimEP[+E <: Entity, +P <: Property] extends EPS[E, P]
22.  final class InterimEUBP[+E <: Entity, +P <: Property] extends InterimEP[E, P]
23.  case class InterimPartialResult[SE >: Null <: Property](us: Iterable[SomePartialResult], dependees: Set[SomeEOptionP], c: OnUpdateContinuation) extends PropertyComputationResult with ProperPropertyComputationResult with Product with Serializable

    InterimPartialResults are used for properties of entities which are computed collaboratively where the individual contribution to the final result depends on the given dependees.

    InterimPartialResults are used for properties of entities which are computed collaboratively where the individual contribution to the final result depends on the given dependees. For example an analysis which analyzes a method to determine the set of all instantiated types will use an InterimPartialResult to commit those results.

24.  final class InterimResult[P >: Null <: Property] extends PropertyComputationResult with ProperPropertyComputationResult

    Encapsulates an intermediate result of the computation of a property.

    Encapsulates an intermediate result of the computation of a property.

    Intermediate results are to be used if further refinements are possible. Hence, if a property of any of the dependees changes (outgoing dependencies), the given continuation c is invoked.

    All current computations that depend on the property of the entity will be invoked.

    Note

    All elements on which the result declares to be dependent on must have been queried before (using one of the apply functions of the property store.)

25.  case class MultiResult(properties: ComputationResults) extends FinalPropertyComputationResult with Product with Serializable

    Encapsulates the final results of the computation of a set of properties.

    Encapsulates the final results of the computation of a set of properties. Hence, all results have to be w.r.t. different e/pk pairs.

    The encapsulated results are not atomically set; they are set one after another.

    See also

    FinalPropertyComputationResult for further information.

26.  final type OnUpdateContinuation = (SomeEPS) => PropertyComputationResult
27.  trait OrderedProperty extends Property

    Ordered properties make the order between all properties of a specific kind explicit; all properties that are of the same kind have to inherit from ordered property or none.

    Ordered properties make the order between all properties of a specific kind explicit; all properties that are of the same kind have to inherit from ordered property or none.

    This information is used by the property store when assertions/debugging is turned on to test if an analysis, which derives a new property, always derives a more precise property.

28.  case class PartialResult[E >: Null <: Entity, P >: Null <: Property](e: E, pk: PropertyKey[P], u: UpdateComputation[E, P]) extends PropertyComputationResult with ProperPropertyComputationResult with Product with Serializable

    PartialResults are used for properties of entities which are computed collaboratively/in a piecewise fashion.

    PartialResults are used for properties of entities which are computed collaboratively/in a piecewise fashion.

    For example, let's assume that we have an entity Project which has the property to store the types which are instantiated and which is updated whenever an analysis of a method detects the instantiation of a type. In this case, the analysis of the method could return a Results object which contains the (Intermediate)Result for the analysis of the method as such and a PartialResult which will update the information about the overall set of instantiated types.

    P

    The type of the property.

    e

    The entity for which we have a partial result.

    pk

    The kind of the property for which we have a partial result.

    u

    The function which is given the current property (if any) and which computes the new property. u has to return None if the update does not change the property and Some(NewProperty) otherwise.

29.  case class PhaseConfiguration[A](propertyKinds: PropertyKindsConfiguration, scheduled: List[ComputationSpecification[A]]) extends Product with Serializable
30.  final type ProperOnUpdateContinuation = (SomeEPS) => ProperPropertyComputationResult
31.  final type ProperPropertyComputation[E <: Entity] = (E) => ProperPropertyComputationResult
32.  trait ProperPropertyComputationResult extends PropertyComputationResult
33.  sealed abstract class PropertiesBoundType extends AnyRef

    Specifies the bounds of the properties that may be used/derived.

34.  trait Property extends PropertyMetaInformation

    An immutable information associated with an entity.

    An immutable information associated with an entity. Each property belongs to exactly one property kind specified by the PropertyKey. For details regarding the semantics of a property see EOptionP#ub.

    Implementation Requirements

    Properties have to be (effectively) immutable when passed to the framework. If a property is mutable and (by some analysis) mutated the overall results will most likely no longer be deterministic!

    Structural Equality

    Each implementation of the property trait has to implement an equals method that determines if two properties are equal.

35.  sealed abstract class PropertyBounds extends AnyRef

    Encapsulate the information about the property bounds used or derived by an analysis.

    Encapsulate the information about the property bounds used or derived by an analysis.

    Note

    Equality is only based on the PropertyKind and not on the information about the concrete bounds.

36.  final type PropertyComputation[E <: Entity] = (E) => PropertyComputationResult

    A function that takes an entity and returns a result.

    A function that takes an entity and returns a result. The result maybe:

    • the final derived property,
    • a function that will continue computing the result once the information about some other entity is available or,
    • an intermediate result which may be refined later on, but not by the current running analysis.

    Note

    In some cases it makes sense that an analysis processes entities of kind A, but derives properties related to entities with kind B. E.g., it is possible to have an analysis that processes entire classes to compute the properties of some fields. This scenario is, however, only supported by eager analyses.

37.  sealed abstract class PropertyComputationResult extends AnyRef

    Encapsulates the (intermediate) result of the computation of a property.

38.  final class PropertyKey[+P] extends AnyVal with PropertyKind

    A value object that identifies a specific kind of properties.

    A value object that identifies a specific kind of properties. Every entity in the PropertyStore must be associated with at most one property per property kind/key.

    To create a property key use one of the companion object's PropertyKey$.create method.

    When a phase finishes all values are committed using the current upper bound unless a property only has a lower bound.

39.  trait PropertyKind extends Any

    Identifies the kind of a property.

    Identifies the kind of a property.

    Generally, we distinguish between regular properties and simple properties. The latter are generally only to be used if lower bounds cannot be computed or a very extensive and are never of interest to any potential client. E.g., in case of an IFDS analysis, computing the lower bound is not meaningful; in case of a call graph analysis, the lower bound is usually either prohibitively expensive or is not usefull to any analysis.

40.  case class PropertyKindsConfiguration(propertyKindsComputedInThisPhase: Set[PropertyKind], propertyKindsComputedInLaterPhase: Set[PropertyKind] = Set.empty, suppressInterimUpdates: Map[PropertyKind, Set[PropertyKind]] = Map.empty, collaborativelyComputedPropertyKindsFinalizationOrder: List[List[PropertyKind]] = List.empty) extends Product with Serializable

    Encapsulates the configuration of an analysis phase.

    Encapsulates the configuration of an analysis phase.

    propertyKindsComputedInThisPhase

    The set of properties which will be computed in the phase. Required to determine which properties will never be computed and for which – therefore – fallbacks should be used.

    propertyKindsComputedInLaterPhase

    The set of properties computed in a later phase. Used for debugging purposes!

    suppressInterimUpdates

    Specifies for which properties updates no interim notifications shall be done. This ist generally only possible for those properties which are computed by analyses that do not take part in cyclic computations. For example,

    ps.setupPhase(
      Set(ReachableNodes.Key, ReachableNodesCount.Key),
      Set.empty,
      Map(ReachableNodesCount.Key -> Set(ReachableNodes.Key))
    )

    will suppress notifications about interim updates from ReachableNodes to ReachableNodesCount

41.  trait PropertyMetaInformation extends PropertyKind

    The meta information shared by properties and their respective kinds.

42.  abstract class PropertyStore extends AnyRef

    A property store manages the execution of computations of properties related to concrete entities as well as artificial entities (for example, methods, fields and classes of a program, but, for another example, also the call graph or the project as such).

    A property store manages the execution of computations of properties related to concrete entities as well as artificial entities (for example, methods, fields and classes of a program, but, for another example, also the call graph or the project as such). These computations may require and provide information about other entities of the store and the property store implements the logic to handle the computations related to the dependencies between the entities. Furthermore, the property store may parallelize the computation of the properties as far as possible without requiring users to take care of it; users are also generally not required to think about the concurrency when implementing an analysis as long as the properties only use immutable data-structures and the analyses only use immutable data structures when interacting the property store. The most basic concepts are also described in the SOAP paper: "Lattice Based Modularization of Static Analyses" (https://conf.researchr.org/event/issta-2018/soap-2018-papers-lattice-based-modularization-of-static-analyses)

    Usage

    The correct strategy, when using the PropertyStore, is to always continue computing the property of an entity and to collect the dependencies on those elements that are (still) relevant. I.e., if some information is not or just not completely available, the analysis should still continue using the provided information and (internally) record the dependency, by storing the returned property extension. Later on, when the analysis has computed its (interim) result, it reports the same and informs the framework about its dependencies. Based on the later the framework will call back the analysis when a dependency is updated. In general, an analysis should always try to minimize the number of dependencies to the minimum set to enable the property store to suspend computations that are no longer required.

    Core Requirements on Property Computation Functions (Modular Static Analyses)

    The following requirements ensure correctness and determinism of the result.

    • At Most One Lazy Function per Property Kind A specific kind of property is always computed by only one registered lazy PropertyComputation function. No other analysis is (conceptually) allowed to derive a value for an E/PK pairing for which a lazy function is registered. It is also not allowed to schedule a computation eagerly if a lazy computation is also registered.
    • Thread-Safe PropertyComputation functions If a single instance of a property computation function (which is the standard case) is scheduled for computing the properties of multiple entities, that function has to be thread safe. I.e., the function may be executed concurrently for different entities. The OnUpdateContinuation functions are, however, executed sequentially w.r.t. one E/PK pair. This model generally does not require that users have to think about concurrent issues as long as the initial function is actually a pure function, which is usually a non-issue.
    • Non-Overlapping Results PropertyComputation functions that are invoked on different entities have to compute result sets that are disjoint unless a PartialResult is used. For example, an analysis that performs a computation on class files and that derives properties of a specific kind related to a class file's methods must ensure that two concurrent calls of the same analysis - running concurrently on two different class files - do not derive information about the same method. If results for a specific entity are collaboratively computed, then a PartialResult has to be used.
    • If some partial result potentially contributes to the property of an entity, the first partial result has to set the property to the default (typically "most precise") value.
    • Monoton a function which computes a property has to be monotonic.

    Cyclic Dependencies

    In general, it may happen that some analyses are mutually dependent and therefore no final value is directly computed. In this case the current extension (the most precise result) of the properties are committed as the final values when the phase end. If the analyses only computed a lower bound that one will be used.

    Thread Safety

    The sequential property store is not thread-safe; the parallelized implementation enables limited concurrent access:

    • a client has to use the SAME thread (the driver thread) to call (0) set and preInitialize to initialize the property store, (1) org.opalj.fpcf.PropertyStore!.setupPhase(configuration:org\.opalj\.fpcf\.PropertyKindsConfiguration)*, (2) registerLazyPropertyComputation or registerTriggeredComputation, (3) scheduleEagerComputationForEntity / scheduleEagerComputationsForEntities, (4) force and (5) (finally) PropertyStore#waitOnPhaseCompletion. go back to (1). Hence, the previously mentioned methods MUST NOT be called by PropertyComputation/OnUpdateComputation functions. The methods to query the store (apply) are thread-safe and can be called at any time.

    Common Abbreviations

    • e = Entity
    • p = Property
    • pk = Property Key
    • pc = Property Computation
    • lpc = Lazy Property Computation
    • c = Continuation (The part of the analysis that factors in all properties of dependees)
    • EPK = Entity and a PropertyKey
    • EPS = Entity, Property and the State (final or intermediate)
    • EP = Entity and some (final or intermediate) Property
    • EOptionP = Entity and either a PropertyKey or (if available) a Property
    • ps = Property Store

    Exceptions

    In general, exceptions are only thrown if debugging is turned on due to the costs of checking for the respective violations. That is, if debugging is turned off, many potential errors leading to "incomprehensible" results will not be reported. Hence, after debugging an analysis turn debugging (and assertions!) off to get the best performance.

    We will throw IllegalArgumentException's iff a parameter is in itself invalid. E.g., the lower bound is above the upper bound. In all other cases IllegalStateExceptions are thrown. All exceptions are either thrown immediately or eventually, when PropertyStore#waitOnPhaseCompletion is called. In the latter case, the exceptions are accumulated in the first thrown exception using suppressed exceptions.

43.  class PropertyStoreContext[+T <: AnyRef] extends AnyRef

    Object stored in the PropertyStore to provide general context information.

    Object stored in the PropertyStore to provide general context information.

    Two typical objects that are stored by OPAL's subprojects in the context are:

    • the project (org.opalj.br.analysis.Project)
    • the (project dependent) configuration (com.typesafe.config.Config)
44.  trait PropertyStoreFactory[PS <: PropertyStore] extends AnyRef

    Common interface implemented by all PropertyStore factories.

45.  final type QualifiedOnUpdateContinuation[E <: Entity, P <: Property] = (EOptionP[E, P]) => ProperPropertyComputationResult
46.  case class Result(finalEP: FinalEP[Entity, Property]) extends FinalPropertyComputationResult with Product with Serializable

    Encapsulates the final result of the computation of the property p for the given entity e.

    Encapsulates the final result of the computation of the property p for the given entity e. See EOptionP#ub for a discussion related to properties.

    See also

    FinalPropertyComputationResult for further information.

47.  sealed abstract class Results extends PropertyComputationResult with ProperPropertyComputationResult

    Just a collection of multiple results.

    Just a collection of multiple results. The results have to be disjoint w.r.t. the underlying e/pk pairs for which it contains results.

48.  case class Schedule[A](batches: List[PhaseConfiguration[A]], initializationData: Map[ComputationSpecification[A], Any]) extends (PropertyStore, Boolean, (PropertyKindsConfiguration) => Unit, (List[ComputationSpecification[A]]) => Unit) => List[(ComputationSpecification[A], A)] with Product with Serializable

    Encapsulates a computed schedule and enables the execution of it.

    Encapsulates a computed schedule and enables the execution of it. Primarily takes care of calling the life-cycle methods of the analyses and setting up the phase appropriately. You can use an AnalysisScenario to compute a schedule.

    batches

    The representation of the computed schedule.

49.  trait SimpleComputationSpecification[A] extends ComputationSpecification[A]
50.  sealed abstract class SinglePropertiesBoundType extends PropertiesBoundType
51.  final type SomeEOptionP = EOptionP[_ <: Entity, _ <: Property]
52.  final type SomeEPK = EPK[_ <: Entity, _ <: Property]
53.  final type SomeEPS = EPS[_ <: Entity, _ <: Property]
54.  final type SomeFallbackPropertyComputation = Function3[PropertyStore, FallbackReason, _ <: Entity, Property]
55.  final type SomeFinalEP = FinalEP[_ <: Entity, _ <: Property]
56.  final type SomeInterimEP = InterimEP[_ <: Entity, _ <: Property]
57.  final type SomePartialResult = PartialResult[_ >: Null <: Entity, _ >: Null <: Property]
58.  final type SomeProperPropertyComputation = Function1[_ <: Entity, ProperPropertyComputationResult]
59.  final type SomePropertyComputation = Function1[_ <: Entity, PropertyComputationResult]
60.  final type SomePropertyKey = PropertyKey[_ <: Property]
61.  final type SomeUpdateComputation = (EOptionP[_$13, _$14]) => Option[InterimEP[_$13, _$14]] forSome {type _$13 <: Entity, type _$14 <: Property}
62.  case class SpecificationViolation(message: String) extends Exception with Product with Serializable
63.  final type UpdateComputation[E <: Entity, P <: Property] = (EOptionP[E, P]) => Option[InterimEP[E, P]]