Document readField / readSymFieldwip/tdammers-7258

1 files changed, 28 insertions, 0 deletions

diff --git a/libraries/base/GHC/Read.hs b/libraries/base/GHC/Read.hs
index e69e4a02b8..2d8ee3de51 100644
--- a/libraries/base/GHC/Read.hs
+++ b/libraries/base/GHC/Read.hs
@@ -361,6 +361,12 @@ choose sps = foldr ((+++) . try_one) pfail sps
                                     L.Symbol s' | s==s' -> p
                                     _other              -> pfail }
 
+-- See Note [Why readField]
+
+-- | 'Read' parser for a record field, of the form @fieldName=value@. The
+-- @fieldName@ must be an alphanumeric identifier; for symbols (operator-style)
+-- field names, e.g. @(#)@, use 'readSymField'). The second argument is a
+-- parser for the field value.
 readField :: String -> ReadPrec a -> ReadPrec a
 readField fieldName readVal = do
         expectP (L.Ident fieldName)
@@ -368,6 +374,12 @@ readField fieldName readVal = do
         readVal
 {-# NOINLINE readField #-}
 
+-- See Note [Why readField]
+
+-- | 'Read' parser for a symbol record field, of the form @(###)=value@ (where
+-- @###@ is the field name). The field name must be a symbol (operator-style),
+-- e.g. @(#)@. For regular (alphanumeric) field names, use 'readField'. The
+-- second argument is a parser for the field value.
 readSymField :: String -> ReadPrec a -> ReadPrec a
 readSymField fieldName readVal = do
         expectP (L.Punc "(")
@@ -377,6 +389,22 @@ readSymField fieldName readVal = do
         readVal
 {-# NOINLINE readSymField #-}
 
+
+-- Note [Why readField]
+--
+-- Previousy, the code for automatically deriving Read instance (in
+-- typecheck/TcGenDeriv.hs) would generate inline code for parsing fields;
+-- this, however, turned out to produce massive amounts of intermediate code,
+-- and produced a considerable performance hit in the code generator.
+-- Since Read instances are not generally supposed to be perfomance critical,
+-- the readField and readSymField functions have been factored out, and the
+-- code generator now just generates calls rather than manually inlining the
+-- parsers. For large record types (e.g. 500 fields), this produces a
+-- significant performance boost.
+--
+-- See also Trac #14364.
+
+
 --------------------------------------------------------------
 -- Simple instances of Read
 --------------------------------------------------------------