Fix shutdown race

Author: bdraco

docs/channel.rst

@@ -66,6 +66,36 @@
 
     The c-ares ``Channel`` provides asynchronous DNS operations.
 
+    The Channel object is designed to handle an unlimited number of DNS queries efficiently.
+    Creating and destroying resolver instances repeatedly is resource-intensive and not
+    recommended. Instead, create a single resolver instance and reuse it throughout your
+    application's lifetime.
+
+    .. important::
+        It is recommended to explicitly close channels when done for predictable resource
+        cleanup. Use :py:meth:`close` which can be called from any thread.
+        While channels will attempt automatic cleanup during garbage collection, explicit
+        closing is safer as it gives you control over when resources are released.
+
+    .. warning::
+        The channel destruction mechanism has a limited throughput of 60 channels per minute
+        (one channel per second) to ensure thread safety and prevent use-after-free errors
+        in c-ares. This means:
+
+        - Avoid creating transient channels for individual queries
+        - Reuse channel instances whenever possible
+        - For applications with high query volume, use a single long-lived channel
+        - If you must create multiple channels, consider pooling them
+
+        Creating and destroying channels rapidly will result in a backlog as the destruction
+        queue processes channels sequentially with a 1-second delay between each.
+
+    The Channel class supports the context manager protocol for automatic cleanup::
+
+        with pycares.Channel() as channel:
+            channel.query('example.com', pycares.QUERY_TYPE_A, callback)
+        # Channel is automatically closed when exiting the context
+
     .. py:method:: getaddrinfo(host, port, callback, family=0, type=0, proto=0, flags=0)
 
         :param string host: Hostname to resolve.
@@ -243,8 +273,33 @@
 
         Cancel any pending query on this channel. All pending callbacks will be called with ARES_ECANCELLED errorno.
 
+    .. py:method:: close()
+
+        Close the channel as soon as it's safe to do so.
+
+        This method can be called from any thread. The channel will be destroyed
+        safely using a background thread with a 1-second delay to ensure c-ares
+        has completed its cleanup.
+
+        Once close() is called, no new queries can be started. Any pending
+        queries will be cancelled and their callbacks will receive ARES_ECANCELLED.
+
+        .. note::
+            It is recommended to explicitly call :py:meth:`close` rather than
+            relying on garbage collection. Explicit closing provides:
+
+            - Control over when resources are released
+            - Predictable shutdown timing
+            - Proper cleanup of all resources
+
+            While the channel will attempt cleanup during garbage collection,
+            explicit closing is safer and more predictable.
+
+        .. versionadded:: 4.9.0
+
+
     .. py:method:: reinit()
-            
+
         Reinitialize the channel.
 
         For more details, see the `ares_reinit documentation <https://c-ares.org/docs/ares_reinit.html>`_.
@@ -284,4 +339,3 @@
     .. py:attribute:: servers
 
         List of nameservers to use for DNS queries.
-

examples/cares-asyncio-event-thread.py

@@ -0,0 +1,87 @@
+import asyncio
+import socket
+from typing import Any, Callable, Optional
+
+import pycares
+
+
+class DNSResolver:
+    def __init__(self, loop: Optional[asyncio.AbstractEventLoop] = None) -> None:
+        # Use event_thread=True for automatic event handling in a separate thread
+        self._channel = pycares.Channel(event_thread=True)
+        self.loop = loop or asyncio.get_running_loop()
+
+    def query(
+        self, name: str, query_type: int, cb: Callable[[Any, Optional[int]], None]
+    ) -> None:
+        self._channel.query(name, query_type, cb)
+
+    def gethostbyname(
+        self, name: str, cb: Callable[[Any, Optional[int]], None]
+    ) -> None:
+        self._channel.gethostbyname(name, socket.AF_INET, cb)
+
+    def close(self) -> None:
+        """Thread-safe shutdown of the channel."""
+        # Simply call close() - it's thread-safe and handles everything
+        self._channel.close()
+
+
+async def main() -> None:
+    # Track queries
+    query_count = 0
+    completed_count = 0
+    cancelled_count = 0
+
+    def cb(query_name: str) -> Callable[[Any, Optional[int]], None]:
+        def _cb(result: Any, error: Optional[int]) -> None:
+            nonlocal completed_count, cancelled_count
+            if error == pycares.errno.ARES_ECANCELLED:
+                cancelled_count += 1
+                print(f"Query for {query_name} was CANCELLED")
+            else:
+                completed_count += 1
+                print(
+                    f"Query for {query_name} completed - Result: {result}, Error: {error}"
+                )
+
+        return _cb
+
+    loop = asyncio.get_running_loop()
+    resolver = DNSResolver(loop)
+
+    print("=== Starting first batch of queries ===")
+    # First batch - these should complete
+    resolver.query("google.com", pycares.QUERY_TYPE_A, cb("google.com"))
+    resolver.query("cloudflare.com", pycares.QUERY_TYPE_A, cb("cloudflare.com"))
+    query_count += 2
+
+    # Give them a moment to complete
+    await asyncio.sleep(0.5)
+
+    print("\n=== Starting second batch of queries (will be cancelled) ===")
+    # Second batch - these will be cancelled
+    resolver.query("github.com", pycares.QUERY_TYPE_A, cb("github.com"))
+    resolver.query("stackoverflow.com", pycares.QUERY_TYPE_A, cb("stackoverflow.com"))
+    resolver.gethostbyname("python.org", cb("python.org"))
+    query_count += 3
+
+    # Immediately close - this will cancel pending queries
+    print("\n=== Closing resolver (cancelling pending queries) ===")
+    resolver.close()
+    print("Resolver closed successfully")
+
+    print(f"\n=== Summary ===")
+    print(f"Total queries: {query_count}")
+    print(f"Completed: {completed_count}")
+    print(f"Cancelled: {cancelled_count}")
+
+
+if __name__ == "__main__":
+    # Check if c-ares supports threads
+    if pycares.ares_threadsafety():
+        # For Python 3.7+
+        asyncio.run(main())
+    else:
+        print("c-ares was not compiled with thread support")
+        print("Please see examples/cares-asyncio.py for sock_state_cb usage")

