Class LockAnalysis

java.lang.Object
org.ek9lang.compiler.phase5.lockanalysis.LockAnalysis
All Implemented Interfaces:
Serializable
public final class LockAnalysis extends Object implements Serializable
Single source of truth for slice-2 deadlock analysis results.

Populated during phase 5 by LockAnalysisListener (intra-function, Phase B.1) and InterproceduralLockAnalyzer (workspace-wide mayEnter fixpoint, Phase C). Persisted on CompilableProgram for post-compilation access by MCP query tools and the IDE deadlock-detail panel.

Lifecycle: transient per-compile — each compilation rebuilds the analysis from scratch and replaces the previous instance atomically at the end of phase 5. Same lifecycle as CallGraph and the quality trackers.

Records hold direct ISymbol/IToken references for in-process navigation; string stableId fields allow cross-reference and serialisation to MCP/IDE wire formats via dedicated extractor classes.

See Also:

  • Constructor Details

    • LockAnalysis

      public LockAnalysis()

  • Method Details

    • addEnterCallSite

      public void addEnterCallSite(EnterCallSite site)

    • recordReceiverObject

      public void recordReceiverObject(String enterSiteStableId, ReceiverObjectPath object)
      Record the field-rooted receiver object for an enter site (Stage-3 Phase 2).

    • lookupReceiverObject

      public ReceiverObjectPath lookupReceiverObject(String enterSiteStableId)
      The receiver object for an enter site, or null when the lock is not field-rooted (parameter/allocation-rooted) or the object was not extracted.

    • addMutexKeyBody

      public void addMutexKeyBody(MutexKeyBody body)

    • registerLockIdentity

      public void registerLockIdentity(LockIdentityDescriptor descriptor)

    • putSummary

      public void putSummary(String functionFqn, FunctionLockSummary summary)

    • addDeadlock

      public void addDeadlock(DeadlockChain chain)

    • addCrossThreadEdge

      public void addCrossThreadEdge(CrossThreadEdge edge)

    • pairEnterSiteWithKeyBody

      public void pairEnterSiteWithKeyBody(String enterSiteId, String keyBodyId)

    • recordCallArgBindings

      public void recordCallArgBindings(String callerFqn, String calleeFqn, String sourceLocation, Map<String,String> bindings)
      Record arg→param bindings for one call edge. Used by Phase C.2 to substitute placeholder identities when composing the callee's mayEnter into the caller's summary.
      Parameters:
      callerFqn - fully-qualified name of the calling function.
      calleeFqn - fully-qualified name of the resolved target.
      sourceLocation - source-location string ("file:line:col") of the call expression — disambiguates multiple calls to the same callee from the same caller.
      bindings - map from callee parameter FQN to the caller-side identity ID resolved for the argument passed at this site.

    • lookupCallArgBindings

      public Map<String,String> lookupCallArgBindings(String callerFqn, String calleeFqn, String sourceLocation)
      Look up arg→param bindings recorded for a specific call edge. Returns an empty map if no bindings exist (defaults to "no substitution").

    • recordPureGetterReturnField

      public void recordPureGetterReturnField(String methodFqn, ISymbol returnedField)
      Record that a pure-getter method (by FQN) returns the given field symbol. Used by Phase 4's receiver inference at enter() sites where the receiver is a method-call result.

    • lookupPureGetterReturnFields

      public Set<ISymbol> lookupPureGetterReturnFields(String methodFqn)
      Look up the set of fields a pure-getter method may return. Empty set (never null) when the method either isn't a known pure getter or its return is unrecognisable.

    • lockPrecedenceGraph

      public LockPrecedenceGraph lockPrecedenceGraph()
      The workspace-wide lock-precedence graph. Populated by C.3 with "lockA held when lockB acquired" edges; SCCs of size ≥ 2 are deadlock-capable cycles.

    • lookupCallArgBindingsAggregated

      public Map<String,String> lookupCallArgBindingsAggregated(String callerFqn, String calleeFqn)

    • enterSites

      public List<EnterCallSite> enterSites()

    • keyBodies

      public List<MutexKeyBody> keyBodies()

    • identitiesById

      public Map<String, LockIdentityDescriptor> identitiesById()

    • summariesByFqn

      public Map<String, FunctionLockSummary> summariesByFqn()

    • deadlocks

      public List<DeadlockChain> deadlocks()

    • crossThreadEdges

      public List<CrossThreadEdge> crossThreadEdges()

    • keyBodyFor

      public String keyBodyFor(String enterSiteId)
      Look up the MutexKeyBody.stableId() paired with the given enter call site (if any). Returns null when the enter() call's argument isn't a MutexKey body — e.g. a non-handler call, or a handler we couldn't resolve.

    • lockIdentitiesForKeyBody

      public Set<String> lockIdentitiesForKeyBody(String keyBodyId)
      THE body-to-lock join: the lock identities a MutexKey body executes under.

      🔑 Read this, never MutexKeyBody.outerLockIdentityId() — that field is registered as the "pending" placeholder when the body is declared (the enter call that binds it has not been seen yet) and is never rewritten. The binding that IS recorded runs the other way, enter site to key body (keyBodyFor(String)), and an enter site can name more than one identity (a parameter-rooted lock may be any of several), so the honest answer is a set, not a string.

      Parameters:
      keyBodyId - the MutexKeyBody.stableId()
      Returns:
      the identity ids of every lock whose enter site passes this body, in enter-site order; empty when no enter call was paired with it

    • lookupIdentity

      public LockIdentityDescriptor lookupIdentity(String stableId)

    • lookupSummary

      public FunctionLockSummary lookupSummary(String functionFqn)

    • lookupKeyBodyById

      public MutexKeyBody lookupKeyBodyById(String stableId)

    • enterSiteCount

      public int enterSiteCount()

    • keyBodyCount

      public int keyBodyCount()

    • identityCount

      public int identityCount()

    • deadlockCount

      public int deadlockCount()

    • crossThreadEdgeCount

      public int crossThreadEdgeCount()