bpo-41001: Add os.eventfd()

Doc/library/os.rst

@@ -3276,6 +3276,102 @@ features:
  .. versionadded:: 3.8
 
 
+.. function:: eventfd(initval[, flags=os.EFD_CLOEXEC])
+
+ 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. See man page
+ :manpage:`eventfd(2)` for more information. By default, the
+ new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
+
+ *initval* is the initial value of the event counter. The initial value
+ must be an 32 bit unsigned integer. Please note that the initial value is
+ limited to a 32 bit unsigned int although the event counter is an unsigned
+ 64 bit integer with a maximum value of 2\ :sup:`64`\ -\ 2.
+
+ *flags* can be constructed from :const:`EFD_CLOEXEC`,
+ :const:`EFD_NONBLOCK`, and :const:`EFD_SEMAPHORE`.
+
+ If :const:`EFD_SEMAPHORE` is specified and the event counter is non-zero,
+ :func:`eventfd_read` returns 1 and decrements the counter by one.
+
+ 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 and :const:`EFD_NONBLOCK` is not
+ specified, :func:`eventfd_read` blocks.
+
+ :func:`eventfd_write` increments the event counter. Write blocks if the
+ write operation would increment the counter to a value larger than
+ 2\ :sup:`64`\ -\ 2.
+
+ Example::
+
+ import os
+
+ # semaphore with start value '1'
+ fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
+ try:
+ # acquire semaphore
+ v = os.eventfd_read(fd)
+ try:
+ do_work()
+ finally:
+ # release semaphore
+ os.eventfd_write(fd, v)
+ finally:
+ os.close(fd)
+
+ .. 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 a 64 bit
+ unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
+
+ .. availability:: See :func:`eventfd`
+
+ .. versionadded:: 3.10
+
+.. function:: eventfd_write(fd, value)
+
+ Add value to an :func:`eventfd` file descriptor. *value* must be a 64 bit
+ unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
+
+ .. availability:: See :func:`eventfd`
+
+ .. versionadded:: 3.10
+
+.. data:: EFD_CLOEXEC
+
+ Set close-on-exec flag for new :func:`eventfd` file descriptor.
+
+ .. availability:: See :func:`eventfd`
+
+ .. versionadded:: 3.10
+
+.. data:: EFD_NONBLOCK
+
+ Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
+ descriptor.
+
+ .. availability:: See :func:`eventfd`
+
+ .. 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.6.30 or newer with glibc 2.8 or newer.
+
+ .. versionadded:: 3.10
+
+
 Linux extended attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Doc/whatsnew/3.10.rst

@@ -229,6 +229,10 @@ os
 Added :func:`os.cpu_count()` support for VxWorks RTOS.
 (Contributed by Peixing Xin in :issue:`41440`.)
 
+Added a new function :func:`os.eventfd` and related helpers to wrap the
+``eventfd2`` syscall on Linux.
+(Contributed by Christian Heimes in :issue:`41001`.)
+
 py_compile
 ----------
 

Lib/test/test_os.py

@@ -15,10 +15,12 @@
 import mmap
 import os
 import pickle
+import select
 import shutil
 import signal
 import socket
 import stat
+import struct
 import subprocess
 import sys
 import sysconfig
@@ -59,6 +61,7 @@
 except ImportError:
  INT_MAX = PY_SSIZE_T_MAX = sys.maxsize
 
+
 from test.support.script_helper import assert_python_ok
 from test.support import unix_shell
 from test.support.os_helper import FakePath
@@ -3528,6 +3531,89 @@ def test_memfd_create(self):
  self.assertFalse(os.get_inheritable(fd2))
 
 
+@unittest.skipUnless(hasattr(os, 'eventfd'), 'requires os.eventfd')
+@support.requires_linux_version(2, 6, 30)
+class EventfdTests(unittest.TestCase):
+ 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))
+
+ # 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))
+
+ # 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
+ 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.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.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)
+
+ def test_eventfd_select(self):
+ flags = os.EFD_CLOEXEC | os.EFD_NONBLOCK
+ fd = os.eventfd(0, flags)
+ self.assertNotEqual(fd, -1)
+ self.addCleanup(os.close, fd)
+
+ # counter is zero, only writeable
+ rfd, wfd, xfd = select.select([fd], [fd], [fd], 0)
+ self.assertEqual((rfd, wfd, xfd), ([], [fd], []))
+
+ # counter is non-zero, read and writeable
+ os.eventfd_write(fd, 23)
+ rfd, wfd, xfd = select.select([fd], [fd], [fd], 0)
+ self.assertEqual((rfd, wfd, xfd), ([fd], [fd], []))
+ self.assertEqual(os.eventfd_read(fd), 23)
+
+ # counter at max, only readable
+ os.eventfd_write(fd, (2**64) - 2)
+ rfd, wfd, xfd = select.select([fd], [fd], [fd], 0)
+ self.assertEqual((rfd, wfd, xfd), ([fd], [], []))
+ os.eventfd_read(fd)
+
+
 class OSErrorTests(unittest.TestCase):
  def setUp(self):
  class Str(str):

Misc/NEWS.d/next/Library/2020-06-17-12-24-26.bpo-41001.5mi7b0.rst

@@ -0,0 +1,2 @@
+Add func:`os.eventfd` to provide a low level interface for Linux's event
+notification file descriptor.