gh-90556: add SharedMemory.rename on multiprocessing.shared_memory

Doc/library/multiprocessing.shared_memory.rst

@@ -112,6 +112,32 @@ copying of data.
       This method has no effect on Windows, where the only way to delete a
       shared memory block is to close all handles.
 
+   .. method:: rename(newname, flags=0)
+
+      Rename the underlying shared memory block to *newname*.
+      By default, if *newname* already exists, it will be unlinked beforehand.
+
+      *flags* (0 by default) takes :ref:`bitwise ORed <bitwise>` flags together.
+
+   .. availability:: FreeBSD >= 13.0
+
+   .. versionadded:: next
+
+   .. data:: SHM_RENAME_EXCHANGE
+             SHM_RENAME_NOREPLACE
+
+      Parameters to the :func:`rename` function.
+
+      :const:`SHM_RENAME_EXCHANGE`
+        Atomically exchange the SharedMemory to the *newname*.
+
+      :const:`SHM_RENAME_NOREPLACE`
+        Raise an error if *newname* exists, rather than unlinking it.
+
+   .. availability:: FreeBSD >= 13.0
+
+   .. versionadded:: next
+
    .. attribute:: buf
 
       A memoryview of contents of the shared memory block.

Lib/multiprocessing/shared_memory.py

@@ -11,6 +11,7 @@
 from functools import partial
 import mmap
 import os
+import platform
 import errno
 import struct
 import secrets
@@ -36,6 +37,10 @@
 else:
     _SHM_NAME_PREFIX = 'wnsm_'
 
+if _USE_POSIX and hasattr(_posixshmem, "shm_rename"):
+    from _posixshmem import SHM_RENAME_EXCHANGE
+    from _posixshmem import SHM_RENAME_NOREPLACE
+
 
 def _make_filename():
     "Create a random filename for the shared memory object."
@@ -253,6 +258,27 @@ def unlink(self):
             if self._track:
                 resource_tracker.unregister(self._name, "shared_memory")
 
+    if _USE_POSIX and hasattr(_posixshmem, "shm_rename"):
+        def rename(self, newname, flags=0):
+            """Renames a shared memory block.
+
+            The policy how the operation is handled depends on the flag passed.
+            The default behavior is if the newname already exists, it will
+            be unlinked beforehand.
+            With the SHM_RENAME_EXCHANGE flag, the old and new name will
+            be exchanged.
+            With the SHM_RENAME_NOREPLACE flag, an error will be returned
+            if the new name exists.
+            """
+            oldname = self._name
+            if _USE_POSIX and self._prepend_leading_slash:
+                newname = "/" + newname
+            self._fd = _posixshmem.shm_rename(self._name, newname, flags)
+            if self._track:
+                resource_tracker.unregister(oldname, "shared_memory")
+                resource_tracker.register(newname, "shared_memory")
+            self._name = newname
+
 
 _encoding = "utf8"
 

Lib/test/_test_multiprocessing.py

@@ -4376,6 +4376,41 @@ def test_shared_memory_recreate(self):
             self.addCleanup(shm2.unlink)
             self.assertEqual(shm2._name, names[1])
 
+    @unittest.skipUnless(hasattr(shared_memory.SharedMemory, "rename"),
+                         "requires SharedMomery.rename")
+    def test_shared_memory_rename(self):
+        name1 = self._new_shm_name('testrename01_tsmb')
+        name2 = self._new_shm_name('testrename02_tsmb')
+        sms = shared_memory.SharedMemory(name1, create=True, size=512)
+        self.addCleanup(sms.unlink)
+
+        sms.rename(name2)
+        self.assertEqual(sms.name, name2)
+
+    @unittest.skipUnless(hasattr(shared_memory.SharedMemory, "rename"),
+                         "requires SharedMomery.rename")
+    def test_shared_memory_rename_noreplace(self):
+        name1 = self._new_shm_name('testrename01_tsmb')
+        name2 = self._new_shm_name('testrename02_tsmb')
+        sms1 = shared_memory.SharedMemory(name1, create=True, size=512)
+        sms2 = shared_memory.SharedMemory(name2, create=True, size=512)
+        self.addCleanup(sms1.unlink)
+        self.addCleanup(sms2.unlink)
+
+        with self.assertRaises(FileExistsError):
+            sms1.rename(name2, flags=shared_memory.SHM_RENAME_NOREPLACE)
+
+    @unittest.skipUnless(hasattr(shared_memory.SharedMemory, "rename"),
+                         "requires SharedMomery.rename")
+    def test_shared_memory_rename_exchange(self):
+        name1 = self._new_shm_name('testrename01_tsmb')
+        name2 = self._new_shm_name('testrename02_tsmb')
+        sms1 = shared_memory.SharedMemory(name1, create=True, size=512)
+        sms2 = shared_memory.SharedMemory(name2, create=True, size=512)
+        self.addCleanup(sms2.unlink)
+
+        sms1.rename(name2, flags=shared_memory.SHM_RENAME_EXCHANGE)
+
     def test_invalid_shared_memory_creation(self):
         # Test creating a shared memory segment with negative size
         with self.assertRaises(ValueError):

