Add eventfd_read/write, fix value type

tiran · tiran · commit 2732046770a2 · 2020-11-13T11:27:56.000+01:00
The ``eventfd_read`` and ``eventfd_write`` functions are convenient
wrappers that perform proper read/write and conversion from/to uint64_t.

Signed-off-by: Christian Heimes &lt;christian@python.org&gt;
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -3278,52 +3278,67 @@ features:
 
 .. function:: eventfd(initval[, flags=os.EFD_CLOEXEC])
 
-   Create and return a file descriptor for event notification. An eventfd can
-   be used to implement an event wait/notify mechanisum.  See man page
-   :manpage:`eventfd(2)` for more information.  By default, the new file
-   descriptor is :ref:`non-inheritable <fd_inheritance>`.
+   Create and return an event file descriptor. The file descriptors supports
+   raw :func:`read` and :func:`write` with a buffer size of 8,
+   :func:`~select.select`, :func:`~select.poll` and similar. By default, the
+   new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
 
-   The *initval* is limited to an unsigned 32-bit integer. The Kernel object
-   holds an unsigned 64-bit integer with a maximum value of 2**64 - 2.  The
-   input value to :func:`~os.write` and output value of :func:~os.read` are
-   are unsigned 64-bit integers (8 bytes) in native byte order.  Eventfds
-   support waiting for I/O completion with :mod:`select` module.
+   If :const:`EFD_SEMAPHORE` is specified and the event counter is non-zero,
+   :func:`eventfd_read` returns 1 and decrements the counter by one.
 
-   Example::
+   If :const:`EFD_SEMAPHORE` is not specified and the event counter is
+   non-zero, :func:`eventfd_read` returns the current event counter value and
+   resets the counter to zero.
+
+   If the event counter is zero, :func:`eventfd_read` blocks.
 
-       import os
-       import struct
+   :func:`eventfd_write` increments the event counter.
 
-       format = "@Q"  # native uint64_t
-       size = struct.calcsize(format)  # 8 bytes
+   *initval* is the initial value of the event counter. It must be an
+   unsigned integer between 0 and 2\ :sup:`64`\ -\ 2.
 
-       # semaphore with start value '1'
-       fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
-       try:
-           # acquire semaphore
-           v = os.read(fd, size)
-           try:
-               assert v == struct.pack(format, 1)
-               do_work()
-           finally:
-               # release semaphore
-               os.write(fd, v)
-       finally:
-           os.close(fd)
+   *flags* can be constructed from :const:`EFD_CLOEXEC`,
+   :const:`EFD_NONBLOCK`, and :const:`EFD_SEMAPHORE`.
 
-   .. availability:: Linux 2.27 or newer with glibc 2.8 or newer.
+   .. availability:: Linux 2.6.27 or newer with glibc 2.8 or newer.
 
    .. versionadded:: 3.10
 
+.. function:: eventfd_read(fd)
+
+   Read value from an :func:`eventfd` file descriptor and return
+   an unsigned integer between 0 and 2\ :sup:`64`\ -\ 2. The function does
+   not verify that *fd* is an :func:`eventfd`.
+
+   .. versionadded:: 3.10
+
+.. function:: eventfd_write(fd, value)
+
+   Add value to an :func:`eventfd` file descriptor. *value* must be
+   an unsigned integer between 0 and 2\ :sup:`64`\ -\ 2. The function does
+   not verify that *fd* is an :func:`eventfd`.
+
+   .. versionadded:: 3.10
 
 .. data:: EFD_CLOEXEC
-          EFD_NONBLOCK
-          EFD_SEMAPHORE
 
-   These flags can be passed to :func:`eventfd`.
+   Set close-on-exec flag for new :func:`eventfd` file descriptor.
+
+   .. versionadded:: 3.10
+
+.. data:: EFD_NONBLOCK
+
+   Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
+   descriptor.
+
+   .. versionadded:: 3.10
+
+.. data:: EFD_SEMAPHORE
+
+   Provide semaphore-like semantics for reads from a :func:`eventfd` file
+   descriptor. On read the internal counter is decremented by one.
 
-   .. availability:: Linux 2.27 or newer with glibc 2.8 or newer.  The
-      ``EFD_SEMAPHORE`` flag is available since Linux 2.30.
+   .. availability:: Linux 2.6.30 or newer
 
    .. versionadded:: 3.10
 
diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py
@@ -3530,45 +3530,64 @@ def test_memfd_create(self):
 
 
 @unittest.skipUnless(hasattr(os, 'eventfd'), 'requires os.eventfd')
-@support.requires_linux_version(2, 30)
+@support.requires_linux_version(2, 6, 30)
 class EventfdTests(unittest.TestCase):
-    fmt = "@Q"  # native uint64_t
-    size = 8  # read/write 8 bytes
-
-    def pack(self, value):
-        return struct.pack(self.fmt, value)
-
     def test_eventfd_initval(self):
+        def pack(value):
+            """Pack as native uint64_t
+            """
+            return struct.pack("@Q", value)
+        size = 8  # read/write 8 bytes
         initval = 42
         fd = os.eventfd(initval)
         self.assertNotEqual(fd, -1)
         self.addCleanup(os.close, fd)
         self.assertFalse(os.get_inheritable(fd))
 
-        res = os.read(fd, self.size)
-        self.assertEqual(res, self.pack(initval))
+        # test with raw read/write
+        res = os.read(fd, size)
+        self.assertEqual(res, pack(initval))
+
+        os.write(fd, pack(23))
+        res = os.read(fd, size)
+        self.assertEqual(res, pack(23))
+
+        os.write(fd, pack(40))
+        os.write(fd, pack(2))
+        res = os.read(fd, size)
+        self.assertEqual(res, pack(42))
 
-        os.write(fd, struct.pack(self.fmt, 23))
-        res = os.read(fd, self.size)
-        self.assertEqual(res, self.pack(23))
+        # test with eventfd_read/eventfd_write
+        os.eventfd_write(fd, 20)
+        os.eventfd_write(fd, 3)
+        res = os.eventfd_read(fd)
+        self.assertEqual(res, 23)
 
     def test_eventfd_semaphore(self):
         initval = 2
-        one = self.pack(1)
-
         flags = os.EFD_CLOEXEC | os.EFD_SEMAPHORE | os.EFD_NONBLOCK
         fd = os.eventfd(initval, flags)
         self.assertNotEqual(fd, -1)
         self.addCleanup(os.close, fd)
 
         # semaphore starts has initval 2, two reads return '1'
-        res = os.read(fd, self.size)
-        self.assertEqual(res, one)
-        res = os.read(fd, self.size)
-        self.assertEqual(res, one)
+        res = os.eventfd_read(fd)
+        self.assertEqual(res, 1)
+        res = os.eventfd_read(fd)
+        self.assertEqual(res, 1)
         # third read would block
         with self.assertRaises(BlockingIOError):
-            os.read(fd, self.size)
+            os.eventfd_read(fd)
+        with self.assertRaises(BlockingIOError):
+            os.read(fd, 8)
+
+        # increase semaphore counter, read one
+        os.eventfd_write(fd, 1)
+        res = os.eventfd_read(fd)
+        self.assertEqual(res, 1)
+        # next read would block, too
+        with self.assertRaises(BlockingIOError):
+            os.eventfd_read(fd)
 
 
 class OSErrorTests(unittest.TestCase):
diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
@@ -12871,13 +12871,18 @@ os.eventfd
     initval: unsigned_int
     flags: int(c_default="EFD_CLOEXEC") = EFD_CLOEXEC
 
+Creates and returns an event notification file descriptor.
 [clinic start generated code]*/
 
 static PyObject *
 os_eventfd_impl(PyObject *module, unsigned int initval, int flags)
-/*[clinic end generated code: output=ce9c9bbd1446f2de input=93c05fbffd6a8d33]*/
+/*[clinic end generated code: output=ce9c9bbd1446f2de input=66203e3c50c4028b]*/
 {
     int fd;
+    if (initval > (PY_ULLONG_MAX - 1)) {
+        PyErr_SetString(PyExc_OverflowError, "initval too large");
+        return NULL;
+    }
     Py_BEGIN_ALLOW_THREADS
     fd = eventfd(initval, flags);
     Py_END_ALLOW_THREADS
@@ -12886,7 +12891,57 @@ os_eventfd_impl(PyObject *module, unsigned int initval, int flags)
     }
     return PyLong_FromLong(fd);
 }
-#endif
+
+/*[clinic input]
+os.eventfd_read
+
+    fd: fildes
+
+Read eventfd value
+[clinic start generated code]*/
+
+static PyObject *
+os_eventfd_read_impl(PyObject *module, int fd)
+/*[clinic end generated code: output=8f2c7b59a3521fd1 input=110f8b57fa596afe]*/
+{
+    eventfd_t value;
+    int result;
+    Py_BEGIN_ALLOW_THREADS
+    result = eventfd_read(fd, &value);
+    Py_END_ALLOW_THREADS
+    if (result == -1) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    return PyLong_FromUnsignedLongLong(value);
+}
+
+/*[clinic input]
+os.eventfd_write
+
+    fd: fildes
+    value: unsigned_long_long
+
+Write eventfd value
+[clinic start generated code]*/
+
+static PyObject *
+os_eventfd_write_impl(PyObject *module, int fd, unsigned long long value)
+/*[clinic end generated code: output=bebd9040bbf987f5 input=82da3dd0d6e62f28]*/
+{
+    int result;
+    if (value > (PY_ULLONG_MAX - 1)) {
+        PyErr_SetString(PyExc_OverflowError, "value too large");
+        return NULL;
+    }
+    Py_BEGIN_ALLOW_THREADS
+    result = eventfd_write(fd, value);
+    Py_END_ALLOW_THREADS
+    if (result == -1) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    Py_RETURN_NONE;
+}
+#endif  /* HAVE_EVENTFD */
 
 /* Terminal size querying */
 
@@ -14649,6 +14704,8 @@ static PyMethodDef posix_methods[] = {
     OS_GETRANDOM_METHODDEF
     OS_MEMFD_CREATE_METHODDEF
     OS_EVENTFD_METHODDEF
+    OS_EVENTFD_READ_METHODDEF
+    OS_EVENTFD_WRITE_METHODDEF
     OS__ADD_DLL_DIRECTORY_METHODDEF
     OS__REMOVE_DLL_DIRECTORY_METHODDEF
     OS_WAITSTATUS_TO_EXITCODE_METHODDEF
