[Git][ghc/ghc][wip/T24359] update user's guide for SPECIALISE expression syntax

[sheaf (@sheaf)]

sheaf pushed to branch wip/T24359 at Glasgow Haskell Compiler / GHC


Commits:
a2d417cc by sheaf at 2024-12-03T11:53:44+01:00
update user's guide for SPECIALISE expression syntax

- - - - -


2 changed files:

- docs/users_guide/exts/pragmas.rst
- docs/users_guide/using-warnings.rst


Changes:

=====================================
docs/users_guide/exts/pragmas.rst
=====================================
@@ -692,24 +692,32 @@ The :pragma:`RULES` pragma lets you specify rewrite rules. It is described in
    single: pragma, SPECIALIZE
    single: overloading, death to
 
-.. pragma:: SPECIALIZE ⟨name⟩ :: ⟨type⟩
+.. pragma:: SPECIALIZE ⟨expr⟩
 
-    Ask that GHC specialize a polymorphic value to a particular type.
+    Ask that GHC create a copy of a function with specific arguments; most
+    commonly, a copy of an overloaded function with specific class
+    dictionary arguments.
 
 (UK spelling also accepted.) For key overloaded functions, you can
-create extra versions (NB: at the cost of larger code) specialised to particular
-types. Thus, if you have an overloaded function:
+create extra versions (NB: at the cost of larger code), specialised to specific
+arguments. Thus, if you have an overloaded function:
 
 ::
 
       hammeredLookup :: Ord key => [(key, value)] -> key -> value
 
 If it is heavily used on lists with ``Widget`` keys, you could
-specialise it as follows:
+specialise it with either of the following forms (the second syntax,
+introduced in GHC 9.14, additionally requires :extension:`TypeApplications`):
 
 ::
 
       {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
+      {-# SPECIALIZE hammeredLookup @Widget #-}
+
+Instead of taking an unknown ``Ord key`` dictionary at runtime, the specialised
+version of ``hammeredLookup`` will use the specific implementation of ``Ord Widget``,
+which is likely to produce more efficient code.
 
 -  A ``SPECIALIZE`` pragma for a function can be put anywhere its type
    signature could be put. Moreover, you can also ``SPECIALIZE`` an
@@ -755,15 +763,14 @@ specialise it as follows:
    specialisation is done too early, the optimisation rules might fail
    to fire.
 
--  The type in a ``SPECIALIZE`` pragma can be any type that is less
-   polymorphic than the type of the original function. In concrete
-   terms, if the original function is ``f`` then the pragma
+-  The ``SPECIALIZE`` pragma is valid only if the expression is well-typed.
+   For example, a specialize pragma of the form
 
    ::
 
          {-# SPECIALIZE f :: <type> #-}
 
-   is valid if and only if the definition
+   is valid only if the definition
 
    ::
 
@@ -777,6 +784,7 @@ specialise it as follows:
 
          f :: Eq a => a -> b -> b
          {-# SPECIALISE f :: Int -> b -> b #-}
+         {-# SPECIALISE f @Float #-}
 
          g :: (Eq a, Ix b) => a -> b -> b
          {-# SPECIALISE g :: (Eq a) => a -> Int -> Int #-}
@@ -789,12 +797,28 @@ specialise it as follows:
    fire very well. If you use this kind of specialisation, let us know
    how well it works.
 
+-  Since GHC 9.14, it is also possible to specialise a function at specific
+   value arguments, e.g.: ::
+
+         fn :: Bool -> Int -> Double
+         fn b i = ...
+           where
+             ... = if b then helper1 else helper2
+         {-# SPECIALISE fn True #-}
+         {-# SPECIALISE fn False #-}
+
+   This will make two copies of ``fn``, one for ``True`` and one for ``False``.
+   These will then be optimised to make direct calls to ``helper1`` or ``helper2``,
+   respectively, instead of dispatching on ``b`` at runtime.
+   Call sites (that use a literal ``True`` or ``False``) will be rewritten
+   to use the specialised versions.
+
 .. _specialize-inline:
 
 ``SPECIALIZE INLINE``
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. pragma:: SPECIALIZE INLINE ⟨name⟩ :: ⟨type⟩
+.. pragma:: SPECIALIZE INLINE ⟨expr⟩
 
     :where: top-level
 


=====================================
docs/users_guide/using-warnings.rst
=====================================
@@ -423,6 +423,20 @@ of ``-W(no-)*``.
     such as a `LANGUAGE` or `OPTIONS_GHC` pragma, appears in the body of
     the module instead.
 
+.. ghc-flag:: -Wdeprecated-pragmas
+    :shortdesc: warn about deprecated pragmas
+    :type: dynamic
+    :reverse: -Wno-deprecated-pragmas
+    :category:
+
+    :since: 9.14
+
+    :default: on
+
+    Emits a warning when using a deprecated form of a SPECIALISE pragma which
+    uses multiple comma-separated type signatures (deprecated and scheduled
+    to be removed in GHC 9.18).
+
 .. ghc-flag:: -Wmissed-specialisations
     :shortdesc: warn when specialisation of an imported, overloaded function
         fails.
@@ -477,6 +491,27 @@ of ``-W(no-)*``.
 
     Alias for :ghc-flag:`-Wall-missed-specialisations`
 
+.. ghc-flag:: -Wuseless-specialisations
+    :shortdesc: warn on useless SPECIALISE pragmas
+    :type: dynamic
+    :reverse: -Wno-useless-specialisations
+    :category:
+
+    :since: 9.14
+
+    :default: on
+
+    Emits a warning if GHC detects a useless SPECIALISE pragma, such as a
+    SPECIALISE pragma on a non-overloaded function, for example
+    ``{-# SPECIALISE id :: Int -> Int #-}``.
+
+.. ghc-flag:: -Wuseless-specializations
+    :shortdesc: alias for :ghc-flag:`-Wuseless-specialisations`
+    :type: dynamic
+    :reverse: -Wno-useless-specializations
+
+    Alias for :ghc-flag:`-Wuseless-specialisations`
+
 .. ghc-flag:: -Wextended-warnings
     :shortdesc: warn about uses of functions & types that have WARNING or
         DEPRECATED pragmas, across all categories



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

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/a2d417ccfdb9cbf3e51fc11f9c52a8c2e40ad7a2
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/20241203/e5488b58/attachment-0001.html>