* maps a OneOcc to OneOcc{ occ_n_br = 0 }

   In our example, occ_join_points will be extended with

       [j :-> [v :-> OneOcc{occ_n_br=0}]]

 * At an occurrence of a join point, we do everything as normal, but add in the

   UsageDetails from the occ_join_points.  See mkOneOcc.

 * Crucially, at the NonRec binding of the join point, in `occAnalBind`, we use

 Here are the consequences

   These are `andUDs` together in `addOccInfo`, and hence

   `v` gets ManyOccs, just as it should.  Clever!

 (W1) Consider this example which shadows `j`:

           join j = rhs in

      * In `postprcess_uds`, we add the chucked-out join points to the

        returned UsageDetails, with `andUDs`.

 (W3) Consider this example, which shadows `j`, but this time in an argument

               join j = rhs

               in f (case x of { K j -> ...; ... })

 (W4) What if the join point binding has a stable unfolding, or RULES?

      They are just alternative right-hand sides, and at each call site we

 Note [Finding join points]

 ~~~~~~~~~~~~~~~~~~~~~~~~~~

 Note [Join arity prediction based on joinRhsArity]

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   ==> { Contify for join arity 1 }

   join f x = \y -> x + y

   in if b then jump f 1 else jump f 2

   ==> { Contify for join arity 1, eta-expand f }

   join f x = id x

   in if b then jump f 12 else jump f 13

   letrec f x y = if ... then f x else True

   in f 42

 would not happen in a tail context! Contification is invalid here.

 points paper nor GHC does this at the moment.)

 We can capitalise on this observation and conclude that *if* f could become a

 It is also the join arity inside the 'TailUsageDetails' returned by

 'occAnalLamTail', so we can predict join arity without doing any fixed-point

 iteration or really doing any deep traversal of let body or RHS at all.

 All this is quite apparent if you look at the contification transformation in

 Fig. 5 of "Compiling without Continuations" (which does not account for

 eta-expansion at all, mind you). The letrec case looks like this

   letrec f = /\as.\xs. L[us] in L'[es]

     ... and a bunch of conditions establishing that f only occurs

         in app heads of join arity (len as + len xs) inside us and es ...

 for non-recursive functions, this is the definition of contification from the

 paper:

   let f = /\as.\xs.u in L[es]     ... conditions ...

 Note [Join points and unfoldings/rules]

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   = -- Analyse the RHS and /then/ the body

     let -- Analyse the rhs first, generating rhs_uds

         !(rhs_uds_s, bndr', rhs') = occAnalNonRecRhs env lvl ire mb_join bndr rhs

         -- Now analyse the body, adding the join point

         -- into the environment with addJoinPoint

                                       thing_inside (addJoinPoint env bndr' rhs_uds)

     in

     if isDeadOcc occ     -- Drop dead code; see Note [Dead code]

     then WUD body_uds body

              (combine [NonRec (fst (tagNonRecBinder lvl occ bndr')) rhs']

                       body)

   -- The normal case, including newly-discovered join points

   -- Analyse the body and /then/ the RHS

   = if isDeadOcc occ   -- Drop dead code; see Note [Dead code]

     then WUD body_uds body

     else let

     rhs_ctxt = mkNonRecRhsCtxt lvl bndr unf

     -- See Note [Join arity prediction based on joinRhsArity]

     -- returned by of occAnalLamTail. It's totally OK for them to mismatch;

     -- hence adjust the UDs from the RHS

                                -- here because that is what we are setting!

     WTUD unf_tuds unf' = occAnalUnfolding rhs_env unf

     adj_unf_uds = adjustTailArity (JoinPoint rhs_ja) unf_tuds

       -- of Note [Join arity prediction based on joinRhsArity]

     --------- IMP-RULES --------

     --------- All rules --------

     -- See Note [Join points and unfoldings/rules]

     -- of Note [Join arity prediction based on joinRhsArity]

     rules_w_uds :: [(CoreRule, UsageDetails, UsageDetails)]

     rules_w_uds = [ (r,l,adjustTailArity (JoinPoint rhs_ja) rhs_wuds)

 -- See Note [Adjusting right-hand sides]

 occAnalLamTail env expr

   = let !(WUD usage expr') = occ_anal_lam_tail env expr

 occ_anal_lam_tail :: OccEnv -> CoreExpr -> WithUsageDetails CoreExpr

 -- Does not markInsideLam etc for the outmost batch of lambdas

             -> WithUsageDetails CoreExpr

 -- The `fun` argument is just an accumulating parameter,

 -- the base for building the application we return

   = go emptyDetails fun args one_shots

   where

     env_args = setNonTailCtxt encl env

 occAnalApp :: OccEnv

            -> (Expr CoreBndr, [Arg CoreBndr], [CoreTickish])

            -> WithUsageDetails (Expr CoreBndr)

   -- Account for join arity of runRW# continuation

   -- See Note [Simplification of runRW#]

   --

              -- Invariant: no Id maps to an empty OccInfoEnv

              -- See Note [Occurrence analysis for join points]

            , occ_join_points :: !JoinPointInfo

 type JoinPointInfo = IdEnv OccInfoEnv

            , occ_join_points = emptyVarEnv

            , occ_bs_env = emptyVarEnv

 noBinderSwaps :: OccEnv -> Bool

 noBinderSwaps (OccEnv { occ_bs_env = bs_env }) = isEmptyVarEnv bs_env

       | uniq `elemVarEnvByKey` env = plusVarEnv_C andLocalOcc env join_env

       | otherwise                  = env

 addJoinPoint :: OccEnv -> Id -> UsageDetails -> OccEnv

   | isEmptyVarEnv zeroed_form

   = env

   | otherwise

   where

 --------------------

 transClosureFV :: VarEnv VarSet -> VarEnv VarSet

                    -- Combining (AlwaysTailCalled 2) and (AlwaysTailCalled 3)

                    -- gives NoTailCallInfo

               , lo_int_cxt :: !InterestingCxt }

     | ManyOccL !TailCallInfo

 instance Outputable LocalOcc where

   ppr (OneOccL { lo_n_br = n, lo_tail = tci })

 -- | TailUsageDetails captures the result of applying 'occAnalLamTail'

 --   to a function `\xyz.body`. The TailUsageDetails pairs together

 --   * the number of lambdas (including type lambdas: a JoinArity)

 -- If the binding turns out to be a join point with the indicated join

 -- arity, this unadjusted usage details is just what we need; otherwise we

 -- need to discard tail calls. That's what `adjustTailUsage` does.

 andUDs:: UsageDetails -> UsageDetails -> UsageDetails

 orUDs :: UsageDetails -> UsageDetails -> UsageDetails

 mkOneOcc :: OccEnv -> Id -> InterestingCxt -> JoinArity -> UsageDetails

 mkOneOcc !env id int_cxt arity

   = mkSimpleDetails (unitVarEnv id occ)

   where

                   , lo_tail = AlwaysTailCalled arity }

 -- Add several occurrences, assumed not to be tail calls

 -------------------

 -- Auxiliary functions for UsageDetails implementation

                         -> UsageDetails -> UsageDetails -> UsageDetails

 {-# INLINE combineUsageDetailsWith #-}

 combineUsageDetailsWith plus_occ_info

   | isEmptyVarEnv env2 = uds1

   | otherwise

   -- See Note [Strictness in the occurrence analyser]

        , ud_z_many    = strictPlusVarEnv z_many1   z_many2

        , ud_z_in_lam  = plusVarEnv z_in_lam1 z_in_lam2

        , ud_z_tail    = strictPlusVarEnv z_tail1   z_tail2 }

         | uniq `elemVarEnvByKey` z_tail = NoTailCallInfo

         | otherwise                     = ti

 -------------------

 -- See Note [Adjusting right-hand sides]

 -- ^ This function concentrates shared logic between occAnalNonRecBind and the

 -- AcyclicSCC case of occAnalRec.

 -- It returns the adjusted rhs UsageDetails combined with the body usage

                 -> UsageDetails

   = -- c.f. occAnal (Lam {})

     markAllInsideLamIf (not one_shot) $

     markAllNonTailIf (not exact_join) $

     uds

   where

     one_shot   = isOneShotFun rhs

 adjustTailArity :: JoinPointHood -> TailUsageDetails -> UsageDetails

 adjustTailArity mb_rhs_ja (TUD ja usage)

 tagRecBinders :: TopLevelFlag           -- At top level?

               -> UsageDetails           -- Of body of let ONLY

               -> [NodeDetails]

                   [IdWithOccInfo]       -- Tagged binders

 -- Substantially more complicated than non-recursive case. Need to adjust RHS

 -- details *before* tagging binders (because the tags depend on the RHSes).

      -- 1. See Note [Join arity prediction based on joinRhsArity]

      --    Determine possible join-point-hood of whole group, by testing for

      unadj_uds = foldr (andUDs . test_manifest_arity) body_uds details_s

      will_be_joins = decideRecJoinPointHood lvl unadj_uds bndrs

      -- 2. Adjust usage details of each RHS, taking into account the

      --    join-point-hood decision

                      -- Matching occAnalLamTail in makeNode

      -- 3. Compute final usage details from adjusted RHS details

      adj_uds = foldr andUDs body_uds rhs_udss'

   | otherwise                  = setIdOccInfo bndr occ_info

 -- | Decide whether some bindings should be made into join points or not, based

 -- Returns `False` if they can't be join points. Note that it's an

 -- assumed to be mutually recursive.

 --

 -- It must, however, be a final decision. If we say `True` for 'f',

                -> InId -> Bool    -- True <=> this is a join point

                -> OutExpr -> SimplM Unfolding

 mkLetUnfolding env top_lvl src id is_join new_rhs

   where

     -- !opts: otherwise, we end up retaining all the SimpleEnv

     !uf_opts = seUnfoldingOpts env

     -- See Note [Force bottoming field]

     !is_bottoming = isDeadEndId id

 -------------------

 simplStableUnfolding :: SimplEnv -> BindContext

                      -> InId

         plusUFM,

         strictPlusUFM,

         plusUFM_C,

         plusUFM_CD,

         plusUFM_CD2,

         mergeUFM,

 strictPlusUFM_C :: (elt -> elt -> elt) -> UniqFM key elt -> UniqFM key elt -> UniqFM key elt

 strictPlusUFM_C f (UFM x) (UFM y) = UFM (MS.unionWith f x y)

 -- | `plusUFM_CD f m1 d1 m2 d2` merges the maps using `f` as the

 -- combinding function and `d1` resp. `d2` as the default value if

 -- there is no entry in `m1` reps. `m2`. The domain is the union of

         lookupUniqSet_Directly,

         partitionUniqSet,

         mapUniqSet,

         unsafeUFMToUniqSet,

         nonDetEltsUniqSet,

         nonDetKeysUniqSet,

 mapMaybeUniqSet_sameUnique :: (a -> Maybe b) -> UniqSet a -> UniqSet b

 mapMaybeUniqSet_sameUnique f (UniqSet a) = UniqSet $ mapMaybeUFM_sameUnique f a

 -- Two 'UniqSet's are considered equal if they contain the same

 -- uniques.

 instance Eq (UniqSet a) where

         elemVarEnv, disjointVarEnv, anyVarEnv,

         extendVarEnv, extendVarEnv_C, extendVarEnv_Acc,

         extendVarEnvList,

         plusVarEnv_CD, plusMaybeVarEnv_C,

         plusVarEnvList, alterVarEnv,

         delVarEnvList, delVarEnv,

 minusVarEnv       :: VarEnv a -> VarEnv b -> VarEnv a

 plusVarEnv_C      :: (a -> a -> a) -> VarEnv a -> VarEnv a -> VarEnv a

 strictPlusVarEnv_C :: (a -> a -> a) -> VarEnv a -> VarEnv a -> VarEnv a

 plusVarEnv_CD     :: (a -> a -> a) -> VarEnv a -> a -> VarEnv a -> a -> VarEnv a

 plusMaybeVarEnv_C :: (a -> a -> Maybe a) -> VarEnv a -> VarEnv a -> VarEnv a

 mapVarEnv         :: (a -> b) -> VarEnv a -> VarEnv b

 extendVarEnvList = addListToUFM

 plusVarEnv_C     = plusUFM_C

 strictPlusVarEnv_C = strictPlusUFM_C

 plusVarEnv_CD    = plusUFM_CD

 plusMaybeVarEnv_C = plusMaybeUFM_C

 delVarEnvList    = delListFromUFM