GitLab

Reviewers: austin, rwbarton, simonmar, hvr, bgamari

Reviewed By: rwbarton, simonmar

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2970

Reviewers: simonmar, austin, hvr, bgamari

Reviewed By: bgamari

Subscribers: RyanGlScott, thomie

Differential Revision: https://phabricator.haskell.org/D2900

This matches the implementations of `castPtr` and `castFunPtr`.

Add @since annotations to instances in `base`.

Test Plan:
 * ./validate  # some commets shouldn't break the build
 * review the annotations for absurdities.

Reviewers: ekmett, goldfire, RyanGlScott, austin, hvr, bgamari

Reviewed By: RyanGlScott, hvr, bgamari

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2277

GHC Trac Issues: #11767

This introduces "freezing," an operation which prevents further
locations from being appended to a CallStack.  Library authors may want
to prevent CallStacks from exposing implementation details, as a matter
of hygiene. For example, in

```
head [] = error "head: empty list"

ghci> head []
*** Exception: head: empty list
CallStack (from implicit params):
  error, called at ...
```

including the call-site of `error` in `head` is not strictly necessary
as the error message already specifies clearly where the error came
from.

So we add a function `freezeCallStack` that wraps an existing CallStack,
preventing further call-sites from being pushed onto it. In other words,

```
pushCallStack callSite (freezeCallStack callStack) = freezeCallStack callStack
```

Now we can define `head` to not produce a CallStack at all

```
head [] =
  let ?callStack = freezeCallStack emptyCallStack
  in error "head: empty list"

ghci> head []
*** Exception: head: empty list
CallStack (from implicit params):
  error, called at ...
```

---

1. We add the `freezeCallStack` and `emptyCallStack` and update the
   definition of `CallStack` to support this functionality.

2. We add `errorWithoutStackTrace`, a variant of `error` that does not
   produce a stack trace, using this feature. I think this is a sensible
   wrapper function to provide in case users want it.

