CoreSyn.hs 73.4 KB
Newer Older
Austin Seipp's avatar
Austin Seipp committed
1 2 3 4
{-
(c) The University of Glasgow 2006
(c) The GRASP/AQUA Project, Glasgow University, 1992-1998
-}
Simon Marlow's avatar
Simon Marlow committed
5

6
{-# LANGUAGE CPP, DeriveDataTypeable, DeriveFunctor #-}
Ian Lynagh's avatar
Ian Lynagh committed
7

8
-- | CoreSyn holds all the main data types for use by for the Glasgow Haskell Compiler midsection
9
module CoreSyn (
10
        -- * Main data types
Peter Wortmann's avatar
Peter Wortmann committed
11 12
        Expr(..), Alt, Bind(..), AltCon(..), Arg,
        Tickish(..), TickishScoping(..), TickishPlacement(..),
13
        CoreProgram, CoreExpr, CoreAlt, CoreBind, CoreArg, CoreBndr,
14
        TaggedExpr, TaggedAlt, TaggedBind, TaggedArg, TaggedBndr(..), deTagExpr,
15

16 17 18 19 20 21
        -- * In/Out type synonyms
        InId, InBind, InExpr, InAlt, InArg, InType, InKind,
               InBndr, InVar, InCoercion, InTyVar, InCoVar,
        OutId, OutBind, OutExpr, OutAlt, OutArg, OutType, OutKind,
               OutBndr, OutVar, OutCoercion, OutTyVar, OutCoVar,

22
        -- ** 'Expr' construction
23 24 25 26 27 28 29 30 31 32 33 34
        mkLets, mkLams,
        mkApps, mkTyApps, mkCoApps, mkVarApps,

        mkIntLit, mkIntLitInt,
        mkWordLit, mkWordLitWord,
        mkWord64LitWord64, mkInt64LitInt64,
        mkCharLit, mkStringLit,
        mkFloatLit, mkFloatLitFloat,
        mkDoubleLit, mkDoubleLitDouble,

        mkConApp, mkConApp2, mkTyBind, mkCoBind,
        varToCoreExpr, varsToCoreExprs,
35

36
        isId, cmpAltCon, cmpAlt, ltAlt,
37 38 39

        -- ** Simple 'Expr' access functions and predicates
        bindersOf, bindersOfBinds, rhssOfBind, rhssOfAlts,
40
        collectBinders, collectTyBinders, collectTyAndValBinders,
Peter Wortmann's avatar
Peter Wortmann committed
41
        collectArgs, collectArgsTicks, flattenBinds,
42

43 44 45
        exprToType, exprToCoercion_maybe,
        applyTypeToArg,

46 47
        isValArg, isTypeArg, isTyCoArg, valArgCount, valBndrCount,
        isRuntimeArg, isRuntimeVar,
48

49
        -- * Tick-related functions
Peter Wortmann's avatar
Peter Wortmann committed
50 51 52 53
        tickishCounts, tickishScoped, tickishScopesLike, tickishFloatable,
        tickishCanSplit, mkNoCount, mkNoScope,
        tickishIsCode, tickishPlace,
        tickishContains,
54 55

        -- * Unfolding data types
56 57
        Unfolding(..),  UnfoldingGuidance(..), UnfoldingSource(..),

58
        -- ** Constructing 'Unfolding's
59
        noUnfolding, bootUnfolding, evaldUnfolding, mkOtherCon,
60
        unSaturatedOk, needSaturated, boringCxtOk, boringCxtNotOk,
61 62 63 64 65

        -- ** Predicates and deconstruction on 'Unfolding'
        unfoldingTemplate, expandUnfolding_maybe,
        maybeUnfoldingTemplate, otherCons,
        isValueUnfolding, isEvaldUnfolding, isCheapUnfolding,
66
        isExpandableUnfolding, isConLikeUnfolding, isCompulsoryUnfolding,
67
        isStableUnfolding,
68
        isClosedUnfolding, hasSomeUnfolding,
69
        isBootUnfolding,
70 71 72 73
        canUnfold, neverUnfoldGuidance, isStableSource,

        -- * Annotated expression data types
        AnnExpr, AnnExpr'(..), AnnBind(..), AnnAlt,
74

Simon Marlow's avatar
Simon Marlow committed
75
        -- ** Operations on annotated expressions
Peter Wortmann's avatar
Peter Wortmann committed
76
        collectAnnArgs, collectAnnArgsTicks,
Simon Marlow's avatar
Simon Marlow committed
77

78 79 80
        -- ** Operations on annotations
        deAnnotate, deAnnotate', deAnnAlt, collectAnnBndrs,

81
        -- * Orphanhood
82
        IsOrphan(..), isOrphan, notOrphan, chooseOrphanAnchor,
83

84
        -- * Core rule data types
85
        CoreRule(..), RuleBase,
86
        RuleName, RuleFun, IdUnfoldingFun, InScopeEnv,
87
        RuleEnv(..), mkRuleEnv, emptyRuleEnv,
88

89
        -- ** Operations on 'CoreRule's
90
        ruleArity, ruleName, ruleIdName, ruleActivation,
91 92
        setRuleIdName,
        isBuiltinRule, isLocalRule, isAutoRule,
93

94 95
        -- * Core vectorisation declarations data type
        CoreVect(..)
96 97
    ) where

98
#include "HsVersions.h"
99

Simon Marlow's avatar
Simon Marlow committed
100
import CostCentre
101
import VarEnv( InScopeSet )
Simon Marlow's avatar
Simon Marlow committed
102 103 104 105
import Var
import Type
import Coercion
import Name
106
import NameSet
107
import NameEnv( NameEnv, emptyNameEnv )
Simon Marlow's avatar
Simon Marlow committed
108 109
import Literal
import DataCon
110
import Module
111
import TyCon
Simon Marlow's avatar
Simon Marlow committed
112
import BasicTypes
113
import DynFlags
114
import Outputable
twanvl's avatar
twanvl committed
115
import Util
116
import UniqFM
Peter Wortmann's avatar
Peter Wortmann committed
117
import SrcLoc     ( RealSrcSpan, containsSpan )
118
import Binary
119

120
import Data.Data hiding (TyCon)
121
import Data.Int
122 123
import Data.Word

124
infixl 4 `mkApps`, `mkTyApps`, `mkVarApps`, `App`, `mkCoApps`
125
-- Left associative, so that we can say (f `mkTyApps` xs `mkVarApps` ys)
126

Austin Seipp's avatar
Austin Seipp committed
127 128 129
{-
************************************************************************
*                                                                      *
130
\subsection{The main data types}
Austin Seipp's avatar
Austin Seipp committed
131 132
*                                                                      *
************************************************************************
133

134
These data types are the heart of the compiler
Austin Seipp's avatar
Austin Seipp committed
135
-}
136

137 138 139 140 141 142 143 144 145 146
-- | This is the data type that represents GHCs core intermediate language. Currently
-- GHC uses System FC <http://research.microsoft.com/~simonpj/papers/ext-f/> for this purpose,
-- which is closely related to the simpler and better known System F <http://en.wikipedia.org/wiki/System_F>.
--
-- We get from Haskell source to this Core language in a number of stages:
--
-- 1. The source code is parsed into an abstract syntax tree, which is represented
--    by the data type 'HsExpr.HsExpr' with the names being 'RdrName.RdrNames'
--
-- 2. This syntax tree is /renamed/, which attaches a 'Unique.Unique' to every 'RdrName.RdrName'
147
--    (yielding a 'Name.Name') to disambiguate identifiers which are lexically identical.
148 149 150 151 152 153 154 155 156 157 158 159 160
--    For example, this program:
--
-- @
--      f x = let f x = x + 1
--            in f (x - 2)
-- @
--
--    Would be renamed by having 'Unique's attached so it looked something like this:
--
-- @
--      f_1 x_2 = let f_3 x_4 = x_4 + 1
--                in f_3 (x_2 - 2)
-- @
Simon Peyton Jones's avatar
Simon Peyton Jones committed
161
--    But see Note [Shadowing] below.
162 163 164 165 166 167 168 169 170
--
-- 3. The resulting syntax tree undergoes type checking (which also deals with instantiating
--    type class arguments) to yield a 'HsExpr.HsExpr' type that has 'Id.Id' as it's names.
--
-- 4. Finally the syntax tree is /desugared/ from the expressive 'HsExpr.HsExpr' type into
--    this 'Expr' type, which has far fewer constructors and hence is easier to perform
--    optimization, analysis and code generation on.
--
-- The type parameter @b@ is for the type of binders in the expression tree.
batterseapower's avatar
batterseapower committed
171 172 173 174 175 176 177 178
--
-- The language consists of the following elements:
--
-- *  Variables
--
-- *  Primitive literals
--
-- *  Applications: note that the argument may be a 'Type'.
179 180
--    See Note [CoreSyn let/app invariant]
--    See Note [Levity polymorphism invariants]
batterseapower's avatar
batterseapower committed
181 182
--
-- *  Lambda abstraction
183
--    See Note [Levity polymorphism invariants]
batterseapower's avatar
batterseapower committed
184 185 186 187
--
-- *  Recursive and non recursive @let@s. Operationally
--    this corresponds to allocating a thunk for the things
--    bound and then executing the sub-expression.
188
--
batterseapower's avatar
batterseapower committed
189 190
--    #top_level_invariant#
--    #letrec_invariant#
191
--
batterseapower's avatar
batterseapower committed
192 193 194
--    The right hand sides of all top-level and recursive @let@s
--    /must/ be of lifted type (see "Type#type_classification" for
--    the meaning of /lifted/ vs. /unlifted/).
195
--
Simon Peyton Jones's avatar
Simon Peyton Jones committed
196
--    See Note [CoreSyn let/app invariant]
197
--    See Note [Levity polymorphism invariants]
Simon Peyton Jones's avatar
Simon Peyton Jones committed
198
--
batterseapower's avatar
batterseapower committed
199 200
--    #type_let#
--    We allow a /non-recursive/ let to bind a type variable, thus:
201
--
batterseapower's avatar
batterseapower committed
202
--    > Let (NonRec tv (Type ty)) body
203
--
batterseapower's avatar
batterseapower committed
204 205
--    This can be very convenient for postponing type substitutions until
--    the next run of the simplifier.
206
--
batterseapower's avatar
batterseapower committed
207 208 209 210
--    At the moment, the rest of the compiler only deals with type-let
--    in a Let expression, rather than at top level.  We may want to revist
--    this choice.
--
211
-- *  Case expression. Operationally this corresponds to evaluating
batterseapower's avatar
batterseapower committed
212 213 214
--    the scrutinee (expression examined) to weak head normal form
--    and then examining at most one level of resulting constructor (i.e. you
--    cannot do nested pattern matching directly with this).
215
--
batterseapower's avatar
batterseapower committed
216 217
--    The binder gets bound to the value of the scrutinee,
--    and the 'Type' must be that of all the case alternatives
218
--
batterseapower's avatar
batterseapower committed
219
--    #case_invariants#
220
--    This is one of the more complicated elements of the Core language,
batterseapower's avatar
batterseapower committed
221
--    and comes with a number of restrictions:
222 223
--
--    1. The list of alternatives may be empty;
224
--       See Note [Empty case alternatives]
Simon Peyton Jones's avatar
Simon Peyton Jones committed
225
--
226
--    2. The 'DEFAULT' case alternative must be first in the list,
Simon Peyton Jones's avatar
Simon Peyton Jones committed
227
--       if it occurs at all.
228 229 230 231 232
--
--    3. The remaining cases are in order of increasing
--         tag  (for 'DataAlts') or
--         lit  (for 'LitAlts').
--       This makes finding the relevant constructor easy,
Simon Peyton Jones's avatar
Simon Peyton Jones committed
233
--       and makes comparison easier too.
234 235
--
--    4. The list of alternatives must be exhaustive. An /exhaustive/ case
Simon Peyton Jones's avatar
Simon Peyton Jones committed
236
--       does not necessarily mention all constructors:
batterseapower's avatar
batterseapower committed
237
--
238 239 240 241 242 243 244 245 246 247 248 249
--       @
--            data Foo = Red | Green | Blue
--       ... case x of
--            Red   -> True
--            other -> f (case x of
--                            Green -> ...
--                            Blue  -> ... ) ...
--       @
--
--       The inner case does not need a @Red@ alternative, because @x@
--       can't be @Red@ at that program point.
--
Ben Gamari's avatar
Ben Gamari committed
250 251 252 253
--    5. Floating-point values must not be scrutinised against literals.
--       See Trac #9238 and Note [Rules for floating-point comparisons]
--       in PrelRules for rationale.
--
254 255
-- *  Cast an expression to a particular type.
--    This is used to implement @newtype@s (a @newtype@ constructor or
batterseapower's avatar
batterseapower committed
256 257 258 259 260 261 262 263
--    destructor just becomes a 'Cast' in Core) and GADTs.
--
-- *  Notes. These allow general information to be added to expressions
--    in the syntax tree
--
-- *  A type: this should only show up at the top level of an Arg
--
-- *  A coercion
264 265

-- If you edit this type, you may need to update the GHC formalism
266
-- See Note [GHC Formalism] in coreSyn/CoreLint.hs
267
data Expr b
268
  = Var   Id
batterseapower's avatar
batterseapower committed
269 270 271 272
  | Lit   Literal
  | App   (Expr b) (Arg b)
  | Lam   b (Expr b)
  | Let   (Bind b) (Expr b)
273
  | Case  (Expr b) b Type [Alt b]       -- See #case_invariant#
batterseapower's avatar
batterseapower committed
274
  | Cast  (Expr b) Coercion
275
  | Tick  (Tickish Id) (Expr b)
batterseapower's avatar
batterseapower committed
276 277
  | Type  Type
  | Coercion Coercion
278
  deriving Data
279 280 281 282 283 284 285 286

-- | Type synonym for expressions that occur in function argument positions.
-- Only 'Arg' should contain a 'Type' at top level, general 'Expr' should not
type Arg b = Expr b

-- | A case split alternative. Consists of the constructor leading to the alternative,
-- the variables bound from the constructor, and the expression to be executed given that binding.
-- The default alternative is @(DEFAULT, [], rhs)@
287 288

-- If you edit this type, you may need to update the GHC formalism
289
-- See Note [GHC Formalism] in coreSyn/CoreLint.hs
290 291 292
type Alt b = (AltCon, [b], Expr b)

-- | A case alternative constructor (i.e. pattern match)
293 294

-- If you edit this type, you may need to update the GHC formalism
295
-- See Note [GHC Formalism] in coreSyn/CoreLint.hs
296
data AltCon
297 298 299 300 301
  = DataAlt DataCon   --  ^ A plain data constructor: @case e of { Foo x -> ... }@.
                      -- Invariant: the 'DataCon' is always from a @data@ type, and never from a @newtype@

  | LitAlt  Literal   -- ^ A literal: @case e of { 1 -> ... }@
                      -- Invariant: always an *unlifted* literal
302 303
                      -- See Note [Literal alternatives]

304
  | DEFAULT           -- ^ Trivial alternative: @case e of { _ -> ... }@
niteria's avatar
niteria committed
305
   deriving (Eq, Data)
306

307
-- | Binding, used for top level bindings in a module and local bindings in a @let@.
308 309

-- If you edit this type, you may need to update the GHC formalism
310
-- See Note [GHC Formalism] in coreSyn/CoreLint.hs
311
data Bind b = NonRec b (Expr b)
312
            | Rec [(b, (Expr b))]
313
  deriving Data
314

Austin Seipp's avatar
Austin Seipp committed
315
{-
Simon Peyton Jones's avatar
Simon Peyton Jones committed
316 317 318 319 320 321 322 323 324 325 326 327 328
Note [Shadowing]
~~~~~~~~~~~~~~~~
While various passes attempt to rename on-the-fly in a manner that
avoids "shadowing" (thereby simplifying downstream optimizations),
neither the simplifier nor any other pass GUARANTEES that shadowing is
avoided. Thus, all passes SHOULD work fine even in the presence of
arbitrary shadowing in their inputs.

In particular, scrutinee variables `x` in expressions of the form
`Case e x t` are often renamed to variables with a prefix
"wild_". These "wild" variables may appear in the body of the
case-expression, and further, may be shadowed within the body.

Simon Peyton Jones's avatar
Simon Peyton Jones committed
329 330 331 332 333 334 335
So the Unique in an Var is not really unique at all.  Still, it's very
useful to give a constant-time equality/ordering for Vars, and to give
a key that can be used to make sets of Vars (VarSet), or mappings from
Vars to other things (VarEnv).   Moreover, if you do want to eliminate
shadowing, you can give a new Unique to an Id without changing its
printable name, which makes debugging easier.

336 337 338 339 340 341 342 343 344 345 346 347 348 349
Note [Literal alternatives]
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Literal alternatives (LitAlt lit) are always for *un-lifted* literals.
We have one literal, a literal Integer, that is lifted, and we don't
allow in a LitAlt, because LitAlt cases don't do any evaluation. Also
(see Trac #5603) if you say
    case 3 of
      S# x -> ...
      J# _ _ -> ...
(where S#, J# are the constructors for Integer) we don't want the
simplifier calling findAlt with argument (LitAlt 3).  No no.  Integer
literals are an opaque encoding of an algebraic data type, not of
an unlifted literal, like all the others.

Ben Gamari's avatar
Ben Gamari committed
350 351 352
Also, we do not permit case analysis with literal patterns on floating-point
types. See Trac #9238 and Note [Rules for floating-point comparisons] in
PrelRules for the rationale for this restriction.
353

354 355 356 357
-------------------------- CoreSyn INVARIANTS ---------------------------

Note [CoreSyn top-level invariant]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
358
See #toplevel_invariant#
359 360 361

Note [CoreSyn letrec invariant]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362
See #letrec_invariant#
363 364 365

Note [CoreSyn let/app invariant]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Simon Peyton Jones's avatar
Simon Peyton Jones committed
366
The let/app invariant
Javran Cheng's avatar
Javran Cheng committed
367
     the right hand side of a non-recursive 'Let', and
Simon Peyton Jones's avatar
Simon Peyton Jones committed
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
     the argument of an 'App',
    /may/ be of unlifted type, but only if
    the expression is ok-for-speculation.

This means that the let can be floated around
without difficulty. For example, this is OK:

   y::Int# = x +# 1#

But this is not, as it may affect termination if the
expression is floated out:

   y::Int# = fac 4#

In this situation you should use @case@ rather than a @let@. The function
'CoreUtils.needsCaseBinding' can help you determine which to generate, or
alternatively use 'MkCore.mkCoreLet' rather than this constructor directly,
which will generate a @case@ if necessary
386

387 388
The let/app invariant is initially enforced by mkCoreLet and mkCoreApp in
coreSyn/MkCore.
389 390 391

Note [CoreSyn case invariants]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
392
See #case_invariants#
393

394 395 396 397 398 399 400 401 402 403
Note [Levity polymorphism invariants]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The levity-polymorphism invariants are these:

* The type of a term-binder must not be levity-polymorphic
* The type of the argument of an App must not be levity-polymorphic.

A type (t::TYPE r) is "levity polymorphic" if 'r' has any free variables.

For example
404
  \(r::RuntimeRep). \(a::TYPE r). \(x::a). e
405 406
is illegal because x's type has kind (TYPE r), which has 'r' free.

407
Note [CoreSyn let goal]
408
~~~~~~~~~~~~~~~~~~~~~~~
409 410 411 412
* The simplifier tries to ensure that if the RHS of a let is a constructor
  application, its arguments are trivial, so that the constructor can be
  inlined vigorously.

413 414
Note [Type let]
~~~~~~~~~~~~~~~
415
See #type_let#
416

417 418
Note [Empty case alternatives]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Simon Peyton Jones's avatar
Simon Peyton Jones committed
419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444
The alternatives of a case expression should be exhaustive.  But
this exhaustive list can be empty!

* A case expression can have empty alternatives if (and only if) the
  scrutinee is bound to raise an exception or diverge. When do we know
  this?  See Note [Bottoming expressions] in CoreUtils.

* The possiblity of empty alternatives is one reason we need a type on
  the case expression: if the alternatives are empty we can't get the
  type from the alternatives!

* In the case of empty types (see Note [Bottoming expressions]), say
    data T
  we do NOT want to replace
    case (x::T) of Bool {}   -->   error Bool "Inaccessible case"
  because x might raise an exception, and *that*'s what we want to see!
  (Trac #6067 is an example.) To preserve semantics we'd have to say
     x `seq` error Bool "Inaccessible case"
  but the 'seq' is just a case, so we are back to square 1.  Or I suppose
  we could say
     x |> UnsafeCoerce T Bool
  but that loses all trace of the fact that this originated with an empty
  set of alternatives.

* We can use the empty-alternative construct to coerce error values from
  one type to another.  For example
445 446 447

    f :: Int -> Int
    f n = error "urk"
448

449 450 451
    g :: Int -> (# Char, Bool #)
    g x = case f x of { 0 -> ..., n -> ... }

Simon Peyton Jones's avatar
Simon Peyton Jones committed
452
  Then if we inline f in g's RHS we get
453
    case (error Int "urk") of (# Char, Bool #) { ... }
Simon Peyton Jones's avatar
Simon Peyton Jones committed
454
  and we can discard the alternatives since the scrutinee is bottom to give
455 456
    case (error Int "urk") of (# Char, Bool #) {}

Simon Peyton Jones's avatar
Simon Peyton Jones committed
457 458 459 460 461 462 463 464 465 466 467
  This is nicer than using an unsafe coerce between Int ~ (# Char,Bool #),
  if for no other reason that we don't need to instantiate the (~) at an
  unboxed type.

* We treat a case expression with empty alternatives as trivial iff
  its scrutinee is (see CoreUtils.exprIsTrivial).  This is actually
  important; see Note [Empty case is trivial] in CoreUtils

* An empty case is replaced by its scrutinee during the CoreToStg
  conversion; remember STG is un-typed, so there is no need for
  the empty case to do the type conversion.
468 469


Austin Seipp's avatar
Austin Seipp committed
470
************************************************************************
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
*                                                                      *
            In/Out type synonyms
*                                                                      *
********************************************************************* -}

{- Many passes apply a substitution, and it's very handy to have type
   synonyms to remind us whether or not the subsitution has been applied -}

-- Pre-cloning or substitution
type InBndr     = CoreBndr
type InType     = Type
type InKind     = Kind
type InBind     = CoreBind
type InExpr     = CoreExpr
type InAlt      = CoreAlt
type InArg      = CoreArg
type InCoercion = Coercion

-- Post-cloning or substitution
type OutBndr     = CoreBndr
type OutType     = Type
type OutKind     = Kind
type OutCoercion = Coercion
type OutBind     = CoreBind
type OutExpr     = CoreExpr
type OutAlt      = CoreAlt
type OutArg      = CoreArg


{- *********************************************************************
Austin Seipp's avatar
Austin Seipp committed
501
*                                                                      *
Simon Peyton Jones's avatar
Simon Peyton Jones committed
502
              Ticks
Austin Seipp's avatar
Austin Seipp committed
503 504 505
*                                                                      *
************************************************************************
-}
Simon Peyton Jones's avatar
Simon Peyton Jones committed
506

507
-- | Allows attaching extra information to points in expressions
508 509

-- If you edit this type, you may need to update the GHC formalism
510
-- See Note [GHC Formalism] in coreSyn/CoreLint.hs
511 512 513 514 515 516 517 518 519 520
data Tickish id =
    -- | An @{-# SCC #-}@ profiling annotation, either automatically
    -- added by the desugarer as a result of -auto-all, or added by
    -- the user.
    ProfNote {
      profNoteCC    :: CostCentre, -- ^ the cost centre
      profNoteCount :: !Bool,      -- ^ bump the entry count?
      profNoteScope :: !Bool       -- ^ scopes over the enclosed expression
                                   -- (i.e. not just a tick)
    }
521

522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544
  -- | A "tick" used by HPC to track the execution of each
  -- subexpression in the original source code.
  | HpcTick {
      tickModule :: Module,
      tickId     :: !Int
    }

  -- | A breakpoint for the GHCi debugger.  This behaves like an HPC
  -- tick, but has a list of free variables which will be available
  -- for inspection in GHCi when the program stops at the breakpoint.
  --
  -- NB. we must take account of these Ids when (a) counting free variables,
  -- and (b) substituting (don't substitute for them)
  | Breakpoint
    { breakpointId     :: !Int
    , breakpointFVs    :: [id]  -- ^ the order of this list is important:
                                -- it matches the order of the lists in the
                                -- appropriate entry in HscTypes.ModBreaks.
                                --
                                -- Careful about substitution!  See
                                -- Note [substTickish] in CoreSubst.
    }

Peter Wortmann's avatar
Peter Wortmann committed
545 546 547 548 549 550 551 552 553 554 555 556 557 558 559
  -- | A source note.
  --
  -- Source notes are pure annotations: Their presence should neither
  -- influence compilation nor execution. The semantics are given by
  -- causality: The presence of a source note means that a local
  -- change in the referenced source code span will possibly provoke
  -- the generated code to change. On the flip-side, the functionality
  -- of annotated code *must* be invariant against changes to all
  -- source code *except* the spans referenced in the source notes
  -- (see "Causality of optimized Haskell" paper for details).
  --
  -- Therefore extending the scope of any given source note is always
  -- valid. Note that it is still undesirable though, as this reduces
  -- their usefulness for debugging and profiling. Therefore we will
  -- generally try only to make use of this property where it is
560
  -- necessary to enable optimizations.
Peter Wortmann's avatar
Peter Wortmann committed
561 562 563 564 565 566
  | SourceNote
    { sourceSpan :: RealSrcSpan -- ^ Source covered
    , sourceName :: String      -- ^ Name for source location
                                --   (uses same names as CCs)
    }

567
  deriving (Eq, Ord, Data)
568

Simon Marlow's avatar
Simon Marlow committed
569 570 571 572
-- | A "counting tick" (where tickishCounts is True) is one that
-- counts evaluations in some way.  We cannot discard a counting tick,
-- and the compiler should preserve the number of counting ticks as
-- far as possible.
573
--
Gabor Greif's avatar
Gabor Greif committed
574
-- However, we still allow the simplifier to increase or decrease
575 576 577 578 579 580
-- sharing, so in practice the actual number of ticks may vary, except
-- that we never change the value from zero to non-zero or vice versa.
tickishCounts :: Tickish id -> Bool
tickishCounts n@ProfNote{} = profNoteCount n
tickishCounts HpcTick{}    = True
tickishCounts Breakpoint{} = True
Peter Wortmann's avatar
Peter Wortmann committed
581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651
tickishCounts _            = False


-- | Specifies the scoping behaviour of ticks. This governs the
-- behaviour of ticks that care about the covered code and the cost
-- associated with it. Important for ticks relating to profiling.
data TickishScoping =
    -- | No scoping: The tick does not care about what code it
    -- covers. Transformations can freely move code inside as well as
    -- outside without any additional annotation obligations
    NoScope

    -- | Soft scoping: We want all code that is covered to stay
    -- covered.  Note that this scope type does not forbid
    -- transformations from happening, as as long as all results of
    -- the transformations are still covered by this tick or a copy of
    -- it. For example
    --
    --   let x = tick<...> (let y = foo in bar) in baz
    --     ===>
    --   let x = tick<...> bar; y = tick<...> foo in baz
    --
    -- Is a valid transformation as far as "bar" and "foo" is
    -- concerned, because both still are scoped over by the tick.
    --
    -- Note though that one might object to the "let" not being
    -- covered by the tick any more. However, we are generally lax
    -- with this - constant costs don't matter too much, and given
    -- that the "let" was effectively merged we can view it as having
    -- lost its identity anyway.
    --
    -- Also note that this scoping behaviour allows floating a tick
    -- "upwards" in pretty much any situation. For example:
    --
    --   case foo of x -> tick<...> bar
    --     ==>
    --   tick<...> case foo of x -> bar
    --
    -- While this is always leagl, we want to make a best effort to
    -- only make us of this where it exposes transformation
    -- opportunities.
  | SoftScope

    -- | Cost centre scoping: We don't want any costs to move to other
    -- cost-centre stacks. This means we not only want no code or cost
    -- to get moved out of their cost centres, but we also object to
    -- code getting associated with new cost-centre ticks - or
    -- changing the order in which they get applied.
    --
    -- A rule of thumb is that we don't want any code to gain new
    -- annotations. However, there are notable exceptions, for
    -- example:
    --
    --   let f = \y -> foo in tick<...> ... (f x) ...
    --     ==>
    --   tick<...> ... foo[x/y] ...
    --
    -- In-lining lambdas like this is always legal, because inlining a
    -- function does not change the cost-centre stack when the
    -- function is called.
  | CostCentreScope

  deriving (Eq)

-- | Returns the intended scoping rule for a Tickish
tickishScoped :: Tickish id -> TickishScoping
tickishScoped n@ProfNote{}
  | profNoteScope n        = CostCentreScope
  | otherwise              = NoScope
tickishScoped HpcTick{}    = NoScope
tickishScoped Breakpoint{} = CostCentreScope
652 653 654
   -- Breakpoints are scoped: eventually we're going to do call
   -- stacks, but also this helps prevent the simplifier from moving
   -- breakpoints around and changing their result type (see #1531).
Peter Wortmann's avatar
Peter Wortmann committed
655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687
tickishScoped SourceNote{} = SoftScope

-- | Returns whether the tick scoping rule is at least as permissive
-- as the given scoping rule.
tickishScopesLike :: Tickish id -> TickishScoping -> Bool
tickishScopesLike t scope = tickishScoped t `like` scope
  where NoScope         `like` _               = True
        _               `like` NoScope         = False
        SoftScope       `like` _               = True
        _               `like` SoftScope       = False
        CostCentreScope `like` _               = True

-- | Returns @True@ for ticks that can be floated upwards easily even
-- where it might change execution counts, such as:
--
--   Just (tick<...> foo)
--     ==>
--   tick<...> (Just foo)
--
-- This is a combination of @tickishSoftScope@ and
-- @tickishCounts@. Note that in principle splittable ticks can become
-- floatable using @mkNoTick@ -- even though there's currently no
-- tickish for which that is the case.
tickishFloatable :: Tickish id -> Bool
tickishFloatable t = t `tickishScopesLike` SoftScope && not (tickishCounts t)

-- | Returns @True@ for a tick that is both counting /and/ scoping and
-- can be split into its (tick, scope) parts using 'mkNoScope' and
-- 'mkNoTick' respectively.
tickishCanSplit :: Tickish id -> Bool
tickishCanSplit ProfNote{profNoteScope = True, profNoteCount = True}
                   = True
tickishCanSplit _  = False
688

Simon Marlow's avatar
Simon Marlow committed
689
mkNoCount :: Tickish id -> Tickish id
Peter Wortmann's avatar
Peter Wortmann committed
690 691 692 693
mkNoCount n | not (tickishCounts n)   = n
            | not (tickishCanSplit n) = panic "mkNoCount: Cannot split!"
mkNoCount n@ProfNote{}                = n {profNoteCount = False}
mkNoCount _                           = panic "mkNoCount: Undefined split!"
694 695

mkNoScope :: Tickish id -> Tickish id
Peter Wortmann's avatar
Peter Wortmann committed
696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715
mkNoScope n | tickishScoped n == NoScope  = n
            | not (tickishCanSplit n)     = panic "mkNoScope: Cannot split!"
mkNoScope n@ProfNote{}                    = n {profNoteScope = False}
mkNoScope _                               = panic "mkNoScope: Undefined split!"

-- | Return @True@ if this source annotation compiles to some backend
-- code. Without this flag, the tickish is seen as a simple annotation
-- that does not have any associated evaluation code.
--
-- What this means that we are allowed to disregard the tick if doing
-- so means that we can skip generating any code in the first place. A
-- typical example is top-level bindings:
--
--   foo = tick<...> \y -> ...
--     ==>
--   foo = \y -> tick<...> ...
--
-- Here there is just no operational difference between the first and
-- the second version. Therefore code generation should simply
-- translate the code as if it found the latter.
716
tickishIsCode :: Tickish id -> Bool
Peter Wortmann's avatar
Peter Wortmann committed
717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770
tickishIsCode SourceNote{} = False
tickishIsCode _tickish     = True  -- all the rest for now


-- | Governs the kind of expression that the tick gets placed on when
-- annotating for example using @mkTick@. If we find that we want to
-- put a tickish on an expression ruled out here, we try to float it
-- inwards until we find a suitable expression.
data TickishPlacement =

    -- | Place ticks exactly on run-time expressions. We can still
    -- move the tick through pure compile-time constructs such as
    -- other ticks, casts or type lambdas. This is the most
    -- restrictive placement rule for ticks, as all tickishs have in
    -- common that they want to track runtime processes. The only
    -- legal placement rule for counting ticks.
    PlaceRuntime

    -- | As @PlaceRuntime@, but we float the tick through all
    -- lambdas. This makes sense where there is little difference
    -- between annotating the lambda and annotating the lambda's code.
  | PlaceNonLam

    -- | In addition to floating through lambdas, cost-centre style
    -- tickishs can also be moved from constructors, non-function
    -- variables and literals. For example:
    --
    --   let x = scc<...> C (scc<...> y) (scc<...> 3) in ...
    --
    -- Neither the constructor application, the variable or the
    -- literal are likely to have any cost worth mentioning. And even
    -- if y names a thunk, the call would not care about the
    -- evaluation context. Therefore removing all annotations in the
    -- above example is safe.
  | PlaceCostCentre

  deriving (Eq)

-- | Placement behaviour we want for the ticks
tickishPlace :: Tickish id -> TickishPlacement
tickishPlace n@ProfNote{}
  | profNoteCount n        = PlaceRuntime
  | otherwise              = PlaceCostCentre
tickishPlace HpcTick{}     = PlaceRuntime
tickishPlace Breakpoint{}  = PlaceRuntime
tickishPlace SourceNote{}  = PlaceNonLam

-- | Returns whether one tick "contains" the other one, therefore
-- making the second tick redundant.
tickishContains :: Eq b => Tickish b -> Tickish b -> Bool
tickishContains (SourceNote sp1 n1) (SourceNote sp2 n2)
  = n1 == n2 && containsSpan sp1 sp2
tickishContains t1 t2
  = t1 == t2
771

772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787
{-
************************************************************************
*                                                                      *
                Orphans
*                                                                      *
************************************************************************
-}

-- | Is this instance an orphan?  If it is not an orphan, contains an 'OccName'
-- witnessing the instance's non-orphanhood.
-- See Note [Orphans]
data IsOrphan
  = IsOrphan
  | NotOrphan OccName -- The OccName 'n' witnesses the instance's non-orphanhood
                      -- In that case, the instance is fingerprinted as part
                      -- of the definition of 'n's definition
788
    deriving Data
789 790 791 792 793 794 795 796 797 798 799

-- | Returns true if 'IsOrphan' is orphan.
isOrphan :: IsOrphan -> Bool
isOrphan IsOrphan = True
isOrphan _ = False

-- | Returns true if 'IsOrphan' is not an orphan.
notOrphan :: IsOrphan -> Bool
notOrphan NotOrphan{} = True
notOrphan _ = False

800
chooseOrphanAnchor :: NameSet -> IsOrphan
801 802 803 804 805 806 807 808 809
-- Something (rule, instance) is relate to all the Names in this
-- list. Choose one of them to be an "anchor" for the orphan.  We make
-- the choice deterministic to avoid gratuitious changes in the ABI
-- hash (Trac #4012).  Specficially, use lexicographic comparison of
-- OccName rather than comparing Uniques
--
-- NB: 'minimum' use Ord, and (Ord OccName) works lexicographically
--
chooseOrphanAnchor local_names
810 811
  | isEmptyNameSet local_names = IsOrphan
  | otherwise                  = NotOrphan (minimum occs)
812
  where
813 814
    occs = map nameOccName $ nonDetEltsUFM local_names
    -- It's OK to use nonDetEltsUFM here, see comments above
815

816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865
instance Binary IsOrphan where
    put_ bh IsOrphan = putByte bh 0
    put_ bh (NotOrphan n) = do
        putByte bh 1
        put_ bh n
    get bh = do
        h <- getByte bh
        case h of
            0 -> return IsOrphan
            _ -> do
                n <- get bh
                return $ NotOrphan n

{-
Note [Orphans]
~~~~~~~~~~~~~~
Class instances, rules, and family instances are divided into orphans
and non-orphans.  Roughly speaking, an instance/rule is an orphan if
its left hand side mentions nothing defined in this module.  Orphan-hood
has two major consequences

 * A module that contains orphans is called an "orphan module".  If
   the module being compiled depends (transitively) on an oprhan
   module M, then M.hi is read in regardless of whether M is oherwise
   needed. This is to ensure that we don't miss any instance decls in
   M.  But it's painful, because it means we need to keep track of all
   the orphan modules below us.

 * A non-orphan is not finger-printed separately.  Instead, for
   fingerprinting purposes it is treated as part of the entity it
   mentions on the LHS.  For example
      data T = T1 | T2
      instance Eq T where ....
   The instance (Eq T) is incorprated as part of T's fingerprint.

   In constrast, orphans are all fingerprinted together in the
   mi_orph_hash field of the ModIface.

   See MkIface.addFingerprints.

Orphan-hood is computed
  * For class instances:
      when we make a ClsInst
    (because it is needed during instance lookup)

  * For rules and family instances:
       when we generate an IfaceRule (MkIface.coreRuleToIfaceRule)
                     or IfaceFamInst (MkIface.instanceToIfaceInst)
-}

Austin Seipp's avatar
Austin Seipp committed
866 867 868
{-
************************************************************************
*                                                                      *
869
\subsection{Transformation rules}
Austin Seipp's avatar
Austin Seipp committed
870 871
*                                                                      *
************************************************************************
872 873 874

The CoreRule type and its friends are dealt with mainly in CoreRules,
but CoreFVs, Subst, PprCore, CoreTidy also inspect the representation.
Austin Seipp's avatar
Austin Seipp committed
875
-}
876

877 878
-- | Gathers a collection of 'CoreRule's. Maps (the name of) an 'Id' to its rules
type RuleBase = NameEnv [CoreRule]
Gabor Greif's avatar
Gabor Greif committed
879
        -- The rules are unordered;
880 881
        -- we sort out any overlaps on lookup

882 883 884 885 886 887 888 889 890 891 892 893 894 895
-- | A full rule environment which we can apply rules from.  Like a 'RuleBase',
-- but it also includes the set of visible orphans we use to filter out orphan
-- rules which are not visible (even though we can see them...)
data RuleEnv
    = RuleEnv { re_base          :: RuleBase
              , re_visible_orphs :: ModuleSet
              }

mkRuleEnv :: RuleBase -> [Module] -> RuleEnv
mkRuleEnv rules vis_orphs = RuleEnv rules (mkModuleSet vis_orphs)

emptyRuleEnv :: RuleEnv
emptyRuleEnv = RuleEnv emptyNameEnv emptyModuleSet

896 897 898 899 900 901 902
-- | A 'CoreRule' is:
--
-- * \"Local\" if the function it is a rule for is defined in the
--   same module as the rule itself.
--
-- * \"Orphan\" if nothing on the LHS is defined in the same module
--   as the rule itself
903
data CoreRule
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923
  = Rule {
        ru_name :: RuleName,            -- ^ Name of the rule, for communication with the user
        ru_act  :: Activation,          -- ^ When the rule is active

        -- Rough-matching stuff
        -- see comments with InstEnv.ClsInst( is_cls, is_rough )
        ru_fn    :: Name,               -- ^ Name of the 'Id.Id' at the head of this rule
        ru_rough :: [Maybe Name],       -- ^ Name at the head of each argument to the left hand side

        -- Proper-matching stuff
        -- see comments with InstEnv.ClsInst( is_tvs, is_tys )
        ru_bndrs :: [CoreBndr],         -- ^ Variables quantified over
        ru_args  :: [CoreExpr],         -- ^ Left hand side arguments

        -- And the right-hand side
        ru_rhs   :: CoreExpr,           -- ^ Right hand side of the rule
                                        -- Occurrence info is guaranteed correct
                                        -- See Note [OccInfo in unfoldings and rules]

        -- Locality
Simon Peyton Jones's avatar
Simon Peyton Jones committed
924 925 926 927 928
        ru_auto :: Bool,   -- ^ @True@  <=> this rule is auto-generated
                           --               (notably by Specialise or SpecConstr)
                           --   @False@ <=> generated at the users behest
                           -- See Note [Trimming auto-rules] in TidyPgm
                           -- for the sole purpose of this field.
929

Simon Peyton Jones's avatar
Simon Peyton Jones committed
930
        ru_origin :: !Module,   -- ^ 'Module' the rule was defined in, used
931 932
                                -- to test if we should see an orphan rule.

Simon Peyton Jones's avatar
Simon Peyton Jones committed
933
        ru_orphan :: !IsOrphan, -- ^ Whether or not the rule is an orphan.
934

935 936 937
        ru_local :: Bool        -- ^ @True@ iff the fn at the head of the rule is
                                -- defined in the same module as the rule
                                -- and is not an implicit 'Id' (like a record selector,
938 939 940 941 942
                                -- class operation, or data constructor).  This
                                -- is different from 'ru_orphan', where a rule
                                -- can avoid being an orphan if *any* Name in
                                -- LHS of the rule was defined in the same
                                -- module as the rule.
943
    }
944

945 946
  -- | Built-in rules are used for constant folding
  -- and suchlike.  They have no free variables.
947 948
  -- A built-in rule is always visible (there is no such thing as
  -- an orphan built-in rule.)
949 950 951 952 953 954 955 956 957
  | BuiltinRule {
        ru_name  :: RuleName,   -- ^ As above
        ru_fn    :: Name,       -- ^ As above
        ru_nargs :: Int,        -- ^ Number of arguments that 'ru_try' consumes,
                                -- if it fires, including type arguments
        ru_try   :: RuleFun
                -- ^ This function does the rewrite.  It given too many
                -- arguments, it simply discards them; the returned 'CoreExpr'
                -- is just the rewrite of 'ru_fn' applied to the first 'ru_nargs' args
958
    }
959
                -- See Note [Extra args in rule matching] in Rules.hs
960

961 962 963
type RuleFun = DynFlags -> InScopeEnv -> Id -> [CoreExpr] -> Maybe CoreExpr
type InScopeEnv = (InScopeSet, IdUnfoldingFun)

964 965 966 967 968
type IdUnfoldingFun = Id -> Unfolding
-- A function that embodies how to unfold an Id if you need
-- to do that in the Rule.  The reason we need to pass this info in
-- is that whether an Id is unfoldable depends on the simplifier phase

twanvl's avatar
twanvl committed
969
isBuiltinRule :: CoreRule -> Bool
970
isBuiltinRule (BuiltinRule {}) = True
971
isBuiltinRule _                = False
972

973 974 975 976
isAutoRule :: CoreRule -> Bool
isAutoRule (BuiltinRule {}) = False
isAutoRule (Rule { ru_auto = is_auto }) = is_auto

977
-- | The number of arguments the 'ru_fn' must be applied
978
-- to before the rule can match on it
979 980 981 982
ruleArity :: CoreRule -> Int
ruleArity (BuiltinRule {ru_nargs = n}) = n
ruleArity (Rule {ru_args = args})      = length args

983 984
ruleName :: CoreRule -> RuleName
ruleName = ru_name
985

986 987 988
ruleActivation :: CoreRule -> Activation
ruleActivation (BuiltinRule { })       = AlwaysActive
ruleActivation (Rule { ru_act = act }) = act
989 990

-- | The 'Name' of the 'Id.Id' at the head of the rule left hand side
991 992
ruleIdName :: CoreRule -> Name
ruleIdName = ru_fn
993

994 995
isLocalRule :: CoreRule -> Bool
isLocalRule = ru_local
996

997
-- | Set the 'Name' of the 'Id.Id' at the head of the rule left hand side
998 999
setRuleIdName :: Name -> CoreRule -> CoreRule
setRuleIdName nm ru = ru { ru_fn = nm }
1000

Austin Seipp's avatar
Austin Seipp committed
1001 1002 1003
{-
************************************************************************
*                                                                      *
1004
\subsection{Vectorisation declarations}
Austin Seipp's avatar
Austin Seipp committed
1005 1006
*                                                                      *
************************************************************************
1007 1008 1009

Representation of desugared vectorisation declarations that are fed to the vectoriser (via
'ModGuts').
Austin Seipp's avatar
Austin Seipp committed
1010
-}
1011

1012
data CoreVect = Vect      Id   CoreExpr
1013 1014 1015
              | NoVect    Id
              | VectType  Bool TyCon (Maybe TyCon)
              | VectClass TyCon                     -- class tycon
1016
              | VectInst  Id                        -- instance dfun (always SCALAR)  !!!FIXME: should be superfluous now
1017

Austin Seipp's avatar
Austin Seipp committed
1018 1019 1020
{-
************************************************************************
*                                                                      *
1021
                Unfoldings
Austin Seipp's avatar
Austin Seipp committed
1022 1023
*                                                                      *
************************************************************************
1024

1025
The @Unfolding@ type is declared here to avoid numerous loops
Austin Seipp's avatar
Austin Seipp committed
1026
-}
1027

1028 1029 1030
-- | Records the /unfolding/ of an identifier, which is approximately the form the
-- identifier would have if we substituted its definition in for the identifier.
-- This type should be treated as abstract everywhere except in "CoreUnfold"
1031
data Unfolding
1032 1033 1034 1035
  = NoUnfolding        -- ^ We have no information about the unfolding.

  | BootUnfolding      -- ^ We have no information about the unfolding, because
                       -- this 'Id' came from an @hi-boot@ file.
1036 1037
                       -- See Note [Inlining and hs-boot files] in ToIface
                       -- for what this is used for.
1038 1039

  | OtherCon [AltCon]  -- ^ It ain't one of these constructors.
1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052
                       -- @OtherCon xs@ also indicates that something has been evaluated
                       -- and hence there's no point in re-evaluating it.
                       -- @OtherCon []@ is used even for non-data-type values
                       -- to indicated evaluated-ness.  Notably:
                       --
                       -- > data C = C !(Int -> Int)
                       -- > case x of { C f -> ... }
                       --
                       -- Here, @f@ gets an @OtherCon []@ unfolding.

  | DFunUnfolding {     -- The Unfolding of a DFunId
                        -- See Note [DFun unfoldings]
                        --     df = /\a1..am. \d1..dn. MkD t1 .. tk
1053
                        --                                 (op1 a1..am d1..dn)
1054
                        --                                 (op2 a1..am d1..dn)
1055 1056 1057 1058
        df_bndrs :: [Var],      -- The bound variables [a1..m],[d1..dn]
        df_con   :: DataCon,    -- The dictionary data constructor (never a newtype datacon)
        df_args  :: [CoreExpr]  -- Args of the data con: types, superclasses and methods,
    }                           -- in positional order
1059

1060
  | CoreUnfolding {             -- An unfolding for an Id with no pragma,
1061
                                -- or perhaps a NOINLINE pragma
1062
                                -- (For NOINLINE, the phase, if any, is in the
1063
                                -- InlinePragInfo for this Id.)
1064 1065 1066 1067 1068
        uf_tmpl       :: CoreExpr,        -- Template; occurrence info is correct
        uf_src        :: UnfoldingSource, -- Where the unfolding came from
        uf_is_top     :: Bool,          -- True <=> top level binding
        uf_is_value   :: Bool,          -- exprIsHNF template (cached); it is ok to discard
                                        --      a `seq` on this variable
1069
        uf_is_conlike :: Bool,          -- True <=> applicn of constructor or CONLIKE function
1070
                                        --      Cached version of exprIsConLike
1071
        uf_is_work_free :: Bool,                -- True <=> doesn't waste (much) work to expand
1072
                                        --          inside an inlining
1073 1074 1075 1076
                                        --      Cached version of exprIsCheap
        uf_expandable :: Bool,          -- True <=> can expand in RULE matching
                                        --      Cached version of exprIsExpandable
        uf_guidance   :: UnfoldingGuidance      -- Tells about the *size* of the template.
1077
    }
1078 1079
  -- ^ An unfolding with redundant cached information. Parameters:
  --
1080 1081 1082
  --  uf_tmpl: Template used to perform unfolding;
  --           NB: Occurrence info is guaranteed correct:
  --               see Note [OccInfo in unfoldings and rules]
1083
  --
1084
  --  uf_is_top: Is this a top level binding?
1085
  --
1086
  --  uf_is_value: 'exprIsHNF' template (cached); it is ok to discard a 'seq' on
1087 1088
  --     this variable
  --
1089 1090
  --  uf_is_work_free:  Does this waste only a little work if we expand it inside an inlining?
  --     Basically this is a cached version of 'exprIsWorkFree'
1091
  --
1092
  --  uf_guidance:  Tells us about the /size/ of the unfolding template
1093

1094

1095 1096
------------------------------------------------
data UnfoldingSource
1097
  = -- See also Note [Historical note: unfoldings for wrappers]
1098

1099
    InlineRhs          -- The current rhs of the function
1100
                       -- Replace uf_tmpl each time around
1101

1102
  | InlineStable       -- From an INLINE or INLINABLE pragma
1103
                       --   INLINE     if guidance is UnfWhen
simonpj@microsoft.com's avatar
simonpj@microsoft.com committed
1104
                       --   INLINABLE  if guidance is UnfIfGoodArgs/UnfoldNever
1105 1106 1107 1108 1109 1110 1111
                       -- (well, technically an INLINABLE might be made
                       -- UnfWhen if it was small enough, and then
                       -- it will behave like INLINE outside the current
                       -- module, but that is the way automatic unfoldings
                       -- work so it is consistent with the intended
                       -- meaning of INLINABLE).
                       --
1112
                       -- uf_tmpl may change, but only as a result of
1113 1114 1115 1116
                       -- gentle simplification, it doesn't get updated
                       -- to the current RHS during compilation as with
                       -- InlineRhs.
                       --
1117
                       -- See Note [InlineRules]
1118 1119

  | InlineCompulsory   -- Something that *has* no binding, so you *must* inline it
1120
                       -- Only a few primop-like things have this property
1121
                       -- (see MkId.hs, calls to mkCompulsoryUnfolding).
1122 1123 1124 1125
                       -- Inline absolutely always, however boring the context.



1126
-- | 'UnfoldingGuidance' says when unfolding should take place
1127
data UnfoldingGuidance
1128 1129 1130
  = UnfWhen {   -- Inline without thinking about the *size* of the uf_tmpl
                -- Used (a) for small *and* cheap unfoldings
                --      (b) for INLINE functions
1131
                -- See Note [INLINE for small functions] in CoreUnfold
1132
      ug_arity    :: Arity,     -- Number of value arguments expected
Simon Peyton Jones's avatar