Misc/NEWS.d/next/Library/2022-01-17-20-03-56.bpo-46398.FATeqM.rst

@@ -0,0 +1 @@
+Add the :mod:`multiprocessing.shared_memory.SharedMemory.rename` method for FreeBSD.

Modules/_multiprocessing/posixshmem.c

@@ -73,6 +73,59 @@ _posixshmem_shm_open_impl(PyObject *module, PyObject *path, int flags,
 }
 #endif /* HAVE_SHM_OPEN */
 
+#ifdef HAVE_SHM_RENAME
+/*[clinic input]
+_posixshmem.shm_rename -> int
+    path_from: unicode
+    path_to: unicode
+    flags: int
+    /
+
+Rename a shared memory object.
+
+Remove a shared memory object and relink to another path.
+By default, if the destination path already exist, it will be unlinked.
+With the SHM_RENAME_EXCHANGE flag, source and destination paths
+will be exchanged.
+With the SHM_RENAME_NOREPLACE flag, an error will be triggered
+if the destination alredady exists.
+
+[clinic start generated code]*/
+
+static int
+_posixshmem_shm_rename_impl(PyObject *module, PyObject *path_from,
+                            PyObject *path_to, int flags)
+/*[clinic end generated code: output=d9a710c512166e18 input=5fb42d1ce077caec]*/
+{
+    int rv;
+    int async_err = 0;
+    Py_ssize_t from_size;
+    Py_ssize_t to_size;
+    const char *from = PyUnicode_AsUTF8AndSize(path_from, &from_size);
+    const char *to = PyUnicode_AsUTF8AndSize(path_to, &to_size);
+    if (from == NULL || to == NULL) {
+        return -1;
+    }
+    if (strlen(from) != (size_t)from_size || strlen(to) != (size_t)to_size) {
+        PyErr_SetString(PyExc_ValueError, "embedded null character");
+        return -1;
+    }
+    do {
+        Py_BEGIN_ALLOW_THREADS
+        rv = shm_rename(from, to, flags);
+        Py_END_ALLOW_THREADS
+    } while (rv < 0 && errno == EINTR && !(async_err = PyErr_CheckSignals()));
+
+    if (rv < 0) {
+        if (!async_err)
+            PyErr_SetFromErrnoWithFilenameObjects(PyExc_OSError, path_from, path_to);
+        return -1;
+    }
+
+    return rv;
+}
+#endif /* HAVE_SHM_RENAME */
+
 #ifdef HAVE_SHM_UNLINK
 /*[clinic input]
 _posixshmem.shm_unlink
@@ -122,12 +175,29 @@ _posixshmem_shm_unlink_impl(PyObject *module, PyObject *path)
 
 static PyMethodDef module_methods[ ] = {
     _POSIXSHMEM_SHM_OPEN_METHODDEF
+#if defined(HAVE_SHM_RENAME)
+    _POSIXSHMEM_SHM_RENAME_METHODDEF
+#endif
     _POSIXSHMEM_SHM_UNLINK_METHODDEF
     {NULL} /* Sentinel */
 };
 
+static int
+posixshmem_exec(PyObject *m)
+{
+#ifdef HAVE_SHM_RENAME
+#ifdef SHM_RENAME_EXCHANGE
+    if (PyModule_AddIntMacro(m, SHM_RENAME_EXCHANGE)) return -1;
+#endif
+#ifdef SHM_RENAME_NOREPLACE
+    if (PyModule_AddIntMacro(m, SHM_RENAME_NOREPLACE)) return -1;
+#endif
+#endif /* HAVE_SHM_RENAME */
+    return 0;
+}
 
 static PyModuleDef_Slot module_slots[] = {
+    {Py_mod_exec, posixshmem_exec},
     {Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
     {Py_mod_gil, Py_MOD_GIL_NOT_USED},
     {0, NULL}

configure.ac

@@ -7297,7 +7297,7 @@ WITH_SAVE_ENV([
   #  endif
   #endif
   "
-  AC_CHECK_FUNCS([shm_open shm_unlink], [have_posix_shmem=yes], [have_posix_shmem=no])
+  AC_CHECK_FUNCS([shm_open shm_rename shm_unlink], [have_posix_shmem=yes], [have_posix_shmem=no])
   _RESTORE_VAR([ac_includes_default])
 ])
 

pyconfig.h.in

@@ -1191,6 +1191,9 @@
 /* Define to 1 if you have the 'shm_open' function. */
 #undef HAVE_SHM_OPEN
 
+/* Define to 1 if you have the 'shm_rename' function. */
+#undef HAVE_SHM_RENAME
+
 /* Define to 1 if you have the 'shm_unlink' function. */
 #undef HAVE_SHM_UNLINK