gh-108277: Add wrapper for timerfd_create, timerfd_settime, and timerfd_gettime to os module

Doc/library/os.rst

@@ -3781,6 +3781,304 @@ features:
    .. versionadded:: 3.10
 
 
+Timer File Descriptors
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.3
+
+These functions provide support for Linux's *timer file descriptor* API.
+Naturally, they are all only available on Linux.
+
+The following example shows how to use a timer file descriptor
+to execute a function twice a second:
+
+.. code-block:: python
+
+   # Practical scripts should use really use a non-blocking timer,
+   # we use a blocking timer here for simplicity.
+   import os, time
+
+   # Create the timer file descriptor
+   fd = os.timerfd_create(time.CLOCK_REALTIME)
+
+   # Start the timer in 1 second, with an interval of half a second
+   os.timerfd_settime(fd, initial=1, interval=0.5)
+
+   try:
+       # Process timer events four times.
+       for _ in range(4):
+          # read() will block until the timer expires
+          _ = os.read(fd, 8)
+          print("Timer expired")
+   finally:
+       # Remember to close the timer file descriptor!
+       os.close(fd)
+
+To avoid the precision loss caused by the :class:`float` type,
+timer file descriptors allow specifying initial expiration and interval
+in integer nanoseconds with ``_ns`` variants of the functions.
+
+This example shows how :func:`~select.epoll` can be used with timer file
+descriptors to wait until the file descriptor is ready for reading:
+
+.. code-block:: python
+
+   import os, time, select, sys
+
+   # Create an epoll object
+   ep = select.epoll()
+
+   # Create timer file descriptors in non-blocking mode.
+   num = 3
+   fds = []
+   for _ in range(num):
+       fd = os.timerfd_create(time.CLOCK_REALTIME, os.TFD_NONBLOCK)
+       fds.append(fd)
+       # Register the timer file descriptor for read events
+       ep.register(fd, select.EPOLLIN)
+
+   # Start the timer with os.timerfd_settime_ns() in nanoseconds.
+   for i, fd in enumerate(fds, start=1):
+       i = i * 10**9
+       os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)
+
+   timeout=3
+   try:
+       # For simplicity, process a fixed number of timer events.
+       # Practical applications should use an infinite loop to process
+       # timer events, and use some trigger to break & stop the timer.
+       for _ in range(num*3):
+           # Wait for the timer to expire for 3 seconds.
+           events = ep.poll(timeout)
+           # XXX?: signaled events may be more than one at once.
+           print(f"Signaled events={events}")
+           for fd, event in events:
+               count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
+               print(f"Timer {fds.index(fd) + 1} expired {count} times")
+   finally:
+       for fd in fds:
+           ep.unregister(fd)
+           os.close(fd)
+       ep.close()
+
+This example shows how :func:`~select.select` can be used with timer file
+descriptors to wait until the file descriptor is ready for reading:
+
+.. code-block:: python
+
+   import os, time, select, sys
+
+   # Create timer file descriptors in non-blocking mode.
+   num = 3
+   fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)
+          for _ in range(num)]
+
+   # Start the timers with os.timerfd_settime() in seconds.
+   # Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc
+   for i, fd in enumerate(fds, start=1):
+       os.timerfd_settime(fd, initial=i/4, interval=i/4)
+
+   timeout = 3
+   try:
+       # For simplicity, process a fixed number of timer events.
+       # Practical applications should use an infinite loop to process
+       # timer events, and use some trigger to break & stop the timer.
+       for _ in range(num*3):
+           # Wait for the timer to expire for 3 seconds.
+           rfd, wfd, xfd = select.select(fds, fds, fds, timeout)
+           for fd in rfd:
+               count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
+               print(f"Timer {fds.index(fd)+1} expired {count} times")
+   finally:
+       for fd in fds:
+           os.close(fd)
+
+--------------
+
+.. function:: timerfd_create(clockid, /, *, flags=0)
+
+   Create and return a timer file descriptor (*timerfd*).
+
+   The file descriptor returned by :func:`timerfd_create` supports:
+
+      - :func:`read`
+      - :func:`~select.select`
+      - :func:`~select.poll`.
+
+   The file descriptor's :func:`read` method can be called with a buffer size of 8.
+   If the timer has already expired one or more times, :func:`read` returns
+   the number of expirations with the host's endianness,
+   which may be converted to an :class:`int` by ``int.from_bytes(x, byteorder=sys.byteorder)``.
+
+   :func:`~select.select` and :func:`~select.poll` can be used to wait until
+   timer expires and the file descriptor is readable.
+
+   *clockid* must be a valid :ref:`clock ID <time-clock-id-constants>`,
+   as defined in the :py:mod:`time` module:
+
+   - :const:`time.CLOCK_REALTIME`
+   - :const:`time.CLOCK_MONOTONIC`
+   - :const:`time.CLOCK_BOOTTIME` (Since Linux 3.15)
+
+   If *clockid* is :const:`time.CLOCK_REALTIME`, a settable system-wide real-time clock
+   is used. If system clock is changed, timer setting need to be updated.
+   To cancel timer when system clock is changed, see :const:`TFD_TIMER_CANCEL_ON_SET`.
+
+   If *clockid* is :const:`time.CLOCK_MONOTONIC`, A nonsettable monotonically increasing
+   clock is used. Even if system clock is changed, timer setting will be not affected.
+
+   If *clockid* is :const:`time.CLOCK_BOOTTIME`, same as :const:`time.CLOCK_MONOTONIC`
+   except it includes any time that the system is suspended.
+
+   The file descriptor's behaviour can be modified by specifying a *flags* value.
+   Any of the following variables may used, combined using bitwise OR
+   (the ``|`` operator):
+
+   - :const:`TFD_NONBLOCK`
+   - :const:`TFD_CLOEXEC`
+
+   If :const:`TFD_NONBLOCK` is not set as a flag, :func:`read` blocks until the timer expires.
+   If it is set as a flag, :func:`read` doesn't block, but if there is no timer expiration,
+   :func:`read` raises :class:`OSError` with ``errno`` is set to :const:`errno.EAGAIN`.
+
+   If :const:`TFD_CLOEXEC` is set as a flag, set close-on-exec flag for new file descriptor.
+
+   The file descriptor must be closed with :func:`os.close` when it is no
+   longer needed, or else the file descriptor will be leaked.
+
+   .. seealso:: The :manpage:`timerfd_create(2)` man page.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+
+.. function:: timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)
+
+   Alter a timer file descriptor's internal timer.
+   This function operates the same interval timer as :func:`timerfd_settime_ns`.
+
+   *fd* must be a valid timer file descriptor.
+
+   The timer's behaviour can be modified by specifying a *flags* value.
+   Any of the following variables may used, combined using bitwise OR
+   (the ``|`` operator):
+
+   - :const:`TFD_TIMER_ABSTIME`
+   - :const:`TFD_TIMER_CANCEL_ON_SET`
+
+   The timer is disabled by setting *initial* to zero (``0``).
+   If *initial* is equal to or greater than zero, the timer is enabled.
+   If *initial* is less than zero, it raises an :class:`OSError` exception
+   with ``errno`` set to :const:`errno.EINVAL`
+
+   By default the timer will fire when *initial* seconds have elapsed.
+   (If *initial* is zero, timer will fire immediately.)
+
+   However, if the :const:`TFD_TIMER_ABSTIME` flag is set,
+   the timer will fire when the timer's clock
+   (set by *clockid* in :func:`timerfd_create`) reaches *initial* seconds.
+
+   The timer's interval is set by the *interval* :py:class:`float`.
+   If *interval* is zero, the timer only fires once, on the initial expiration.
+   If *interval* is greater than zero, the timer fires every time *interval*
+   seconds have elapsed since the previous expiration.
+   If *interval* is less than zero, it raises :class:`OSError` with ``errno``
+   set to :const:`errno.EINVAL`
+
+   If the :const:`TFD_TIMER_CANCEL_ON_SET` flag is set along with :const:`TFD_TIMER_ABSTIME`
+   and the clock for this timer is :const:`time.CLOCK_REALTIME`, the timer is marked as
+   cancelable when if the real-time clock is changed discontinuously. Reading the descriptor
+   is aborted with with the error ECANCELED.
+
+   Linux manages system clock as UTC. A daylight-savings time transition is done
+   by changing time offset only and doesn't cause discontinuous system clock change.
+
+   Return a two-item tuple of (``next_expiration``, ``interval``) from
+   the previous timer state, before this function executed.
+
+   .. seealso::  The :manpage:`timerfd_settime(2)` man page.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+
+.. function:: timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)
+
+   Similar to :func:`timerfd_settime`, but use time as nanoseconds.
+   This function operates the same interval timer as :func:`timerfd_settime`.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+
+.. function:: timerfd_gettime(fd, /)
+
+   Return a two-item tuple of floats (``next_expiration``, ``interval``).
+
+   ``next_expiration`` denotes the relative time until next the timer next fires,
+   regardless of if the :const:`TFD_TIMER_ABSTIME` flag is set.
+
+   ``interval`` denotes the timer's interval.
+   If zero, the timer will only fire once, after ``next_expiration`` seconds have elapsed.
+
+   .. seealso:: :manpage:`timerfd_gettime(2)`
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+
+.. function:: timerfd_gettime_ns(fd, /)
+
+   Similar to :func:`timerfd_gettime`, but return time as nanoseconds.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+.. data:: TFD_NONBLOCK
+
+   A flag for the :func:`timerfd_create` function,
+   which sets the :const:`O_NONBLOCK` status flag for the new timer file descriptor.
+   If :const:`TFD_NONBLOCK` is not set as a flag, :func:`read` blocks.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+.. data:: TFD_CLOEXEC
+
+   A flag for the :func:`timerfd_create` function,
+   If :const:`TFD_CLOEXEC` is set as a flag, set close-on-exec flag for new file descriptor.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+.. data:: TFD_TIMER_ABSTIME
+
+   A flag for the :func:`timerfd_settime` and :func:`timerfd_settime_ns` functions.
+   If this flag is set, *initial* is interpreted as an absolute value on the timer's clock
+   (in UTC seconds or nanoseconds since the Unix Epoch).
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+.. data:: TFD_TIMER_CANCEL_ON_SET
+
+   A flag for the :func:`timerfd_settime` and :func:`timerfd_settime_ns` functions
+   along with :const:`TFD_TIMER_ABSTIME`.
+   The timer is cancelled when the time of the underlying clock changes discontinuously.
+
+   .. availability:: Linux >= 2.6.27 with glibc >= 2.8
+
+   .. versionadded:: 3.13
+
+
 Linux extended attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Doc/whatsnew/3.13.rst

@@ -163,6 +163,17 @@ opcode
   documented or exposed through ``dis``, and were not intended to be
   used externally.
 
+os
+--
+
+* Add a low level interface for Linux's timer notification file descriptors
+  via :func:`os.timerfd_create`,
+  :func:`os.timerfd_settime`, :func:`os.timerfd_settime_ns`,
+  :func:`os.timerfd_gettime`, and :func:`os.timerfd_gettime_ns`,
+  :const:`os.TFD_NONBLOCK`, :const:`os.TFD_CLOEXEC`,
+  :const:`os.TFD_TIMER_ABSTIME`, and :const:`os.TFD_TIMER_CANCEL_ON_SET`
+  (Contributed by Masaru Tsuchiyama in :gh:`108277`.)
+
 pathlib
 -------
 

Include/internal/pycore_global_strings.h

@@ -482,6 +482,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(instructions)
         STRUCT_FOR_ID(intern)
         STRUCT_FOR_ID(intersection)
+        STRUCT_FOR_ID(interval)
         STRUCT_FOR_ID(is_running)
         STRUCT_FOR_ID(isatty)
         STRUCT_FOR_ID(isinstance)