examples/cares-asyncio.py

@@ -52,18 +52,38 @@ def query(self, query_type, name, cb):
     def gethostbyname(self, name, cb):
         self._channel.gethostbyname(name, socket.AF_INET, cb)
 
+    def close(self):
+        """Close the resolver and cleanup resources."""
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+        for fd in self._fds:
+            self.loop.remove_reader(fd)
+            self.loop.remove_writer(fd)
+        self._fds.clear()
+        # Note: The channel will be destroyed safely in a background thread
+        # with a 1-second delay to ensure c-ares has completed its cleanup.
+        self._channel.close()
 
-def main():
+
+async def main():
     def cb(result, error):
         print("Result: {}, Error: {}".format(result, error))
-    loop = asyncio.get_event_loop()
+
+    loop = asyncio.get_running_loop()
     resolver = DNSResolver(loop)
-    resolver.query('google.com', pycares.QUERY_TYPE_A, cb)
-    resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, cb)
-    resolver.gethostbyname('apple.com', cb)
-    loop.run_forever()
+
+    try:
+        resolver.query('google.com', pycares.QUERY_TYPE_A, cb)
+        resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, cb)
+        resolver.gethostbyname('apple.com', cb)
+
+        # Give some time for queries to complete
+        await asyncio.sleep(2)
+    finally:
+        resolver.close()
 
 
 if __name__ == '__main__':
-    main()
+    asyncio.run(main())
 

examples/cares-context-manager.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+"""
+Example of using pycares Channel as a context manager with event_thread=True.
+
+This demonstrates the simplest way to use pycares with automatic cleanup.
+The event thread handles all socket operations internally, and the context
+manager ensures the channel is properly closed when done.
+"""
+
+import pycares
+import socket
+import time
+
+
+def main():
+    """Run DNS queries using Channel as a context manager."""
+    results = []
+
+    def callback(result, error):
+        """Store results from DNS queries."""
+        if error:
+            print(f"Error {error}: {pycares.errno.strerror(error)}")
+        else:
+            print(f"Result: {result}")
+        results.append((result, error))
+
+    # Use Channel as a context manager with event_thread=True
+    # This is the recommended pattern for simple use cases
+    with pycares.Channel(
+        servers=["8.8.8.8", "8.8.4.4"], timeout=5.0, tries=3, event_thread=True
+    ) as channel:
+        print("=== Making DNS queries ===")
+
+        # Query for A records
+        channel.query("google.com", pycares.QUERY_TYPE_A, callback)
+        channel.query("cloudflare.com", pycares.QUERY_TYPE_A, callback)
+
+        # Query for AAAA records
+        channel.query("google.com", pycares.QUERY_TYPE_AAAA, callback)
+
+        # Query for MX records
+        channel.query("python.org", pycares.QUERY_TYPE_MX, callback)
+
+        # Query for TXT records
+        channel.query("google.com", pycares.QUERY_TYPE_TXT, callback)
+
+        # Query using gethostbyname
+        channel.gethostbyname("github.com", socket.AF_INET, callback)
+
+        # Query using gethostbyaddr
+        channel.gethostbyaddr("8.8.8.8", callback)
+
+        print("\nWaiting for queries to complete...")
+        # Give queries time to complete
+        # In a real application, you would coordinate with your event loop
+        time.sleep(2)
+
+    # Channel is automatically closed when exiting the context
+    print("\n=== Channel closed automatically ===")
+
+    print(f"\nCompleted {len(results)} queries")
+
+    # Demonstrate that the channel is closed and can't be used
+    try:
+        channel.query("example.com", pycares.QUERY_TYPE_A, callback)
+    except RuntimeError as e:
+        print(f"\nExpected error when using closed channel: {e}")
+
+
+if __name__ == "__main__":
+    # Check if c-ares supports threads
+    if pycares.ares_threadsafety():
+        print(f"Using pycares {pycares.__version__} with c-ares {pycares.ARES_VERSION}")
+        print(
+            f"Thread safety: {'enabled' if pycares.ares_threadsafety() else 'disabled'}\n"
+        )
+        main()
+    else:
+        print("This example requires c-ares to be compiled with thread support")
+        print("Use cares-select.py or cares-asyncio.py instead")