3. We replace uses of `error` in base with `errorWithoutStackTrace`. The
   rationale is that base does not export any functions that use CallStacks
   (except for `error` and `undefined`) so there's no way for the stack
   traces (from Implicit CallStacks) to include user-defined functions.
   They'll only contain the call to `error` itself. As base already has a
   good habit of providing useful error messages that name the triggering
   function, the stack trace really just adds noise to the error. (I don't
   have a strong opinion on whether we should include this third commit,
   but the change was very mechanical so I thought I'd include it anyway in
   case there's interest)

4. Updates tests in `array` and `stm` submodules

Test Plan: ./validate, new test is T11049

Reviewers: simonpj, nomeata, goldfire, austin, hvr, bgamari

Reviewed By: simonpj

Subscribers: thomie

Projects: #ghc

Differential Revision: https://phabricator.haskell.org/D1628

GHC Trac Issues: #11049

To quote Simon Marlow,

    We don't expect users to ever write code that uses mkWeak# or
    finalizeWeak#, we have safe interfaces to these. Let's document the type
    unsafety and fix the problem with () without introducing any overhead.

Updates stm submodule.

Summary: See Note [MallocPtr finalizers]

Test Plan: validate; new test T10904

Reviewers: ezyang, bgamari, austin, hvr, rwbarton

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D1275

Previously the types needlessly used (), which is defined ghc-prim,
leading to unfortunate import cycles. See #10867 for details.

Updates stm submodule.

Thanks to #9858 `Typeable` doesn't need to be explicitly derived anymore.
This also makes `AutoDeriveTypeable` redundant, as well as some imports of
`Typeable` (removal of whose may be beneficial to #9707). This commit
removes several such now redundant use-sites in `base`.

Reviewed By: austin, ekmett

Differential Revision: https://phabricator.haskell.org/D712

...several modules in `base` recently touched by me

This simplifies the import graph and more importantly removes import
cycles that arise due to `Control.Monad` & `Data.List` importing
`Data.Traversable` (preparation for #9586)

Reviewed By: ekmett, austin

Differential Revision: https://phabricator.haskell.org/D234

This is a first step towards addressing #9111

This results in the following additional Typeable (exported) instances
being generated (list was compiled by diff'ing hoogle txt output):

  instance Typeable CFile
  instance Typeable 'CFile
  instance Typeable CFpos
  instance Typeable 'CFpos
  instance Typeable CJmpBuf
  instance Typeable 'CJmpBuf
  instance Typeable ChItem
  instance Typeable QSem
  instance Typeable ID
  instance Typeable 'ID
  instance Typeable CONST
  instance Typeable Qi
  instance Typeable Qr
  instance Typeable Mp
  instance Typeable ConstrRep
  instance Typeable Fixity
  instance Typeable 'Prefix
  instance Typeable 'Infix
  instance Typeable Constr
  instance Typeable DataType
  instance Typeable DataRep
  instance Typeable Data
  instance Typeable HasResolution
  instance Typeable IsList
Signed-off-by: Herbert Valerio Riedel <hvr@gnu.org>

The now obsolete (and redundant) `#hide` pragmas have been superseded by
`{-# OPTIONS_HADDOCK hide #-}` pragmas which are used by most of the
affected modules anyway.

This commit also adds proper `{-# OPTIONS_HADDOCK hide #-}` pragmas to
`GHC.Desugar` and `GHC.IO.Encoding.Iconv` which had only the ineffective
`#hide` annotation.
Signed-off-by: Herbert Valerio Riedel <hvr@gnu.org>

With GHC 7.8's PolyKinds the macros in `<Typeable.h>` are no longer of any
use, and their use is clearly obsolete. The sites using those macros are
replaced by auto-derivations of `Typeable` instances.

This reduces reliance on the CPP extension and the compile dependency on
`Typeable.h` in a couple of modules.
Signed-off-by: Herbert Valerio Riedel <hvr@gnu.org>

* Do not have have an hs-boot file for Data.Typeable
* Instead make all the loops go through
     GHC.Err (just a couple of magic functions)
     GHC.Exception (some non-exceptional functions)

The main idea is
  a) don't involve classes in the hs-boot world
  b) loop through error cases where performance doesn't matter
  c) be careful not to SOURCE import things that are bottom,
     unless MkCore knows about them in eRROR_IDS, so that we
     see their strictness

It can't be any other calling convention, e.g. stdcall.

See: #7067
See: http://hackage.haskell.org/trac/ghc/ticket/7067
See: http://www.haskell.org/pipermail/glasgow-haskell-users/2012-July/022579.html

As well as being more pleasant, this fixes #1841:
    Data.Typeable: Instances of basic types don't provide qualified
    strings to mkTyCon

Add explicit {-# LANGUAGE xxx #-} pragmas to each module, that say
what extensions that module uses.  This makes it clearer where
different extensions are used in the (large, variagated) base package.

Now base.cabal doesn't need any extensions field

Thanks to Bas van Dijk for doing all the work.

These unused imports are detected by the new unused-import code

Highlights:

* Unicode support for Handle I/O:

  ** Automatic encoding and decoding using a per-Handle encoding.

  ** The encoding defaults to the locale encoding (only on Unix 
     so far, perhaps Windows later).

  ** Built-in UTF-8, UTF-16 (BE/LE), and UTF-32 (BE/LE) codecs.

  ** iconv-based codec for other encodings on Unix

* Modularity: the low-level IO interface is exposed as a type class
  (GHC.IO.IODevice) so you can build your own low-level IO providers and
  make Handles from them.

* Newline translation: instead of being Windows-specific wired-in
  magic, the translation from \r\n -> \n and back again is available
  on all platforms and is configurable for reading/writing
  independently.


Unicode-aware Handles
~~~~~~~~~~~~~~~~~~~~~

This is a significant restructuring of the Handle implementation with
the primary goal of supporting Unicode character encodings.

The only change to the existing behaviour is that by default, text IO
is done in the prevailing locale encoding of the system (except on
Windows [1]).  

Handles created by openBinaryFile use the Latin-1 encoding, as do
Handles placed in binary mode using hSetBinaryMode.

We provide a way to change the encoding for an existing Handle:

   GHC.IO.Handle.hSetEncoding :: Handle -> TextEncoding -> IO ()

and various encodings (from GHC.IO.Encoding):

   latin1,
   utf8,
   utf16, utf16le, utf16be,
   utf32, utf32le, utf32be,
   localeEncoding,

and a way to lookup other encodings:

   GHC.IO.Encoding.mkTextEncoding :: String -> IO TextEncoding

(it's system-dependent whether the requested encoding will be
available).

We may want to export these from somewhere more permanent; that's a
topic for a future library proposal.

Thanks to suggestions from Duncan Coutts, it's possible to call
hSetEncoding even on buffered read Handles, and the right thing
happens.  So we can read from text streams that include multiple
encodings, such as an HTTP response or email message, without having
to turn buffering off (though there is a penalty for switching
encodings on a buffered Handle, as the IO system has to do some
re-decoding to figure out where it should start reading from again).

If there is a decoding error, it is reported when an attempt is made
to read the offending character from the Handle, as you would expect.

Performance varies.  For "hGetContents >>= putStr" I found the new
library was faster on my x86_64 machine, but slower on an x86.  On the
whole I'd expect things to be a bit slower due to the extra
decoding/encoding, but probabaly not noticeably.  If performance is
critical for your app, then you should be using bytestring and text
anyway.

[1] Note: locale encoding is not currently implemented on Windows due
to the built-in Win32 APIs for encoding/decoding not being sufficient
for our purposes.  Ask me for details.  Offers of help gratefully
accepted.


Newline Translation
~~~~~~~~~~~~~~~~~~~

In the old IO library, text-mode Handles on Windows had automatic
translation from \r\n -> \n on input, and the opposite on output.  It
was implemented using the underlying CRT functions, which meant that
there were certain odd restrictions, such as read/write text handles
needing to be unbuffered, and seeking not working at all on text
Handles.

In the rewrite, newline translation is now implemented in the upper
layers, as it needs to be since we have to perform Unicode decoding
before newline translation.  This means that it is now available on
all platforms, which can be quite handy for writing portable code.

For now, I have left the behaviour as it was, namely \r\n -> \n on
Windows, and no translation on Unix.  However, another reasonable
default (similar to what Python does) would be to do \r\n -> \n on
input, and convert to the platform-native representation (either \r\n
or \n) on output.  This is called universalNewlineMode (below).

The API is as follows.  (available from GHC.IO.Handle for now, again
this is something we will probably want to try to get into System.IO
at some point):

-- | The representation of a newline in the external file or stream.
data Newline = LF    -- ^ "\n"
             | CRLF  -- ^ "\r\n"
             deriving Eq

-- | Specifies the translation, if any, of newline characters between
-- internal Strings and the external file or stream.  Haskell Strings
-- are assumed to represent newlines with the '\n' character; the
-- newline mode specifies how to translate '\n' on output, and what to
-- translate into '\n' on input.
data NewlineMode 
  = NewlineMode { inputNL :: Newline,
                    -- ^ the representation of newlines on input
                  outputNL :: Newline
                    -- ^ the representation of newlines on output
                 }
             deriving Eq

-- | The native newline representation for the current platform
nativeNewline :: Newline

-- | Map "\r\n" into "\n" on input, and "\n" to the native newline
-- represetnation on output.  This mode can be used on any platform, and
-- works with text files using any newline convention.  The downside is
-- that @readFile a >>= writeFile b@ might yield a different file.
universalNewlineMode :: NewlineMode
universalNewlineMode  = NewlineMode { inputNL  = CRLF, 
                                      outputNL = nativeNewline }

-- | Use the native newline representation on both input and output
nativeNewlineMode    :: NewlineMode
nativeNewlineMode     = NewlineMode { inputNL  = nativeNewline, 
                                      outputNL = nativeNewline }

-- | Do no newline translation at all.
noNewlineTranslation :: NewlineMode
noNewlineTranslation  = NewlineMode { inputNL  = LF, outputNL = LF }


-- | Change the newline translation mode on the Handle.
hSetNewlineMode :: Handle -> NewlineMode -> IO ()



IO Devices
~~~~~~~~~~

The major change here is that the implementation of the Handle
operations is separated from the underlying IO device, using type
classes.  File descriptors are just one IO provider; I have also
implemented memory-mapped files (good for random-access read/write)
and a Handle that pipes output to a Chan (useful for testing code that
writes to a Handle).  New kinds of Handle can be implemented outside
the base package, for instance someone could write bytestringToHandle.
A Handle is made using mkFileHandle:

-- | makes a new 'Handle'
mkFileHandle :: (IODevice dev, BufferedIO dev, Typeable dev)
              => dev -- ^ the underlying IO device, which must support
                     -- 'IODevice', 'BufferedIO' and 'Typeable'
              -> FilePath
                     -- ^ a string describing the 'Handle', e.g. the file
                     -- path for a file.  Used in error messages.
              -> IOMode
                     -- ^ The mode in which the 'Handle' is to be used
              -> Maybe TextEncoding
                     -- ^ text encoding to use, if any
              -> NewlineMode
                     -- ^ newline translation mode
              -> IO Handle

This also means that someone can write a completely new IO
implementation on Windows based on native Win32 HANDLEs, and
distribute it as a separate package (I really hope somebody does
this!).

This restructuring isn't as radical as previous designs.  I haven't
made any attempt to make a separate binary I/O layer, for example
(although hGetBuf/hPutBuf do bypass the text encoding and newline
translation).  The main goal here was to get Unicode support in, and
to allow others to experiment with making new kinds of Handle.  We
could split up the layers further later.


API changes and Module structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NB. GHC.IOBase and GHC.Handle are now DEPRECATED (they are still
present, but are just re-exporting things from other modules now).
For 6.12 we'll want to bump base to version 5 and add a base4-compat.
For now I'm using #if __GLASGOW_HASKEL__ >= 611 to avoid deprecated
warnings.

I split modules into smaller parts in many places.  For example, we
now have GHC.IORef, GHC.MVar and GHC.IOArray containing the
implementations of IORef, MVar and IOArray respectively.  This was
necessary for untangling dependencies, but it also makes things easier
to follow.

The new module structurue for the IO-relatied parts of the base
package is:

GHC.IO
   Implementation of the IO monad; unsafe*; throw/catch

GHC.IO.IOMode
   The IOMode type

GHC.IO.Buffer
   Buffers and operations on them

GHC.IO.Device
   The IODevice and RawIO classes.

GHC.IO.BufferedIO
   The BufferedIO class.

GHC.IO.FD
   The FD type, with instances of IODevice, RawIO and BufferedIO.

GHC.IO.Exception
   IO-related Exceptions

GHC.IO.Encoding
   The TextEncoding type; built-in TextEncodings; mkTextEncoding

GHC.IO.Encoding.Types
GHC.IO.Encoding.Iconv
GHC.IO.Encoding.Latin1
GHC.IO.Encoding.UTF8
GHC.IO.Encoding.UTF16
GHC.IO.Encoding.UTF32
   Implementation internals for GHC.IO.Encoding

GHC.IO.Handle
   The main API for GHC's Handle implementation, provides all the Handle
   operations + mkFileHandle + hSetEncoding.

GHC.IO.Handle.Types
GHC.IO.Handle.Internals
GHC.IO.Handle.Text
   Implementation of Handles and operations.

GHC.IO.Handle.FD
   Parts of the Handle API implemented by file-descriptors: openFile,
   stdin, stdout, stderr, fdToHandle etc.

 - add newAlignedPinnedByteArray# for allocating pinned BAs with
   arbitrary alignment

 - the old newPinnedByteArray# now aligns to 16 bytes

Foreign.alloca will use newAlignedPinnedByteArray#, and so might end
up wasting less space than before (we used to align to 8 by default).
Foreign.allocaBytes and Foreign.mallocForeignPtrBytes will get 16-byte
aligned memory, which is enough to avoid problems with SSE
instructions on x86, for example.

There was a bug in the old newPinnedByteArray#: it aligned to 8 bytes,
but would have failed if the header was not a multiple of 8
(fortunately it always was, even with profiling).  Also we
occasionally wasted some space unnecessarily due to alignment in
allocatePinned().

I haven't done anything about Foreign.malloc/mallocBytes, which will
give you the same alignment guarantees as malloc() (8 bytes on
Linux/x86 here).

Patch amended by Simon Marlow:
  - mkWeakFinalizer# commoned up with mkWeakFinalizerEnv#