Generalise reallyUnsafePtrEquality# and use it

fixes #9192 and #17126
updates containers submodule

1. Changes the type of the primop `reallyUnsafePtrEquality#` to the most
general version possible (heterogeneous as well as levity-polymorphic):

> reallyUnsafePtrEquality#
>   :: forall {l :: Levity} {k :: Levity}
>        (a :: TYPE (BoxedRep l)) (b :: TYPE (BoxedRep k))
>   . a -> b -> Int#

2. Adds a new internal module, `GHC.Ext.PtrEq`, which contains pointer
equality operations that are now subsumed by `reallyUnsafePtrEquality#`.
These functions are then re-exported by `GHC.Exts` (so that no function
goes missing from the export list of `GHC.Exts`, which is user-facing).
More specifically, `GHC.Ext.PtrEq` defines:

  - A new function:
    * reallyUnsafePtrEquality :: forall (a :: Type). a -> a -> Int#

  - Library definitions of ex-primops:
     * `sameMutableArray#`
     * `sameSmallMutableArray`
     * `sameMutableByteArray#`
     * `sameMutableArrayArray#`
     * `sameMutVar#`
     * `sameTVar#`
     * `sameMVar#`
     * `sameIOPort#`
     * `eqStableName#`

  - New functions for comparing non-mutable arrays:
     * `sameArray#`
     * `sameSmallArray#`
     * `sameByteArray#`
     * `sameArrayArray#`

  These were requested in #9192.

Generally speaking, existing libraries that
use `reallyUnsafePtrEquality#` will continue to work with the new,
levity-polymorphic version. But not all!
Some (`containers`, `unordered-containers`, `dependent-map`) contain
the following:

> unsafeCoerce# reallyUnsafePtrEquality# a b

If we make `reallyUnsafePtrEquality#` levity-polymorphic, this code
fails the current GHC representation-polymorphism checks.
We agreed that the right solution here is to modify the library;
in this case by deleting the call to `unsafeCoerce#`,
since `reallyUnsafePtrEquality#` is now type-heterogeneous too.

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/users_guide/9.4.1-notes.rst b/docs/users_guide/9.4.1-notes.rst
index 68417b0a6b..655e672a1b 100644
--- a/docs/users_guide/9.4.1-notes.rst
+++ b/docs/users_guide/9.4.1-notes.rst
@@ -41,6 +41,32 @@ Version 9.4.1
 
         raise# :: forall (a :: Type) {r :: RuntimeRep} (b :: TYPE r). a -> b
 
+- ``GHC.Exts.reallyUnsafePtrEquality#`` has been made more general, as it is now
+   both levity-polymorphic and heterogeneous: ::
+
+        reallyUnsafePtrEquality#
+          :: forall {l :: Levity} (a :: TYPE (BoxedRep l))
+                    {k :: Levity} (b :: TYPE (BoxedRep k))
+          . a -> b -> Int#
+
+   This means that ``GHC.Exts.reallyUnsafePtrEquality#`` can be used
+   on primitive arrays such as ``GHC.Exts.Array#`` and ``GHC.Exts.ByteArray#``.
+   It can also be used on values of different types, without needing to call
+   ``GHC.Exts.unsafeCoerce#``.
+
+- Added ``GHC.Exts.reallyUnsafePtrEquality`` which recovers the
+  previous behaviour of ``GHC.Exts.reallyUnsafePtrEquality#``: ::
+
+        reallyUnsafePtrEquality :: forall (a :: Type). a -> a -> Int#
+
+- Added ``GHC.Exts.sameArray#``, ``GHC.Exts.sameSmallArray#``,
+  ``GHC.Exts.sameByteArray#`` and ``GHC.Exts.sameArrayArray#``: ::
+ 
+        sameArray# :: Array# a -> Array# a -> Int#
+        sameSmallArray# :: SmallArray# a -> SmallArray# a -> Int#
+        sameByteArray# :: ByteArray# -> ByteArray# -> Int#
+        sameArrayArray# :: ArrayArray# -> ArrayArray# -> Int#
+
 ``ghc`` library
 ~~~~~~~~~~~~~~~