# <!-- rdoc-file=ext/socket/tcpsocket.c -->
# TCPSocket represents a TCP/IP client socket.
#
# A simple client may look like:
#
#     require 'socket'
#
#     s = TCPSocket.new 'localhost', 2000
#
#     while line = s.gets # Read lines from socket
#       puts line         # and print them
#     end
#
#     s.close             # close socket when done
#
class TCPSocket < IPSocket
  # <!--
  #   rdoc-file=ext/socket/tcpsocket.c
  #   - TCPSocket.gethostbyname(hostname) => [official_hostname, alias_hostnames, address_family, *address_list]
  # -->
  # Use Addrinfo.getaddrinfo instead. This method is deprecated for the following
  # reasons:
  #
  # *   The 3rd element of the result is the address family of the first address.
  #     The address families of the rest of the addresses are not returned.
  # *   gethostbyname() may take a long time and it may block other threads. (GVL
  #     cannot be released since gethostbyname() is not thread safe.)
  # *   This method uses gethostbyname() function already removed from POSIX.
  #
  # This method lookups host information by *hostname*.
  #
  #     TCPSocket.gethostbyname("localhost")
  #     #=> ["localhost", ["hal"], 2, "127.0.0.1"]
  #
  def self.gethostbyname: (String host) -> [ String, Array[String], Integer, String ]

  private

  # <!--
  #   rdoc-file=ext/socket/tcpsocket.c
  #   - TCPSocket.new(remote_host, remote_port, local_host=nil, local_port=nil, resolv_timeout: nil, connect_timeout: nil, fast_fallback: true)
  # -->
  # Opens a TCP connection to `remote_host` on `remote_port`.  If `local_host` and
  # `local_port` are specified, then those parameters are used on the local end to
  # establish the connection.
  #
  # Starting from Ruby 3.4, this method operates according to the Happy Eyeballs
  # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305))
  # algorithm by default, except on Windows.
  #
  # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the
  # option `fast_fallback:false`.
  #
  # Happy Eyeballs Version 2 is not provided on Windows, and it behaves the same
  # as in Ruby 3.3 and earlier.
  #
  # :resolv_timeout
  # :   Specifies the timeout in seconds from when the hostname resolution starts.
  #
  # :connect_timeout
  # :   This method sequentially attempts connecting to all candidate destination
  #     addresses.
  #     The `connect_timeout` specifies the timeout in seconds from the start of
  #     the connection attempt to the last candidate.
  #     By default, all connection attempts continue until the timeout occurs.
  #     When `fast_fallback:false` is explicitly specified,
  #     a timeout is set for each connection attempt and any connection attempt
  #     that exceeds its timeout will be canceled.
  #
  # :fast_fallback
  # :   Enables the Happy Eyeballs Version 2 algorithm (enabled by default).
  #
  #
  # ### Happy Eyeballs Version 2
  # Happy Eyeballs Version 2 ([RFC
  # 8305](https://datatracker.ietf.org/doc/html/rfc8305)) is an algorithm designed
  # to improve client socket connectivity.
  #  It aims for more reliable and efficient connections by performing hostname
  # resolution and connection attempts in parallel, instead of serially.
  #
  # Starting from Ruby 3.4, this method operates as follows with this algorithm
  # except on Windows:
  #
  # 1.  Start resolving both IPv6 and IPv4 addresses concurrently.
  # 2.  Start connecting to the one of the addresses that are obtained first.
  #     If IPv4 addresses are obtained first, the method waits 50 ms for IPv6 name
  #     resolution to prioritize IPv6 connections.
  # 3.  After starting a connection attempt, wait 250 ms for the connection to be
  #     established.
  #      If no connection is established within this time, a new connection is
  #     started every 250 ms
  #      until a connection is  established or there are no more candidate
  #     addresses.
  #      (Although RFC 8305 strictly specifies sorting addresses,
  #      this method only alternates between IPv6 / IPv4 addresses due to the
  #     performance concerns)
  # 4.  Once a connection is established, all remaining connection attempts are
  #     canceled.
  #
  def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port) -> untyped
end