path: root/ghc/compiler/basicTypes/IdInfo.lhs

%
% (c) The GRASP/AQUA Project, Glasgow University, 1993-1998
%
\section[IdInfo]{@IdInfos@: Non-essential information about @Ids@}

(And a pretty good illustration of quite a few things wrong with
Haskell. [WDP 94/11])

\begin{code}
module IdInfo (
	IdInfo,		-- Abstract

	noIdInfo,
	ppIdInfo,

	-- Arity
	ArityInfo(..),
	exactArity, atLeastArity, unknownArity,
	arityInfo, setArityInfo, ppArityInfo, arityLowerBound,

	-- Strictness
	StrictnessInfo(..),				-- Non-abstract
	workerExists, mkStrictnessInfo, mkBottomStrictnessInfo, 
	noStrictnessInfo, bottomIsGuaranteed, strictnessInfo, 
	ppStrictnessInfo, setStrictnessInfo, 

	-- Unfolding
	unfoldingInfo, setUnfoldingInfo, 

	-- DemandInfo
	demandInfo, setDemandInfo, 

	-- Inline prags
	InlinePragInfo(..), OccInfo(..),
	inlinePragInfo, setInlinePragInfo, notInsideLambda,

	-- Specialisation
	IdSpecEnv, specInfo, setSpecInfo,

	-- Update
	UpdateInfo, UpdateSpec,
	mkUpdateInfo, updateInfo, updateInfoMaybe, ppUpdateInfo, setUpdateInfo,

	-- CAF info
	CafInfo(..), cafInfo, setCafInfo, ppCafInfo,
    ) where

#include "HsVersions.h"


