Describes an interval of evaluation cardinalities. See Note [Evaluation cardinalities]

A demand describes a scaled evaluation context, e.g. how many times and how deep the denoted thing is evaluated.

The "how many" component is represented by a Cardinality. The "how deep" component is represented by a SubDemand. Examples (using Note [Demand notation]):

• seq puts demand 1A on its first argument: It evaluates the argument strictly (1), but not any deeper (A).
• fst puts demand 1P(1L,A) on its argument: It evaluates the argument pair strictly and the first component strictly, but no nested info beyond that (L). Its second argument is not used at all.
• $ puts demand 1C1(L) on its first argument: It calls (C) the argument function with one argument, exactly once (1). No info on how the result of that call is evaluated (L).
• maybe puts demand MCM(L) on its second argument: It evaluates the argument function at most once ((M)aybe) and calls it once when it is evaluated.
• fst p + fst p puts demand SP(SL,A) on p: It's 1P(1L,A) multiplied by two, so we get S (used at least once, possibly multiple times).

This data type is quite similar to Scaled SubDemand, but it's scaled by Card, which is an interval on Multiplicity, the upper bound of which could be used to infer uniqueness types.

A sub-demand describes an evaluation context, e.g. how deep the denoted thing is evaluated. See Demand for examples.

The nested SubDemand d of a Call Cn(d) is relative to a single such call. E.g. The expression f 1 2 + f 3 4 puts call demand SCS(C1(L)) on f: f is called exactly twice (S), each time exactly once (1) with an additional argument.

The nested Demands dn of a Prod P(d1,d2,...) apply absolutely: If dn is a used once demand (cf. isUsedOnce), then that means that the denoted sub-expression is used once in the entire evaluation context described by the surrounding Demand. E.g., LP(ML) means that the field of the denoted expression is used at most once, although the entire expression might be used many times.

See Note [Call demands are relative] and Note [Demand notation].

A smart constructor for Prod, applying rewrite rules along the semantic equality Prod [polyDmd n, ...] === polyDmd n, simplifying to Poly SubDemands when possible. Note that this degrades boxity information! E.g. a polymorphic demand will never unbox.

viewProd n sd interprets sd as a Prod of arity n, expanding Poly demands as necessary.

Denotes ∪ on Card.

Denotes ∪ on Demand.

Denotes ∪ on SubDemand.

Denotes + on Card.

Denotes + on Demand.

Denotes + on SubDemand.

Denotes * on Card.

True = upper bound is 0.

True = upper bound is 1.

True = lower bound is 1.

Is the value used at most once?

Not absent and used strictly. See Note [Strict demands]

Contrast with isStrictUsedDmd. See Note [Strict demands]

Used to suppress pretty-printing of an uninformative demand

We try to avoid tracking weak free variable demands in strictness signatures for analysis performance reasons. See Note [Lazy and unleashable free variables] in GHC.Core.Opt.DmdAnal.

First argument of catch#: MCM(L). Evaluates its arg lazily, but then applies it exactly once to one argument.

Second argument of catch#: MCM(C1(L)). Calls its arg lazily, but then applies it exactly once to an additional argument.

First argument of 'GHC.Exts.maskAsyncExceptions#': 1C1(L). Called exactly once.

First argument of 'GHC.Exts.atomically#': SCS(L). Called at least once, possibly many times.

Intersect with [0,1].

Make a Demand evaluated at-most-once.

Make a Demand evaluated at-least-once (e.g. strict).

If the argument is a used non-newtype dictionary, give it strict demand. Also split the product type & demand and recur in order to similarly strictify the argument's contained used non-newtype superclass dictionaries. We use the demand as our recursive measure to guarantee termination.

Peels one call level from the sub-demand, and also returns how many times we entered the lambda body.

Wraps the SubDemand with a one-shot call demand: d -> C1(d).

mkCalledOnceDmds n d returns C1(C1...(C1 d)) where there are n C1's.

See Note [Computing one-shot info]

See Note [Computing one-shot info]

