gh-63016: Add flags parameter on mmap.flush

Doc/library/mmap.rst

@@ -212,7 +212,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
  Writable :term:`bytes-like object` is now accepted.
 
 
- .. method:: flush([offset[, size]])
+ .. method:: flush([offset[, size]], *, flags=MS_SYNC)
 
  Flushes changes made to the in-memory copy of a file back to disk. Without
  use of this call there is no guarantee that changes are written back before
@@ -221,6 +221,12 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
  whole extent of the mapping is flushed. *offset* must be a multiple of the
  :const:`PAGESIZE` or :const:`ALLOCATIONGRANULARITY`.
 
+ The *flags* parameter specifies the synchronization behavior.
+ *flags* must be one of the :ref:`MS_* constants <ms-constants>` available
+ on the system.
+
+ On Windows, the *flags* parameter is ignored.
+
  ``None`` is returned to indicate success. An exception is raised when the
  call failed.
 
@@ -235,6 +241,9 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
  specified alone, and the flush operation will extend from *offset*
  to the end of the mmap.
 
+ .. versionchanged:: next
+ Added *flags* parameter to control synchronization behavior.
+
 
  .. method:: madvise(option[, start[, length]])
 
@@ -461,3 +470,22 @@ MAP_* Constants
  :data:`MAP_TPRO`, :data:`MAP_TRANSLATED_ALLOW_EXECUTE`, and
  :data:`MAP_UNIX03` constants.
 
+.. _ms-constants:
+
+MS_* Constants
+++++++++++++++
+
+.. data:: MS_SYNC
+ MS_ASYNC
+ MS_INVALIDATE
+
+ These flags control the synchronization behavior for :meth:`mmap.flush`:
+
+ * :data:`MS_SYNC` - Synchronous flush: writes are scheduled and the call
+ blocks until they are physically written to storage.
+ * :data:`MS_ASYNC` - Asynchronous flush: writes are scheduled but the call
+ returns immediately without waiting for completion.
+ * :data:`MS_INVALIDATE` - Invalidate cached data: invalidates other mappings
+ of the same file so they can see the changes.
+
+ .. versionadded:: next

Lib/test/test_mmap.py

@@ -1166,6 +1166,15 @@ def test_flush_parameters(self):
  m.flush(PAGESIZE)
  m.flush(PAGESIZE, PAGESIZE)
 
+ if hasattr(mmap, 'MS_SYNC'):
+ m.flush(0, PAGESIZE, flags=mmap.MS_SYNC)
+ if hasattr(mmap, 'MS_ASYNC'):
+ m.flush(flags=mmap.MS_ASYNC)
+ if hasattr(mmap, 'MS_INVALIDATE'):
+ m.flush(PAGESIZE * 2, flags=mmap.MS_INVALIDATE)
+ if hasattr(mmap, 'MS_ASYNC') and hasattr(mmap, 'MS_INVALIDATE'):
+ m.flush(0, PAGESIZE, flags=mmap.MS_ASYNC | mmap.MS_INVALIDATE)
+
  @unittest.skipUnless(sys.platform == 'linux', 'Linux only')
  @support.requires_linux_version(5, 17, 0)
  def test_set_name(self):

Misc/NEWS.d/next/Core_and_Builtins/2025-10-04-20-48-02.gh-issue-63016.EC9QN_.rst

@@ -0,0 +1 @@
+Add a ``flags`` parameter to :meth:`mmap.mmap.flush` to control synchronization behavior.

Modules/mmapmodule.c

@@ -1034,12 +1034,15 @@ mmap.mmap.flush
  offset: Py_ssize_t = 0
  size: Py_ssize_t = -1
  /
+ *
+ flags: int = 0
 
 [clinic start generated code]*/
 
 static PyObject *
-mmap_mmap_flush_impl(mmap_object *self, Py_ssize_t offset, Py_ssize_t size)
-/*[clinic end generated code: output=956ced67466149cf input=c50b893bc69520ec]*/
+mmap_mmap_flush_impl(mmap_object *self, Py_ssize_t offset, Py_ssize_t size,
+ int flags)
+/*[clinic end generated code: output=4225f4174dc75a53 input=42ba5fb716b6c294]*/
 {
  CHECK_VALID(NULL);
  if (size == -1) {
@@ -1060,8 +1063,10 @@ mmap_mmap_flush_impl(mmap_object *self, Py_ssize_t offset, Py_ssize_t size)
  }
  Py_RETURN_NONE;
 #elif defined(UNIX)
- /* XXX flags for msync? */
- if (-1 == msync(self->data + offset, size, MS_SYNC)) {
+ if (flags == 0) {
+ flags = MS_SYNC;
+ }
+ if (-1 == msync(self->data + offset, size, flags)) {
  PyErr_SetFromErrno(PyExc_OSError);
  return NULL;
  }
@@ -2331,6 +2336,16 @@ mmap_exec(PyObject *module)
  ADD_INT_MACRO(module, ACCESS_WRITE);
  ADD_INT_MACRO(module, ACCESS_COPY);
 
+#ifdef MS_INVALIDATE
+ ADD_INT_MACRO(module, MS_INVALIDATE);
+#endif
+#ifdef MS_ASYNC
+ ADD_INT_MACRO(module, MS_ASYNC);
+#endif
+#ifdef MS_SYNC
+ ADD_INT_MACRO(module, MS_SYNC);
+#endif
+
 #ifdef HAVE_MADVISE
  // Conventional advice values
 #ifdef MADV_NORMAL