[Git][ghc/ghc][master] Documentation: add an example of SPEC usage

[Marge Bot (@marge-bot)]

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
5b038888 by Bodigrim at 2023-02-16T10:18:24-05:00
Documentation: add an example of SPEC usage

- - - - -


2 changed files:

- libraries/base/GHC/Exts.hs
- libraries/ghc-prim/GHC/Types.hs


Changes:

=====================================
libraries/base/GHC/Exts.hs
=====================================
@@ -203,8 +203,11 @@ traceEvent = Debug.Trace.traceEventIO
 *                                                                       *
 ********************************************************************** -}
 
--- Annotating a type with NoSpecConstr will make SpecConstr
--- not specialise for arguments of that type.
+-- | Deprecated, use 'SPEC' directly instead.
+--
+-- Annotating a type with 'NoSpecConstr' will make @SpecConstr@
+-- not specialise for arguments of that type,
+-- e. g., @{-# ANN type SPEC ForceSpecConstr #-}@.
 
 -- This data type is defined here, rather than in the SpecConstr module
 -- itself, so that importing it doesn't force stupidly linking the


=====================================
libraries/ghc-prim/GHC/Types.hs
=====================================
@@ -435,7 +435,25 @@ you're reading this in 2023 then things went wrong). See #8326.
 -- specializations. However, not all loops fall into this category.
 --
 -- Libraries can specify this by using 'SPEC' data type to inform which
--- loops should be aggressively specialized.
+-- loops should be aggressively specialized. For example,
+-- instead of
+--
+-- > loop x where loop arg = ...
+--
+-- write
+--
+-- > loop SPEC x where loop !_ arg = ...
+--
+-- There is no semantic difference between 'SPEC' and 'SPEC2',
+-- we just need a type with two contructors lest it is optimised away
+-- before @SpecConstr at .
+--
+-- This type is reexported from "GHC.Exts" since GHC 9.0 and @base-4.15 at .
+-- For compatibility with earlier releases import it from "GHC.Types"
+-- in @ghc-prim@ package.
+--
+-- @since 0.3.1.0
+--
 data SPEC = SPEC | SPEC2
 
 



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5b0388880e10ce53565721a9569d009d4534cbc1

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5b0388880e10ce53565721a9569d009d4534cbc1
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230216/d2491ba7/attachment-0001.html>