# 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:

    # 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 `float` type, timer file descriptors allow specifying initial expiration and interval in integer nanoseconds with `_ns` variants of the functions.

This example shows how `epoll()` can be used with timer file descriptors to wait until the file descriptor is ready for reading:

    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 number 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 `select()` can be used with timer file descriptors to wait until the file descriptor is ready for reading:

    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