saturatedByOneShots n CM(CM(...)) = True = There are at least n nested CM(..) calls. See Note [Demand on the worker] in GHC.Core.Opt.WorkWrap

keepAliveDmdType dt vs makes sure that the Ids in vs have some usage in the returned demand types -- they are not Absent. See Note [Absence analysis for stable unfoldings and RULES] in GHC.Core.Opt.DmdAnal.

Divergence characterises whether something surely diverges. Models a subset lattice of the following exhaustive set of divergence results:

n

nontermination (e.g. loops)

i

throws imprecise exception

p

throws precise exceTtion

c

converges (reduces to WHNF).

The different lattice elements correspond to different subsets, indicated by juxtaposition of indicators (e.g. nc definitely doesn't throw an exception, and may or may not reduce to WHNF).

            Dunno (nipc)
                 |
           ExnOrDiv (nip)
                 |
           Diverges (ni)

As you can see, we don't distinguish n and i. See Note [Precise exceptions and strictness analysis] for why p is so special compared to i.

True if the Divergence indicates that evaluation will not return. See Note [Dead ends].

Characterises how an expression * Evaluates its free variables (dt_env) * Evaluates its arguments (dt_args) * Diverges on every code path or not (dt_div)

The demand type of doing nothing (lazy, absent, no Divergence information). Note that it is 'not' the top of the lattice (which would be "may use everything"), so it is (no longer) called topDmdType.

Compute the least upper bound of two DmdTypes elicited /by the same incoming demand/!

When e is evaluated after executing an IO action that may throw a precise exception, we act as if there is an additional control flow path that is taken if e throws a precise exception. The demand type of this control flow path * is lazy and absent (topDmd) in all free variables and arguments * has exnDiv Divergence result So we can simply take a variant of nopDmdType, exnDmdType. Why not nopDmdType? Because then the result of e can never be exnDiv! That means failure to drop dead-ends, see #18086. See Note [Precise exceptions and strictness analysis]

See keepAliveDmdEnv.

The depth of the wrapped DmdType encodes the arity at which it is safe to unleash. Better construct this through mkStrictSigForArity. See Note [Understanding DmdType and StrictSig]

Turns a DmdType computed for the particular Arity into a StrictSig unleashable at that arity. See Note [Understanding DmdType and StrictSig]

True if the signature diverges or throws an exception in a saturated call. See Note [Dead ends].

Returns true if an application to n value args would diverge or throw an exception.

If a function having botDiv is applied to a less number of arguments than its syntactic arity, we cannot say for sure that it is going to diverge. Hence this function conservatively returns False in that case. See Note [Dead ends].

Add extra (topDmd) arguments to a strictness signature. In contrast to etaConvertStrictSig, this prepends additional argument demands. This is used by FloatOut.

We are expanding (x y. e) to (x y z. e z) or reducing from the latter to the former (when the Simplifier identifies a new join points, for example). In contrast to prependArgsStrictSig, this appends extra arg demands if necessary. This works by looking at the DmdType (which was produced under a call demand for the old arity) and trying to transfer as many facts as we can to the call demand of new arity. An arity increase (resulting in a stronger incoming demand) can retain much of the info, while an arity decrease (a weakening of the incoming demand) must fall back to a conservative default.

A demand transformer is a monotone function from an incoming evaluation context (SubDemand) to a DmdType, describing how the denoted thing (i.e. expression, function) uses its arguments and free variables, and whether it diverges.

See Note [Understanding DmdType and StrictSig] and Note [What are demand signatures?].

Extrapolate a demand signature (StrictSig) into a DmdTransformer.

Given a function's StrictSig and a SubDemand for the evaluation context, return how the function evaluates its free variables and arguments.

A special DmdTransformer for data constructors that feeds product demands into the constructor arguments.

A special DmdTransformer for dictionary selectors that feeds the demand on the result into the indicated dictionary component (if saturated).

Remove the demand environment from the signature.

Remove all `C_01 :*` info (but not CM sub-demands) from the demand

Remove all `C_01 :*` info (but not CM sub-demands) from the strictness signature