Improve internal docs

pitrou · pitrou · commit 6c594ce5f1b4 · 2023-10-14T09:45:41.000+02:00
diff --git a/Include/pythread.h b/Include/pythread.h
@@ -21,6 +21,17 @@ PyAPI_FUNC(void) _Py_NO_RETURN PyThread_exit_thread(void);
 PyAPI_FUNC(unsigned long) PyThread_get_thread_ident(void);
 
 #if !defined(Py_LIMITED_API)
+/* Thread joining APIs.
+ *
+ * These APIs have a strict contract:
+ *  - Either PyThread_join_thread or PyThread_detach_thread must be called
+ *    exactly once with the given handle.
+ *  - Calling neither PyThread_join_thread nor PyThread_detach_thread results
+ *    in a resource leak until the end of the process.
+ *  - Any other usage, such as calling both PyThread_join_thread and
+ *    PyThread_detach_thread, or calling them more than once (including
+ *    simultaneously), results in undefined behavior.
+ */
 PyAPI_FUNC(unsigned long) PyThread_start_joinable_thread(void (*func)(void *),
                                                          void *arg,
                                                          Py_uintptr_t* handle);
diff --git a/Modules/_threadmodule.c b/Modules/_threadmodule.c
@@ -1280,12 +1280,18 @@ PyDoc_STRVAR(start_new_doc,
 "start_new_thread(function, args[, kwargs[, joinable]])\n\
 (start_new() is an obsolete synonym)\n\
 \n\
-Start a new thread and return its identifier.  The thread will call the\n\
-function with positional arguments from the tuple args and keyword arguments\n\
-taken from the optional dictionary kwargs.  The thread exits when the\n\
-function returns; the return value is ignored.  The thread will also exit\n\
-when the function raises an unhandled exception; a stack trace will be\n\
-printed unless the exception is SystemExit.\n");
+Start a new thread and return its identifier.\n\
+\n\
+The thread will call the function with positional arguments from the\n\
+tuple args and keyword arguments taken from the optional dictionary\n\
+kwargs.  The thread exits when the function returns; the return value\n\
+is ignored.  The thread will also exit when the function raises an\n\
+unhandled exception; a stack trace will be printed unless the exception\n\
+is SystemExit.\n\
+If the optional joinable argument is True, then the thread must later\n\
+be joined with join_thread() or detached with detach_thread().\n\
+Failure to do so results in a system resource leak until interpreter\n\
+shutdown.\n");
 
 static PyObject *
 thread_PyThread_exit_thread(PyObject *self, PyObject *Py_UNUSED(ignored))
