From b76dd69478f1116ea02474f695fe7fd53537a7a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johannes=20M=C3=BCller?= <straightshoota@gmail.com>
Date: Tue, 24 Sep 2024 13:09:33 +0200
Subject: [PATCH] Add documentation about synchronous DNS resolution

---
 src/socket/addrinfo.cr | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/socket/addrinfo.cr b/src/socket/addrinfo.cr
index ef76d0e285b6..411c09143411 100644
--- a/src/socket/addrinfo.cr
+++ b/src/socket/addrinfo.cr
@@ -4,6 +4,19 @@ require "crystal/system/addrinfo"
 
 class Socket
   # Domain name resolver.
+  #
+  # # Query Concurrency Behaviour
+  #
+  # On most platforms, DNS queries are currently resolved synchronously.
+  # Calling a resolve method blocks the entire thread until it returns.
+  # This can cause latencies, especially in single-threaded processes.
+  #
+  # DNS queries resolve asynchronously on the following platforms:
+  #
+  # * Windows 8 and higher
+  #
+  # NOTE: Follow the discussion in [Async DNS resolution (#13619)](https://github.com/crystal-lang/crystal/issues/13619)
+  # for more details.
   struct Addrinfo
     include Crystal::System::Addrinfo