prepare for FF

python · blaisep · May 11, 2021 · May 12, 2021 · May 12, 2021 · May 12, 2021
commit 03bef0a859c04dd409644b92331483ff19d0c2d1
diff --git a/Doc/c-api/hash.rst b/Doc/c-api/hash.rst
@@ -0,0 +1,61 @@
+.. highlight:: c
+
+PyHash API
+----------
+
+See also the :c:member:`PyTypeObject.tp_hash` member.
+
+.. c:type:: Py_hash_t
+
+   Hash value type: signed integer.
+
+   .. versionadded:: 3.2
+
+.. c:type:: Py_uhash_t
+
+   Hash value type: unsigned integer.
+
+   .. versionadded:: 3.2
+
+
+.. c:type:: PyHash_FuncDef
+
+   Hash function definition used by :c:func:`PyHash_GetFuncDef`.
+
+   .. c::member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
+
+      Hash function.
+
+   .. c:member:: const char *name
+
+      Hash function name (UTF-8 encoded string).
+
+   .. c:member:: const int hash_bits
+
+      Internal size of the hash value in bits.
+
+   .. c:member:: const int seed_bits
+
+      Size of seed input in bits.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyHash_FuncDef* PyHash_GetFuncDef(void)
+
+   Get the hash function definition.
+
+   .. seealso::
+      :pep:`456` "Secure and interchangeable hash algorithm".
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: Py_hash_t Py_HashPointer(const void *ptr)
+
+   Hash a pointer value: process the pointer value as an integer (cast it to
+   ``uintptr_t`` internally). The pointer is not dereferenced.
+
+   The function cannot fail: it cannot return ``-1``.
+
+   .. versionadded:: 3.13
diff --git a/Doc/howto/timerfd.rst b/Doc/howto/timerfd.rst
@@ -0,0 +1,230 @@
+.. _timerfd-howto:
+
+*****************************
+  timer file descriptor HOWTO
+*****************************
+
+:Release: 1.13
+
+This HOWTO discusses Python's support for the linux timer file descriptor.
+
+
+Examples
+========
+
+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, socket, sys
+
+   # Create an epoll object
+   ep = select.epoll()
+
+   # In this example, use loopback address to send "stop" command to the server.
+   #
+   # $ telnet 127.0.0.1 1234
+   # Trying 127.0.0.1...
+   # Connected to 127.0.0.1.
+   # Escape character is '^]'.
+   # stop
+   # Connection closed by foreign host.
+   #
+   sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+   sock.bind(("127.0.0.1", 1234))
+   sock.setblocking(False)
+   sock.listen(1)
+   ep.register(sock, select.EPOLLIN)
+
+   # Create timer file descriptors in non-blocking mode.
+   num = 3
+   fds = []
+   for _ in range(num):
+       fd = os.timerfd_create(time.CLOCK_REALTIME, flags=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.
+   # Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc
+   for i, fd in enumerate(fds, start=1):
+       one_sec_in_nsec = 10**9
+       i = i * one_sec_in_nsec
+       os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)
+
+   timeout = 3
+   try:
+       conn = None
+       is_active = True
+       while is_active:
+           # Wait for the timer to expire for 3 seconds.
+           # epoll.poll() returns a list of (fd, event) pairs.
+           # fd is a file descriptor.
+           # sock and conn[=returned value of socket.accept()] are socket objects, not file descriptors.
+           # So use sock.fileno() and conn.fileno() to get the file descriptors.
+           events = ep.poll(timeout)
+
+           # If more than one timer file descriptors are ready for reading at once,
+           # epoll.poll() returns a list of (fd, event) pairs.
+           #
+           # In this example settings,
+           #    1st timer fires every 0.25 seconds in 0.25 seconds. (0.25, 0.5, 0.75, 1.0, ...)
+           #    2nd timer every 0.5 seconds in 0.5 seconds. (0.5, 1.0, 1.5, 2.0, ...)
+           #    3rd timer every 0.75 seconds in 0.75 seconds. (0.75, 1.5, 2.25, 3.0, ...)
+           #
+           #    In 0.25 seconds, only 1st timer fires.
+           #    In 0.5 seconds, 1st timer and 2nd timer fires at once.
+           #    In 0.75 seconds, 1st timer and 3rd timer fires at once.
+           #    In 1.5 seconds, 1st timer, 2nd timer and 3rd timer fires at once.
+           #
+           # If a timer file descriptor is signaled more than once since
+           # the last os.read() call, os.read() returns the nubmer of signaled
+           # as host order of class bytes.
+           print(f"Signaled events={events}")
+           for fd, event in events:
+               if event & select.EPOLLIN:
+                   if fd == sock.fileno():
+                       # Check if there is a connection request.
+                       print(f"Accepting connection {fd}")
+                       conn, addr = sock.accept()
+                       conn.setblocking(False)
+                       print(f"Accepted connection {conn} from {addr}")
+                       ep.register(conn, select.EPOLLIN)
+                   elif conn and fd == conn.fileno():
+                       # Check if there is data to read.
+                       print(f"Reading data {fd}")
+                       data = conn.recv(1024)
+                       if data:
+                           # You should catch UnicodeDecodeError exception for safety.
+                           cmd = data.decode()
+                           if cmd.startswith("stop"):
+                               print(f"Stopping server")
+                               is_active = False
+                           else:
+                               print(f"Unknown command: {cmd}")
+                       else:
+                           # No more data, close connection
+                           print(f"Closing connection {fd}")
+                           ep.unregister(conn)
+                           conn.close()
+                           conn = None
+                   elif fd in fds:
+                       print(f"Reading timer {fd}")
+                       count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
+                       print(f"Timer {fds.index(fd) + 1} expired {count} times")
+                   else:
+                       print(f"Unknown file descriptor {fd}")
+   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, socket, sys
+
+   # In this example, use loopback address to send "stop" command to the server.
+   #
+   # $ telnet 127.0.0.1 1234
+   # Trying 127.0.0.1...
+   # Connected to 127.0.0.1.
+   # Escape character is '^]'.
+   # stop
+   # Connection closed by foreign host.
+   #
+   sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+   sock.bind(("127.0.0.1", 1234))
+   sock.setblocking(False)
+   sock.listen(1)
+
+   # 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)]
+   select_fds = fds + [sock]
+
+   # 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:
+       conn = None
+       is_active = True
+       while is_active:
+          # Wait for the timer to expire for 3 seconds.
+          # select.select() returns a list of file descriptors or objects.
+          rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, timeout)
+          for fd in rfd:
+              if fd == sock:
+                  # Check if there is a connection request.
+                  print(f"Accepting connection {fd}")
+                  conn, addr = sock.accept()
+                  conn.setblocking(False)
+                  print(f"Accepted connection {conn} from {addr}")
+                  select_fds.append(conn)
+              elif conn and fd == conn:
+                  # Check if there is data to read.
+                  print(f"Reading data {fd}")
+                  data = conn.recv(1024)
+                  if data:
+                      # You should catch UnicodeDecodeError exception for safety.
+                      cmd = data.decode()
+                      if cmd.startswith("stop"):
+                          print(f"Stopping server")
+                          is_active = False
+                      else:
+                          print(f"Unknown command: {cmd}")
+                  else:
+                      # No more data, close connection
+                      print(f"Closing connection {fd}")
+                      select_fds.remove(conn)
+                      conn.close()
+                      conn = None
+              elif fd in fds:
+                  print(f"Reading timer {fd}")
+                  count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
+                  print(f"Timer {fds.index(fd) + 1} expired {count} times")
+              else:
+                  print(f"Unknown file descriptor {fd}")
+   finally:
+       for fd in fds:
+          os.close(fd)
+       sock.close()
+       sock = None
+
diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
@@ -0,0 +1,57 @@
+++++++++++++++++++++++++++++++++++++
+Modules command-line interface (CLI)
+++++++++++++++++++++++++++++++++++++
+
+The following modules have a command-line interface.
+
+* :ref:`ast <ast-cli>`
+* :ref:`asyncio <asyncio-cli>`
+* :mod:`base64`
+* :ref:`calendar <calendar-cli>`
+* :mod:`code`
+* :ref:`compileall <compileall-cli>`
+* :mod:`cProfile`: see :ref:`profile <profile-cli>`
+* :ref:`difflib <difflib-interface>`
+* :ref:`dis <dis-cli>`
+* :mod:`doctest`
+* :mod:`!encodings.rot_13`
+* :mod:`ensurepip`
+* :mod:`filecmp`
+* :mod:`fileinput`
+* :mod:`ftplib`
+* :ref:`gzip <gzip-cli>`
+* :ref:`http.server <http-server-cli>`
+* :mod:`!idlelib`
+* :ref:`inspect <inspect-module-cli>`
+* :ref:`json.tool <json-commandline>`
+* :mod:`mimetypes`
+* :mod:`pdb`
+* :mod:`pickle`
+* :ref:`pickletools <pickletools-cli>`
+* :mod:`platform`
+* :mod:`poplib`
+* :ref:`profile <profile-cli>`
+* :mod:`pstats`
+* :ref:`py_compile <py_compile-cli>`
+* :mod:`pyclbr`
+* :mod:`pydoc`
+* :mod:`quopri`
+* :mod:`runpy`
+* :ref:`site <site-commandline>`
+* :ref:`sqlite3 <sqlite3-cli>`
+* :ref:`sysconfig <sysconfig-cli>`
+* :mod:`tabnanny`
+* :ref:`tarfile <tarfile-commandline>`
+* :mod:`!this`
+* :ref:`timeit <timeit-command-line-interface>`
+* :ref:`tokenize <tokenize-cli>`
+* :ref:`trace <trace-cli>`
+* :mod:`turtledemo`
+* :ref:`unittest <unittest-command-line-interface>`
+* :ref:`uuid <uuid-cli>`
+* :mod:`venv`
+* :mod:`webbrowser`
+* :ref:`zipapp <zipapp-command-line-interface>`
+* :ref:`zipfile <zipfile-commandline>`
+
+See also the :ref:`Python command-line interface <using-on-general>`.
diff --git a/Include/cpython/pyhash.h b/Include/cpython/pyhash.h
@@ -0,0 +1,39 @@
+#ifndef Py_CPYTHON_HASH_H
+#  error "this header file must not be included directly"
+#endif
+
+/* Prime multiplier used in string and various other hashes. */
+#define _PyHASH_MULTIPLIER 1000003UL  /* 0xf4243 */
+
+/* Parameters used for the numeric hash implementation.  See notes for
+   _Py_HashDouble in Python/pyhash.c.  Numeric hashes are based on
+   reduction modulo the prime 2**_PyHASH_BITS - 1. */
+
+#if SIZEOF_VOID_P >= 8
+#  define _PyHASH_BITS 61
+#else
+#  define _PyHASH_BITS 31
+#endif
+
+#define _PyHASH_MODULUS (((size_t)1 << _PyHASH_BITS) - 1)
+#define _PyHASH_INF 314159
+#define _PyHASH_IMAG _PyHASH_MULTIPLIER
+
+/* Helpers for hash functions */
+PyAPI_FUNC(Py_hash_t) _Py_HashDouble(PyObject *, double);
+
+// Kept for backward compatibility
+#define _Py_HashPointer Py_HashPointer
+
+
+/* hash function definition */
+typedef struct {
+    Py_hash_t (*const hash)(const void *, Py_ssize_t);
+    const char *name;
+    const int hash_bits;
+    const int seed_bits;
+} PyHash_FuncDef;
+
+PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);
+
+PyAPI_FUNC(Py_hash_t) Py_HashPointer(const void *ptr);