Document keepAlive#

In GHC.CoreToStg.Prep I see

    cpe_app env
            (Var f)
            args
            n
        | Just KeepAliveOp <- isPrimOpId_maybe f
        , CpeApp (Type arg_rep)
          : CpeApp (Type arg_ty)
          : CpeApp (Type _result_rep)
          : CpeApp (Type result_ty)
          : CpeApp arg
          : CpeApp s0
          : CpeApp k
          : rest <- args
        = do { y  <- newVar (cpSubstTy env result_ty)
             ; s2 <- newVar realWorldStatePrimTy
             ; -- beta reduce if possible
             ; (floats, k') <- case k of
                  Lam s body -> cpe_app (extendCorePrepEnvExpr env s s0) body rest (n-2)
                  _          -> cpe_app env k (CpeApp s0 : rest) (n-1)
             ; let touchId = mkPrimOpId TouchOp
                   expr = Case k' y result_ty [Alt DEFAULT [] rhs]
                   rhs = let scrut = mkApps (Var touchId) [Type arg_rep, Type arg_ty, arg, Var realWorldPrimId]
                         in Case scrut s2 result_ty [Alt DEFAULT [] (Var y)]
             ; (floats', expr') <- cpeBody env expr
             ; return (floats `appendFloats` floats', expr')
             }
        | Just KeepAliveOp <- isPrimOpId_maybe f
        = panic "invalid keepAlive# application"

with not a shred of discussion. The keepAlive# discussion was one of the longest-running sagas in GHC's recent history. We tried multiple ways that didn't work, before arriving at this one.

It desperately needs a Note that describes all the moving parts. @bgamari can you add one? I think #17760 (closed) is the relevant ticket, and a long series of attempts including at least

• A wiki page: https://gitlab.haskell.org/ghc/ghc/-/wikis/proposal/with-combinator
• !2559 (closed) (abandoned)
• !2566 (closed) (abandoned)
• !2567 (continuation arguments, still open)
• !2933 (closed) (abandoned)
• !2961 (closed) (abandoned)
• !3131 (closed) (abandoned)
• !4015 (closed) (abandoned)
• !4168 (closed) (abandoned)
• !3113 (closed) (runRW#, landed)
• !4347 (closed) (landed).

Any line of thought that is so long surely deserves careful documentation.

Simon