Finish stable split

Long ago, the stable name table and stable pointer tables were one.
Now, they are separate, and have significantly different
implementations. I believe the time has come to finish the split
that began in #7674.

* Divide `rts/Stable` into `rts/StableName` and `rts/StablePtr`.

* Give each table its own mutex.

* Add FFI functions `hs_lock_stable_ptr_table` and
`hs_unlock_stable_ptr_table` and document them.
  These are intended to replace the previously undocumented
`hs_lock_stable_tables` and `hs_lock_stable_tables`,
  which are now documented as deprecated synonyms.

* Make `eqStableName#` use pointer equality instead of unnecessarily
comparing stable name table indices.

Reviewers: simonmar, bgamari, erikd

Reviewed By: bgamari

Subscribers: rwbarton, carter

GHC Trac Issues: #15555

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

5 files changed, 59 insertions, 19 deletions

diff --git a/includes/HsFFI.h b/includes/HsFFI.h
index dea365cb65..84976474f5 100644
--- a/includes/HsFFI.h
+++ b/includes/HsFFI.h
@@ -101,8 +101,26 @@ extern void hs_thread_done (void);
 
 extern void hs_perform_gc (void);
 
+// Lock the stable pointer table. The table must be unlocked
+// again before calling any Haskell functions, even if those
+// functions do not manipulate stable pointers. The Haskell
+// garbage collector will not be able to run until this lock
+// is released! It is also forbidden to call hs_free_fun_ptr
+// or any stable pointer-related FFI functions other than
+// hs_free_stable_ptr_unsafe while the table is locked.
+extern void hs_lock_stable_ptr_table (void);
+
+// A deprecated synonym.
 extern void hs_lock_stable_tables (void);
+
+// Unlock the stable pointer table.
+extern void hs_unlock_stable_ptr_table (void);
+
+// A deprecated synonym.
 extern void hs_unlock_stable_tables (void);
+
+// Free a stable pointer assuming that the stable pointer
+// table is already locked.
 extern void hs_free_stable_ptr_unsafe (HsStablePtr sp);
 
 extern void hs_free_stable_ptr (HsStablePtr sp);
diff --git a/includes/Rts.h b/includes/Rts.h
index fc70479eb6..eb11536c19 100644
--- a/includes/Rts.h
+++ b/includes/Rts.h
@@ -198,7 +198,8 @@ void _assertFail(const char *filename, unsigned int linenum)
 #include "rts/Linker.h"
 #include "rts/Ticky.h"
 #include "rts/Timer.h"
-#include "rts/Stable.h"
+#include "rts/StablePtr.h"
+#include "rts/StableName.h"
 #include "rts/TTY.h"
 #include "rts/Utils.h"
 #include "rts/PrimFloat.h"
diff --git a/includes/rts/Stable.h b/includes/rts/StableName.h
index 4550ad6117..d43ffcb2f6 100644
--- a/includes/rts/Stable.h
+++ b/includes/rts/StableName.h
@@ -2,7 +2,7 @@
  *
  * (c) The GHC Team, 1998-2009
  *
- * Stable Pointers
+ * Stable Names
  *
  * Do not #include this file directly: #include "Rts.h" instead.
  *
@@ -13,9 +13,6 @@
 
 #pragma once
 
-EXTERN_INLINE StgPtr deRefStablePtr (StgStablePtr stable_ptr);
-StgStablePtr getStablePtr  (StgPtr p);
-
 /* -----------------------------------------------------------------------------
    PRIVATE from here.
    -------------------------------------------------------------------------- */
@@ -32,17 +29,4 @@ typedef struct {
                          // free
 } snEntry;
 
-typedef struct {
-    StgPtr addr;         // Haskell object when entry is in use, next free
-                         // entry (NULL when this is the last free entry)
-                         // otherwise.
-} spEntry;
-
 extern DLL_IMPORT_RTS snEntry *stable_name_table;
-extern DLL_IMPORT_RTS spEntry *stable_ptr_table;
-
-EXTERN_INLINE
-StgPtr deRefStablePtr(StgStablePtr sp)
-{
-    return stable_ptr_table[(StgWord)sp].addr;
-}
diff --git a/includes/rts/StablePtr.h b/includes/rts/StablePtr.h
new file mode 100644
index 0000000000..0d3642fbfe
--- /dev/null
+++ b/includes/rts/StablePtr.h
@@ -0,0 +1,35 @@
+/* -----------------------------------------------------------------------------
+ *
+ * (c) The GHC Team, 1998-2009
+ *
+ * Stable Pointers
+ *
+ * Do not #include this file directly: #include "Rts.h" instead.
+ *
+ * To understand the structure of the RTS headers, see the wiki:
+ *   http://ghc.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
+ *
+ * ---------------------------------------------------------------------------*/
+
+#pragma once
+
+EXTERN_INLINE StgPtr deRefStablePtr (StgStablePtr stable_ptr);
+StgStablePtr getStablePtr  (StgPtr p);
+
+/* -----------------------------------------------------------------------------
+   PRIVATE from here.
+   -------------------------------------------------------------------------- */
+
+typedef struct {
+    StgPtr addr;         // Haskell object when entry is in use, next free
+                         // entry (NULL when this is the last free entry)
+                         // otherwise.
+} spEntry;
+
+extern DLL_IMPORT_RTS spEntry *stable_ptr_table;
+
+EXTERN_INLINE
+StgPtr deRefStablePtr(StgStablePtr sp)
+{
+    return stable_ptr_table[(StgWord)sp].addr;
+}
diff --git a/includes/stg/MiscClosures.h b/includes/stg/MiscClosures.h
index 5328ed3f4a..c13b5ff052 100644
--- a/includes/stg/MiscClosures.h
+++ b/includes/stg/MiscClosures.h
@@ -514,8 +514,10 @@ extern StgWord RTS_VAR(atomic_modify_mutvar_mutex);
 // RtsFlags
 extern StgWord RTS_VAR(RtsFlags); // bogus type
 
-// Stable.c
+// StablePtr.c
 extern StgWord RTS_VAR(stable_ptr_table);
+
+// StableName.c
 extern StgWord RTS_VAR(stable_name_table);
 
 // Profiling.c