Class ConfinedSites

java.lang.Object
org.ek9lang.compiler.phase9.ConfinedSites

public final class ConfinedSites extends Object
THE rule of which allocation sites a CONFINE follows (N-V V1 and V3; NV_PER_SITE_CONFINEMENT.md §2, the plan's §2.2 with the review's changes and the V3 holder rule re-argued in `nv_v23/DESIGN.md`; EK9_NATIVE_CYCLE_COLLECTOR_DESIGN.md §13.11 N-V) - what ConfinePlacement places and ConfineVerifier (V-N) demands exactly, one function over FACTS the IR already carries (PublishedValues' standing under D1-a: IR_OPTIMISATION computes no fact here). Decided PER OPERATION (decide(IRConstruct, OperationInstr)): one structured walk indexes what the conditional form needs from the IR - never a second alias set - and every site is then judged.

CONFINE v, site (V1, after(IRInstr)) follows instruction S iff ALL of:

  1. S is an allocation site (IsAllocationSite: a constructor CALL that is no delegation, a LIST_LITERAL, a DICT_LITERAL) - never an owned non-constructor result, which is an EXISTING object;
  2. its per-value escape record (stamped by IR_ANALYSIS, EscapeFacts) says the object - and every view of it - is held by nothing outside the operation's frame: escapeLevel NONE or LOCAL. That level JOINS what the value may reach through a holder's other contents (mayReach, S0' F1), so a value kept into a view of a local holder that also holds a parameter or a payload is never stamped (CE-1, CE-4), and a capture is a GLOBAL reach (F2), so nothing a closure may move out is (CE-2);
  3. no holder of kind capture on the record - redundant with (2) since F2, kept as the belt the design named (NV Q5: the capturing construct's body is not followed; T4-5 moves a capture out);
  4. the emission filter (NV §3.4, Q2) on the ALLOCATED type - a constructor's target type, a literal's collection type - by name through ProgramConfinedSites: not already [confined] (its allocator stamps every object; an instruction would add nothing), not [acyclic] and not childless (never a candidate), not an enumeration (process-wide singletons), not a plain core type (the runtime's own object - a stamp on every Stdout() would churn every program for nothing a collection can reach). A core parameterisation passes when a type argument's leaf may hold a reference (List of Node, List of Any); an unknown name never does - the fail-closed direction is NO stamp;
  5. the program's fuse has not tripped (DerivationContradictions): the record's LOCAL trusts the derived RETAINS, and where the IR proves them wrong anywhere in the program no site is stamped.

CONFINE v, with, h (V3) follows a site the first form refuses iff, besides (1), (3), (4) and (5):

  1. the operation is not a construction member (a constructor, a capture constructor, _i_init, _c_init): this is not yet stamped there - the object's own site stamps it afterwards and V2 reaches its count-1 children;
  2. the record's level is FIELD or PARAMETER - every reach, mayReach included, is this or a parameter: nothing returned, published, thrown, handed to threads, captured, kept in a lock or fail-closed;
  3. the record has EXACTLY ONE holder that is not a local slot (and no slot holder that is a CALLER slot - a parameter slot assigned the value would alias it with the caller's object), and that holder is the IMMEDIATE run-time holder of the value, which the IR can name in two shapes only: (A) a direct field store BY NAME - SLOT_ASSIGN this.p, v (h = this), FIELD_ASSIGN o.f, v / STORE_FIELD o.f, v (h = o); (B) a keep BY NAME by an EXTERN member of a CORE PARAMETERISATION (List of Node, Optional of Request, ...) whose RETAINS keep that argument into its receiver (h = the receiver) or into another parameter (h = that argument) - the keep is into the runtime's own structure of that object, which nothing but the object reaches (N-C's premise). A USER callee's receiver <- p names the receiver's GRAPH, not the receiver - a part of it may be shared while the receiver is confined - so it never qualifies; nor does a keep of an ALIAS of the value, an element or constructed holder (made after the site), or a second holder of any kind;
  4. h is visible at the site: this, or a name defined by an earlier instruction of the same list or of an enclosing list of the structured walk (its register dominates the stamp);
  5. the belt: in a MutexKey body, h resolved through its loads to its base is not a CALLER slot (the payload is never stamped, so the run-time test would refuse it anyway; the IR says so).
The object is then confined exactly when h's object is, which h's own stamp says at run time - whichever object the view h turns out to be (the static ambiguity F1's mayReach records is exactly what the run-time check dissolves). A missing stamp is a leak the ledger counts; a wrong one is another thread's free against this thread's buffer - every doubt above answers "no stamp". Built once per program by ProgramConfinedSites.

The canary (withCanary(String); master plan row 5 M2 (c)): a rule that ALSO stamps every allocation site of one named type whatever the record, the filter and the fuse say - a deliberately WRONG rule, so the oracle that exists to see a wrong stamp (the checking build's forget abort, ThreadSanitizer, in the threaded seed family) can be shown to see one. It is a coordinate of a differential leg (CompilerFlags.getConfineCanaryType(), set by no door); ConfinePlacement and ConfineVerifier are handed the SAME rule, so V-N's exact check agrees with the stamp - what V-N's audit can see of it (a captured or published name) still fails the compile, which is why the canary names a type whose only sites are alias-class escapes (the CE-1 shape). Two forms: the type name alone stamps site; "with:" before it stamps with, this in every member that has a receiver ("every object of this type is confined with its maker" - the wrong holder, V3's one way to be wrong) and site elsewhere.

  • Field Details

    • WITH_CANARY_PREFIX

      public static final String WITH_CANARY_PREFIX
      The prefix of a canary type that arms the conditional form (with, this) rather than the site stamp.
      See Also:
  • Constructor Details

    • ConfinedSites

      ConfinedSites(Predicate<String> stampableType, List<String> fuseFindings, Function<CallInstr, Optional<ScopedSymbol>> calleeOf, IsMutexKeyType isMutexKeyType)
      Parameters:
      stampableType - true, by fully qualified name, for a type a site stamp can matter for (rule 4) - false for a name it does not know.
      fuseFindings - the program's derivation contradictions; any at all and no site is stamped (rule 5).
      calleeOf - THE program's callee resolution, for the conditional form's keeping call (rule 8 (B)).
      isMutexKeyType - the MutexKey test, for the belt (rule 10).
  • Method Details

    • withCanary

      public ConfinedSites withCanary(String type)
      This rule with the canary armed for one allocated type (see the class note): every allocation site of that type is stamped regardless - site, or with, this when the type is given with "with:". Null disarms it (the rule as it is).
    • canaryType

      public String canaryType()
      The type the canary is armed for (with its form prefix, if any), or null when this is the rule as shipped.
    • after

      public List<ConfineInstr> after(IRInstr instruction)
      The SITE form alone: the CONFINE v, site that must come immediately after this instruction; empty for most, and empty for a site only the conditional form can stamp (decide(IRConstruct, OperationInstr) asks both).
    • decide

      public Map<IRInstr, List<ConfineInstr>> decide(IRConstruct construct, OperationInstr operation)
      THE decision for one operation: the CONFINEs that must follow each of its instructions (an identity map; an instruction not in it is followed by none) - the site form where it applies, else the conditional form. ConfinePlacement inserts exactly these and ConfineVerifier demands exactly these.
    • allocatedType

      String allocatedType(IRInstr instruction)
      The type the site allocates: a constructor's target type, a literal's collection type; null for no site.
    • fuseTripped

      public boolean fuseTripped()
      Has the program's fuse tripped - the derivation contradicted somewhere, so no site is stamped anywhere.
    • fuseFindings

      public List<String> fuseFindings()
      The findings that tripped the fuse (E1a, E1b); empty when it holds.