-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | GHC plugin to make stream fusion more predictable.
--   
--   This plugin provides the programmer with a way to annotate certain
--   types using a <a>Fuse</a> pragma. The programmer would annotate the
--   types that are to be eliminated by fusion. During the simplifier phase
--   the plugin goes through the relevant bindings and if one of these
--   types are found inside a binding then that binding is marked to be
--   inlined irrespective of the size.
--   
--   This plugin was primarily motivated by <a>streamly</a> but it can be
--   used in general.
@package fusion-plugin
@version 0.1.0


module Fusion.Plugin.Types

-- | A GHC annotation to inform the plugin to aggressively inline join
--   points that perform a case match on the constructors of the annotated
--   type. Inlining enables case-of-case transformations that would
--   potentially eliminate the constructors.
--   
--   This annotation is to be used on types whose constructors are known to
--   be involved in case-of-case transformations enabling stream fusion via
--   elimination of those constructors.
--   
--   It is advised to use unique types for intermediate stream state that
--   is to be annotated with <a>Fuse</a>. If the annotated type is also
--   used for some other purpose this annotation may inline code that is
--   not involved in stream fusion and should otherwise not be inlined.
--   
--   <pre>
--   {-# ANN type Step Fuse #-}
--   data Step s a = Yield a s | Skip s | Stop
--   </pre>
data Fuse
Fuse :: Fuse
instance Data.Data.Data Fusion.Plugin.Types.Fuse
instance GHC.Classes.Eq Fusion.Plugin.Types.Fuse
instance Outputable.Outputable Fusion.Plugin.Types.Fuse


-- | Stream fusion depends on the GHC case-of-case transformations
--   eliminating intermediate constructors. Case-of-case transformation in
--   turn depends on inlining. During core-to-core transformations GHC may
--   create several internal bindings (e.g. join points) which may not get
--   inlined because their size is bigger than GHC's inlining threshold.
--   Even though we know that after fusion the resulting code would be
--   smaller and more efficient. The programmer cannot force inlining of
--   these bindings as there is no way for the programmer to address these
--   bindings at the source level because they are internal, generated
--   during core-to-core transformations. As a result stream fusion fails
--   unpredictably depending on whether GHC was able to inline the internal
--   bindings or not.
--   
--   <a>See GHC ticket #17075</a> for more details.
--   
--   This plugin provides the programmer with a way to annotate certain
--   types using a custom <a>Fuse</a> annotation. The programmer would
--   annotate the types that are to be eliminated by fusion via
--   case-of-case transformations. During the simplifier phase the plugin
--   goes through the relevant bindings and if one of these types are found
--   inside a binding then that binding is marked to be inlined
--   irrespective of the size.
--   
--   At the right places, fusion can provide dramatic performance
--   improvements (e.g. 10x) to the code.
module Fusion.Plugin
plugin :: Plugin