Move NUMUSERTYPES thread safety discussion to legacy DType API docs

Author: ngoldbaum

doc/source/reference/c-api/array.rst

@@ -1264,6 +1264,13 @@ User-defined data types
     registered (checked only by the address of the pointer), then
     return the previously-assigned type-number.
 
+    The number of user DTypes known to numpy is stored in
+    ``NPY_NUMUSERTYPES``, a static global variable that is public in the
+    C API.  Accessing this symbol is inherently *not* thread-safe. If
+    for some reason you need to use this API in a multithreaded context,
+    you will need to add your own locking, NumPy does not ensure new
+    data types can be added in a thread-safe manner.
+
 .. c:function:: int PyArray_RegisterCastFunc( \
         PyArray_Descr* descr, int totype, PyArray_VectorUnaryFunc* castfunc)
 

doc/source/reference/global_state.rst

@@ -1,13 +1,13 @@
 .. _global_state:
 
-************
-Global state
-************
+****************************
+Global Configuration Options
+****************************
 
-NumPy exposes global state in legacy APIs and a few import-time,
-compile-time, or runtime options which change the global behaviour.
-Most of these are related to performance or for debugging purposes and
-will not be interesting to the vast majority of users.
+NumPy has a few import-time, compile-time, or runtime configuration
+options which change the global behaviour.  Most of these are related to
+performance or for debugging purposes and will not be interesting to the
+vast majority of users.
 
 
 Performance-related options
@@ -70,10 +70,3 @@ and set the ``ndarray.base``.
 
 .. versionchanged:: 1.25.2
     This variable is only checked on the first import.
-
-Legacy User DTypes
-==================
-
-The number of legacy user DTypes is stored in ``NPY_NUMUSERTPES``, a global
-variable that is exposed in the NumPy C API. This means that the legacy DType
-API is inherently not thread-safe.

doc/source/user/c-info.beyond-basics.rst

@@ -268,6 +268,9 @@ specifies your data-type. This type number should be stored and made
 available by your module so that other modules can use it to recognize
 your data-type.
 
+Note that this API is inherently thread-unsafe. See `thread_safety` for more
+details about thread safety in NumPy.
+
 
 Registering a casting function
 ------------------------------