# <!-- 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, open_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.
  #
  # For details on Happy Eyeballs Version 2, see
  # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=).
  #
  # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the
  # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will
  # disable Happy Eyeballs Version 2 not only for this method but for all Socket
  # globally.
  #
  # When using TCPSocket.new on Windows, Happy Eyeballs Version 2 is not provided,
  # 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.
  #
  # :open_timeout
  # :   Specifies the timeout in seconds from the start of the method execution.
  #     If this timeout is reached while there are still addresses that have not
  #     yet been attempted for connection, no further attempts will be made.
  #     If this option is specified together with other timeout options, an
  #     `ArgumentError` will be raised.
  #
  # :fast_fallback
  # :   Enables the Happy Eyeballs Version 2 algorithm (enabled by default).
  #
  def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port, ?fast_fallback: boolish, ?resolv_timeout: Integer, ?connect_timeout: Integer) -> void
                | (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port, ?fast_fallback: boolish, ?open_timeout: Integer) -> void
end