import {-# SOURCE #-} CoreUnfold ( Unfolding, noUnfolding )
import {-# SOURCE #-} CoreSyn	 ( CoreExpr )

import SpecEnv	        ( SpecEnv, emptySpecEnv )
import Demand		( Demand,  isLazy, wwLazy, pprDemands )
import Outputable	
\end{code}

An @IdInfo@ gives {\em optional} information about an @Id@.  If
present it never lies, but it may not be present, in which case there
is always a conservative assumption which can be made.

Two @Id@s may have different info even though they have the same
@Unique@ (and are hence the same @Id@); for example, one might lack
the properties attached to the other.

The @IdInfo@ gives information about the value, or definition, of the
@Id@.  It does {\em not} contain information about the @Id@'s usage
(except for @DemandInfo@? ToDo).

\begin{code}
data IdInfo
  = IdInfo {
	arityInfo :: ArityInfo,			-- Its arity
	demandInfo :: Demand,			-- Whether or not it is definitely demanded
	specInfo :: IdSpecEnv,			-- Specialisations of this function which exist
	strictnessInfo :: StrictnessInfo,	-- Strictness properties
	unfoldingInfo :: Unfolding,		-- Its unfolding
	updateInfo :: UpdateInfo,		-- Which args should be updated
	cafInfo :: CafInfo,
	inlinePragInfo :: !InlinePragInfo	-- Inline pragmas
    }
\end{code}

Setters

\begin{code}
setUpdateInfo	  ud info = info { updateInfo = ud }
setDemandInfo	  dd info = info { demandInfo = dd }
setStrictnessInfo st info = info { strictnessInfo = st }
setSpecInfo 	  sp info = info { specInfo = sp }
setArityInfo	  ar info = info { arityInfo = ar  }
setInlinePragInfo pr info = info { inlinePragInfo = pr }
setUnfoldingInfo  uf info = info { unfoldingInfo = uf }
setCafInfo        cf info = info { cafInfo = cf }
\end{code}


\begin{code}
noIdInfo = IdInfo {
		arityInfo	= UnknownArity,
		demandInfo	= wwLazy,
		specInfo	= emptySpecEnv,
		strictnessInfo	= NoStrictnessInfo,
		unfoldingInfo	= noUnfolding,
		updateInfo	= NoUpdateInfo,
		cafInfo		= MayHaveCafRefs,
		inlinePragInfo  = NoInlinePragInfo
	   }
\end{code}

\begin{code}
ppIdInfo :: IdInfo -> SDoc
ppIdInfo (IdInfo {arityInfo, 
		  demandInfo,
		  specInfo,
		  strictnessInfo, 
		  unfoldingInfo,
		  updateInfo, 
		  cafInfo,
		  inlinePragInfo})
  = hsep [
	    ppArityInfo arityInfo,
	    ppUpdateInfo updateInfo,
	    ppStrictnessInfo strictnessInfo,
	    ppr demandInfo,
	    ppCafInfo cafInfo
	-- Inline pragma printed out with all binders; see PprCore.pprIdBndr
	]
\end{code}

%************************************************************************
%*									*
\subsection[arity-IdInfo]{Arity info about an @Id@}
%*									*
%************************************************************************

For locally-defined Ids, the code generator maintains its own notion
of their arities; so it should not be asking...	 (but other things
besides the code-generator need arity info!)

\begin{code}
data ArityInfo
  = UnknownArity	-- No idea
  | ArityExactly Int	-- Arity is exactly this
  | ArityAtLeast Int	-- Arity is this or greater

exactArity   = ArityExactly
atLeastArity = ArityAtLeast
unknownArity = UnknownArity

arityLowerBound :: ArityInfo -> Int
arityLowerBound UnknownArity     = 0
arityLowerBound (ArityAtLeast n) = n
arityLowerBound (ArityExactly n) = n


ppArityInfo UnknownArity	 = empty
ppArityInfo (ArityExactly arity) = hsep [ptext SLIT("__A"), int arity]
ppArityInfo (ArityAtLeast arity) = hsep [ptext SLIT("__AL"), int arity]
\end{code}

%************************************************************************
%*									*
\subsection{Inline-pragma information}
%*									*
%************************************************************************

\begin{code}
data InlinePragInfo
  = NoInlinePragInfo

  | IAmASpecPragmaId	-- Used for spec-pragma Ids; don't discard or inline

  | IWantToBeINLINEd	-- User INLINE pragma
  | IMustNotBeINLINEd	-- User NOINLINE pragma

  | IAmALoopBreaker	-- Used by the occurrence analyser to mark loop-breakers
			-- in a group of recursive definitions

  | ICanSafelyBeINLINEd	-- Used by the occurrence analyser to mark things
			-- that manifesly occur once, not inside SCCs, 
			-- not in constructor arguments

	OccInfo		-- Says whether the occurrence is inside a lambda
			--	If so, must only substitute WHNFs

	Bool		-- False <=> occurs in more than one case branch
			--	If so, there's a code-duplication issue

  | IAmDead		-- Marks unused variables.  Sometimes useful for
			-- lambda and case-bound variables.

  | IMustBeINLINEd	-- Absolutely must inline; used for PrimOps and
			-- constructors only.

instance Outputable InlinePragInfo where
  ppr NoInlinePragInfo  	= empty
  ppr IMustBeINLINEd    	= ptext SLIT("__UU")
  ppr IWantToBeINLINEd  	= ptext SLIT("__U")
  ppr IMustNotBeINLINEd 	= ptext SLIT("__Unot")
  ppr IAmALoopBreaker   	= ptext SLIT("__Ux")
  ppr IAmDead			= ptext SLIT("__Ud")
  ppr (ICanSafelyBeINLINEd _ _) = ptext SLIT("__Us")
  ppr IAmASpecPragmaId 		= ptext SLIT("__US")

instance Show InlinePragInfo where
  showsPrec p prag = showsPrecSDoc p (ppr prag)
\end{code}

The @IMustNotBeDiscarded@ exists only to make Ids that are
on the *LHS* of bindings created by SPECIALISE pragmas; 
eg:		s = f Int d
The SpecPragmaId is never itself mentioned; it
exists solely so that the specialiser will find
the call to f, and make specialised version of it.
The SpecPragmaId binding is discarded by the specialiser
when it gathers up overloaded calls.
Meanwhile, it is not discarded as dead code.

\begin{code}
data OccInfo
  = StrictOcc		-- Occurs syntactically strictly;
			-- i.e. in a function position or case scrutinee

  | LazyOcc		-- Not syntactically strict (*even* that of a strict function)
			-- or in a case branch where there's more than one alternative

  | InsideLam		-- Inside a non-linear lambda (that is, a lambda which
			-- is sure to be instantiated only once).
			-- Substituting a redex for this occurrence is
			-- dangerous because it might duplicate work.

instance Outputable OccInfo where
  ppr StrictOcc = text "s"
  ppr LazyOcc   = empty
  ppr InsideLam = text "l"


notInsideLambda :: OccInfo -> Bool
notInsideLambda StrictOcc = True
notInsideLambda LazyOcc   = True
notInsideLambda InsideLam = False
\end{code}

%************************************************************************
%*									*
\subsection[specialisation-IdInfo]{Specialisation info about an @Id@}
%*									*
%************************************************************************

A @IdSpecEnv@ holds details of an @Id@'s specialisations. 

\begin{code}
type IdSpecEnv = SpecEnv CoreExpr
\end{code}

For example, if \tr{f}'s @SpecEnv@ contains the mapping:
\begin{verbatim}
	[List a, b]  ===>  (\d -> f' a b)
\end{verbatim}
then when we find an application of f to matching types, we simply replace
it by the matching RHS:
\begin{verbatim}
	f (List Int) Bool ===>  (\d -> f' Int Bool)
\end{verbatim}
All the stuff about how many dictionaries to discard, and what types
to apply the specialised function to, are handled by the fact that the
SpecEnv contains a template for the result of the specialisation.

There is one more exciting case, which is dealt with in exactly the same
way.  If the specialised value is unboxed then it is lifted at its
definition site and unlifted at its uses.  For example:

	pi :: forall a. Num a => a

might have a specialisation

	[Int#] ===>  (case pi' of Lift pi# -> pi#)

where pi' :: Lift Int# is the specialised version of pi.



%************************************************************************
%*									*
\subsection[strictness-IdInfo]{Strictness info about an @Id@}
%*									*
%************************************************************************

We specify the strictness of a function by giving information about
each of the ``wrapper's'' arguments (see the description about
worker/wrapper-style transformations in the PJ/Launchbury paper on
unboxed types).

The list of @Demands@ specifies: (a)~the strictness properties
of a function's arguments; (b)~the {\em existence} of a ``worker''
version of the function; and (c)~the type signature of that worker (if
it exists); i.e. its calling convention.

\begin{code}
data StrictnessInfo
  = NoStrictnessInfo

  | BottomGuaranteed	-- This Id guarantees never to return;
			-- it is bottom regardless of its arguments.
			-- Useful for "error" and other disguised
			-- variants thereof.

  | StrictnessInfo [Demand] 
		   Bool		-- True <=> there is a worker. There might not be, even for a
				-- strict function, because:
				-- 	(a) the function might be small enough to inline, 
				--	    so no need for w/w split
				-- 	(b) the strictness info might be "SSS" or something, so no w/w split.

				-- Worker's Id, if applicable, and a list of the constructors
				-- mentioned by the wrapper.  This is necessary so that the
				-- renamer can slurp them in.  Without this info, the renamer doesn't
				-- know which data types to slurp in concretely.  Remember, for
				-- strict things we don't put the unfolding in the interface file, to save space.
				-- This constructor list allows the renamer to behave much as if the
				-- unfolding *was* in the interface file.
\end{code}

\begin{code}
mkStrictnessInfo :: [Demand] -> Bool -> StrictnessInfo

mkStrictnessInfo xs has_wrkr
  | all isLazy xs	 = NoStrictnessInfo		-- Uninteresting
  | otherwise		 = StrictnessInfo xs has_wrkr

noStrictnessInfo       = NoStrictnessInfo
mkBottomStrictnessInfo = BottomGuaranteed

bottomIsGuaranteed BottomGuaranteed = True
bottomIsGuaranteed other    	    = False

ppStrictnessInfo NoStrictnessInfo = empty
ppStrictnessInfo BottomGuaranteed = ptext SLIT("__bot")

ppStrictnessInfo (StrictnessInfo wrapper_args wrkr_maybe)
  = hsep [ptext SLIT("__S"), pprDemands wrapper_args]
\end{code}


\begin{code}
workerExists :: StrictnessInfo -> Bool
workerExists (StrictnessInfo _ worker_exists) = worker_exists
workerExists other			      = False
\end{code}


%************************************************************************
%*									*
\subsection[update-IdInfo]{Update-analysis info about an @Id@}
%*									*
%************************************************************************

\begin{code}
data UpdateInfo
  = NoUpdateInfo
  | SomeUpdateInfo UpdateSpec
  deriving (Eq, Ord)
      -- we need Eq/Ord to cross-chk update infos in interfaces

-- the form in which we pass update-analysis info between modules:
type UpdateSpec = [Int]
\end{code}

\begin{code}
mkUpdateInfo = SomeUpdateInfo

updateInfoMaybe NoUpdateInfo	    = Nothing
updateInfoMaybe (SomeUpdateInfo []) = Nothing
updateInfoMaybe (SomeUpdateInfo	 u) = Just u
\end{code}

Text instance so that the update annotations can be read in.

\begin{code}
ppUpdateInfo NoUpdateInfo	   = empty
ppUpdateInfo (SomeUpdateInfo [])   = empty
ppUpdateInfo (SomeUpdateInfo spec) = (<>) (ptext SLIT("__U ")) (hcat (map int spec))
\end{code}

%************************************************************************
%*									*
\subsection[CAF-IdInfo]{CAF-related information}
%*									*
%************************************************************************

This information is used to build Static Reference Tables (see
simplStg/ComputeSRT.lhs).

\begin{code}
data CafInfo 
	= MayHaveCafRefs		-- either:
					-- (1) A function or static constructor
					--     that refers to one or more CAFs,
					-- (2) A real live CAF

	| NoCafRefs			-- A function or static constructor
				        -- that refers to no CAFs.

-- LATER: not sure how easy this is...
--      | OneCafRef Id


ppCafInfo NoCafRefs = ptext SLIT("__C")
ppCafInfo MayHaveCafRefs = empty
\end{code}