examples/cares-poll.py

@@ -48,6 +48,13 @@ def query(self, query_type, name, cb):
     def gethostbyname(self, name, cb):
         self._channel.gethostbyname(name, socket.AF_INET, cb)
 
+    def close(self):
+        """Close the resolver and cleanup resources."""
+        for fd in list(self._fd_map):
+            self.poll.unregister(fd)
+        self._fd_map.clear()
+        self._channel.close()
+
 
 if __name__ == '__main__':
     def query_cb(result, error):
@@ -57,8 +64,11 @@ def gethostbyname_cb(result, error):
         print(result)
         print(error)
     resolver = DNSResolver()
-    resolver.query('google.com', pycares.QUERY_TYPE_A, query_cb)
-    resolver.query('facebook.com', pycares.QUERY_TYPE_A, query_cb)
-    resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, query_cb)
-    resolver.gethostbyname('apple.com', gethostbyname_cb)
-    resolver.wait_channel()
+    try:
+        resolver.query('google.com', pycares.QUERY_TYPE_A, query_cb)
+        resolver.query('facebook.com', pycares.QUERY_TYPE_A, query_cb)
+        resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, query_cb)
+        resolver.gethostbyname('apple.com', gethostbyname_cb)
+        resolver.wait_channel()
+    finally:
+        resolver.close()

examples/cares-resolver.py

@@ -52,6 +52,14 @@ def query(self, query_type, name, cb):
     def gethostbyname(self, name, cb):
         self._channel.gethostbyname(name, socket.AF_INET, cb)
 
+    def close(self):
+        """Close the resolver and cleanup resources."""
+        self._timer.stop()
+        for handle in self._fd_map.values():
+            handle.close()
+        self._fd_map.clear()
+        self._channel.close()
+
 
 if __name__ == '__main__':
     def query_cb(result, error):
@@ -62,8 +70,11 @@ def gethostbyname_cb(result, error):
         print(error)
     loop = pyuv.Loop.default_loop()
     resolver = DNSResolver(loop)
-    resolver.query('google.com', pycares.QUERY_TYPE_A, query_cb)
-    resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, query_cb)
-    resolver.gethostbyname('apple.com', gethostbyname_cb)
-    loop.run()
+    try:
+        resolver.query('google.com', pycares.QUERY_TYPE_A, query_cb)
+        resolver.query('sip2sip.info', pycares.QUERY_TYPE_SOA, query_cb)
+        resolver.gethostbyname('apple.com', gethostbyname_cb)
+        loop.run()
+    finally:
+        resolver.close()
 

examples/cares-select.py

@@ -25,9 +25,12 @@ def cb(result, error):
         print(result)
         print(error)
     channel = pycares.Channel()
-    channel.gethostbyname('google.com', socket.AF_INET, cb)
-    channel.query('google.com', pycares.QUERY_TYPE_A, cb)
-    channel.query('sip2sip.info', pycares.QUERY_TYPE_SOA, cb)
-    wait_channel(channel)
+    try:
+        channel.gethostbyname('google.com', socket.AF_INET, cb)
+        channel.query('google.com', pycares.QUERY_TYPE_A, cb)
+        channel.query('sip2sip.info', pycares.QUERY_TYPE_SOA, cb)
+        wait_channel(channel)
+    finally:
+        channel.close()
     print('Done!')