rbs 1.2.1 → 1.3.0

data/stdlib/socket/0/tcp_server.rbs

@@ -0,0 +1,177 @@
+# TCPServer represents a TCP/IP server socket.
+#
+# A simple TCP server may look like:
+#
+#     require 'socket'
+#
+#     server = TCPServer.new 2000 # Server bind to port 2000
+#     loop do
+#       client = server.accept    # Wait for a client to connect
+#       client.puts "Hello !"
+#       client.puts "Time is #{Time.now}"
+#       client.close
+#     end
+#
+# A more usable server (serving multiple clients):
+#
+#     require 'socket'
+#
+#     server = TCPServer.new 2000
+#     loop do
+#       Thread.start(server.accept) do |client|
+#         client.puts "Hello !"
+#         client.puts "Time is #{Time.now}"
+#         client.close
+#       end
+#     end
+class TCPServer < TCPSocket
+  public
+
+  # Accepts an incoming connection. It returns a new TCPSocket object.
+  #
+  #     TCPServer.open("127.0.0.1", 14641) {|serv|
+  #       s = serv.accept
+  #       s.puts Time.now
+  #       s.close
+  #     }
+  #
+  def accept: () -> TCPSocket
+
+  # Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the
+  # underlying file descriptor. It returns an accepted TCPSocket for the incoming
+  # connection.
+  #
+  # ### Example
+  #     require 'socket'
+  #     serv = TCPServer.new(2202)
+  #     begin # emulate blocking accept
+  #       sock = serv.accept_nonblock
+  #     rescue IO::WaitReadable, Errno::EINTR
+  #       IO.select([serv])
+  #       retry
+  #     end
+  #     # sock is an accepted socket.
+  #
+  # Refer to Socket#accept for the exceptions that may be thrown if the call to
+  # TCPServer#accept_nonblock fails.
+  #
+  # TCPServer#accept_nonblock may raise any error corresponding to accept(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK, Errno::EAGAIN, Errno::ECONNABORTED,
+  # Errno::EPROTO, it is extended by IO::WaitReadable. So IO::WaitReadable can be
+  # used to rescue the exceptions for retrying accept_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # accept_nonblock should not raise an IO::WaitReadable exception, but return the
+  # symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   TCPServer#accept
+  # *   Socket#accept
+  #
+  #
+  def accept_nonblock: (?exception: boolish) -> (TCPSocket | :wait_readable)
+
+  # Listens for connections, using the specified `int` as the backlog. A call to
+  # *listen* only applies if the `socket` is of type SOCK_STREAM or
+  # SOCK_SEQPACKET.
+  #
+  # ### Parameter
+  # *   `backlog` - the maximum length of the queue for pending connections.
+  #
+  #
+  # ### Example 1
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
+  #     socket.bind( sockaddr )
+  #     socket.listen( 5 )
+  #
+  # ### Example 2 (listening on an arbitrary port, unix-based systems only):
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     socket.listen( 1 )
+  #
+  # ### Unix-based Exceptions
+  # On unix based systems the above will work because a new `sockaddr` struct is
+  # created on the address ADDR_ANY, for an arbitrary port number as handed off by
+  # the kernel. It will not work on Windows, because Windows requires that the
+  # `socket` is bound by calling *bind* before it can *listen*.
+  #
+  # If the *backlog* amount exceeds the implementation-dependent maximum queue
+  # length, the implementation's maximum queue length will be used.
+  #
+  # On unix-based based systems the following system exceptions may be raised if
+  # the call to *listen* fails:
+  # *   Errno::EBADF - the *socket* argument is not a valid file descriptor
+  # *   Errno::EDESTADDRREQ - the *socket* is not bound to a local address, and
+  #     the protocol does not support listening on an unbound socket
+  # *   Errno::EINVAL - the *socket* is already connected
+  # *   Errno::ENOTSOCK - the *socket* argument does not refer to a socket
+  # *   Errno::EOPNOTSUPP - the *socket* protocol does not support listen
+  # *   Errno::EACCES - the calling process does not have appropriate privileges
+  # *   Errno::EINVAL - the *socket* has been shut down
+  # *   Errno::ENOBUFS - insufficient resources are available in the system to
+  #     complete the call
+  #
+  #
+  # ### Windows Exceptions
+  # On Windows systems the following system exceptions may be raised if the call
+  # to *listen* fails:
+  # *   Errno::ENETDOWN - the network is down
+  # *   Errno::EADDRINUSE - the socket's local address is already in use. This
+  #     usually occurs during the execution of *bind* but could be delayed if the
+  #     call to *bind* was to a partially wildcard address (involving ADDR_ANY)
+  #     and if a specific address needs to be committed at the time of the call to
+  #     *listen*
+  # *   Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
+  #     service provider is still processing a callback function
+  # *   Errno::EINVAL - the `socket` has not been bound with a call to *bind*.
+  # *   Errno::EISCONN - the `socket` is already connected
+  # *   Errno::EMFILE - no more socket descriptors are available
+  # *   Errno::ENOBUFS - no buffer space is available
+  # *   Errno::ENOTSOC - `socket` is not a socket
+  # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
+  #     the *listen* method
+  #
+  #
+  # ### See
+  # *   listen manual pages on unix-based systems
+  # *   listen function in Microsoft's Winsock functions reference
+  #
+  #
+  def listen: (Integer backlog) -> void
+
+  # Returns a file descriptor of a accepted connection.
+  #
+  #     TCPServer.open("127.0.0.1", 28561) {|serv|
+  #       fd = serv.sysaccept
+  #       s = IO.for_fd(fd)
+  #       s.puts Time.now
+  #       s.close
+  #     }
+  #
+  def sysaccept: () -> Integer
+
+  private
+
+  def __accept_nonblock: (untyped) -> untyped
+
+  # Creates a new server socket bound to *port*.
+  #
+  # If *hostname* is given, the socket is bound to it.
+  #
+  #     serv = TCPServer.new("127.0.0.1", 28561)
+  #     s = serv.accept
+  #     s.puts Time.now
+  #     s.close
+  #
+  # Internally, TCPServer.new calls getaddrinfo() function to obtain addresses. If
+  # getaddrinfo() returns multiple addresses, TCPServer.new tries to create a
+  # server socket for each address and returns first one that is successful.
+  #
+  def initialize: (?String host, Integer port) -> untyped
+end

data/stdlib/socket/0/tcp_socket.rbs

@@ -0,0 +1,35 @@
+# 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
+  # 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
+
+  def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port) -> untyped
+end

data/stdlib/socket/0/udp_socket.rbs

@@ -0,0 +1,111 @@
+# UDPSocket represents a UDP/IP socket.
+class UDPSocket < IPSocket
+  public
+
+  # Binds *udpsocket* to *host*:*port*.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #     u1.send "message-to-self", 0, "127.0.0.1", 4913
+  #     p u1.recvfrom(10) #=> ["message-to", ["AF_INET", 4913, "localhost", "127.0.0.1"]]
+  #
+  def bind: (String host, Integer port) -> void
+
+  # Connects *udpsocket* to *host*:*port*.
+  #
+  # This makes possible to send without destination address.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #     u2 = UDPSocket.new
+  #     u2.connect("127.0.0.1", 4913)
+  #     u2.send "uuuu", 0
+  #     p u1.recvfrom(10) #=> ["uuuu", ["AF_INET", 33230, "localhost", "127.0.0.1"]]
+  #
+  def connect: (String host, Integer port) -> void
+
+  # Receives up to *maxlen* bytes from `udpsocket` using recvfrom(2) after
+  # O_NONBLOCK is set for the underlying file descriptor. *flags* is zero or more
+  # of the `MSG_` options. The first element of the results, *mesg*, is the data
+  # received. The second element, *sender_inet_addr*, is an array to represent the
+  # sender address.
+  #
+  # When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns an empty string
+  # as data. It means an empty packet.
+  #
+  # ### Parameters
+  # *   `maxlen` - the number of bytes to receive from the socket
+  # *   `flags` - zero or more of the `MSG_` options
+  # *   `outbuf` - destination String buffer
+  # *   `options` - keyword hash, supporting `exception: false`
+  #
+  #
+  # ### Example
+  #     require 'socket'
+  #     s1 = UDPSocket.new
+  #     s1.bind("127.0.0.1", 0)
+  #     s2 = UDPSocket.new
+  #     s2.bind("127.0.0.1", 0)
+  #     s2.connect(*s1.addr.values_at(3,1))
+  #     s1.connect(*s2.addr.values_at(3,1))
+  #     s1.send "aaa", 0
+  #     begin # emulate blocking recvfrom
+  #       p s2.recvfrom_nonblock(10)  #=> ["aaa", ["AF_INET", 33302, "localhost.localdomain", "127.0.0.1"]]
+  #     rescue IO::WaitReadable
+  #       IO.select([s2])
+  #       retry
+  #     end
+  #
+  # Refer to Socket#recvfrom for the exceptions that may be thrown if the call to
+  # *recvfrom_nonblock* fails.
+  #
+  # UDPSocket#recvfrom_nonblock may raise any error corresponding to recvfrom(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by
+  # IO::WaitReadable. So IO::WaitReadable can be used to rescue the exceptions for
+  # retrying recvfrom_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # recvfrom_nonblock should not raise an IO::WaitReadable exception, but return
+  # the symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   Socket#recvfrom
+  #
+  #
+  def recvfrom_nonblock: (Integer len, ?Integer flag, ?String outbuf, ?exception: boolish) -> [String, [String, Integer, String, String]]
+
+  # Sends *mesg* via *udpsocket*.
+  #
+  # *flags* should be a bitwise OR of Socket::MSG_* constants.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #
+  #     u2 = UDPSocket.new
+  #     u2.send "hi", 0, "127.0.0.1", 4913
+  #
+  #     mesg, addr = u1.recvfrom(10)
+  #     u1.send mesg, 0, addr[3], addr[1]
+  #
+  #     p u2.recv(100) #=> "hi"
+  #
+  def send: (String msg, ?Integer flags, ?String host, ?Integer port) -> Integer
+
+  private
+
+  def __recvfrom_nonblock: (untyped, untyped, untyped, untyped) -> untyped
+
+  # Creates a new UDPSocket object.
+  #
+  # *address_family* should be an integer, a string or a symbol: Socket::AF_INET,
+  # "AF_INET", :INET, etc.
+  #
+  #     require 'socket'
+  #
+  #     UDPSocket.new                   #=> #<UDPSocket:fd 3>
+  #     UDPSocket.new(Socket::AF_INET6) #=> #<UDPSocket:fd 4>
+  #
+  def initialize: (?Integer family) -> untyped
+end

data/stdlib/socket/0/unix_server.rbs

@@ -0,0 +1,154 @@
+# UNIXServer represents a UNIX domain stream server socket.
+class UNIXServer < UNIXSocket
+  public
+
+  # Accepts an incoming connection. It returns a new UNIXSocket object.
+  #
+  #     UNIXServer.open("/tmp/sock") {|serv|
+  #       UNIXSocket.open("/tmp/sock") {|c|
+  #         s = serv.accept
+  #         s.puts "hi"
+  #         s.close
+  #         p c.read #=> "hi\n"
+  #       }
+  #     }
+  #
+  def accept: () -> UNIXSocket
+
+  # Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the
+  # underlying file descriptor. It returns an accepted UNIXSocket for the incoming
+  # connection.
+  #
+  # ### Example
+  #     require 'socket'
+  #     serv = UNIXServer.new("/tmp/sock")
+  #     begin # emulate blocking accept
+  #       sock = serv.accept_nonblock
+  #     rescue IO::WaitReadable, Errno::EINTR
+  #       IO.select([serv])
+  #       retry
+  #     end
+  #     # sock is an accepted socket.
+  #
+  # Refer to Socket#accept for the exceptions that may be thrown if the call to
+  # UNIXServer#accept_nonblock fails.
+  #
+  # UNIXServer#accept_nonblock may raise any error corresponding to accept(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK, Errno::EAGAIN, Errno::ECONNABORTED or
+  # Errno::EPROTO, it is extended by IO::WaitReadable. So IO::WaitReadable can be
+  # used to rescue the exceptions for retrying accept_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # accept_nonblock should not raise an IO::WaitReadable exception, but return the
+  # symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   UNIXServer#accept
+  # *   Socket#accept
+  #
+  #
+  def accept_nonblock: (?exception: boolish) -> (UNIXSocket | :wait_readable)
+
+  # Listens for connections, using the specified `int` as the backlog. A call to
+  # *listen* only applies if the `socket` is of type SOCK_STREAM or
+  # SOCK_SEQPACKET.
+  #
+  # ### Parameter
+  # *   `backlog` - the maximum length of the queue for pending connections.
+  #
+  #
+  # ### Example 1
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
+  #     socket.bind( sockaddr )
+  #     socket.listen( 5 )
+  #
+  # ### Example 2 (listening on an arbitrary port, unix-based systems only):
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     socket.listen( 1 )
+  #
+  # ### Unix-based Exceptions
+  # On unix based systems the above will work because a new `sockaddr` struct is
+  # created on the address ADDR_ANY, for an arbitrary port number as handed off by
+  # the kernel. It will not work on Windows, because Windows requires that the
+  # `socket` is bound by calling *bind* before it can *listen*.
+  #
+  # If the *backlog* amount exceeds the implementation-dependent maximum queue
+  # length, the implementation's maximum queue length will be used.
+  #
+  # On unix-based based systems the following system exceptions may be raised if
+  # the call to *listen* fails:
+  # *   Errno::EBADF - the *socket* argument is not a valid file descriptor
+  # *   Errno::EDESTADDRREQ - the *socket* is not bound to a local address, and
+  #     the protocol does not support listening on an unbound socket
+  # *   Errno::EINVAL - the *socket* is already connected
+  # *   Errno::ENOTSOCK - the *socket* argument does not refer to a socket
+  # *   Errno::EOPNOTSUPP - the *socket* protocol does not support listen
+  # *   Errno::EACCES - the calling process does not have appropriate privileges
+  # *   Errno::EINVAL - the *socket* has been shut down
+  # *   Errno::ENOBUFS - insufficient resources are available in the system to
+  #     complete the call
+  #
+  #
+  # ### Windows Exceptions
+  # On Windows systems the following system exceptions may be raised if the call
+  # to *listen* fails:
+  # *   Errno::ENETDOWN - the network is down
+  # *   Errno::EADDRINUSE - the socket's local address is already in use. This
+  #     usually occurs during the execution of *bind* but could be delayed if the
+  #     call to *bind* was to a partially wildcard address (involving ADDR_ANY)
+  #     and if a specific address needs to be committed at the time of the call to
+  #     *listen*
+  # *   Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
+  #     service provider is still processing a callback function
+  # *   Errno::EINVAL - the `socket` has not been bound with a call to *bind*.
+  # *   Errno::EISCONN - the `socket` is already connected
+  # *   Errno::EMFILE - no more socket descriptors are available
+  # *   Errno::ENOBUFS - no buffer space is available
+  # *   Errno::ENOTSOC - `socket` is not a socket
+  # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
+  #     the *listen* method
+  #
+  #
+  # ### See
+  # *   listen manual pages on unix-based systems
+  # *   listen function in Microsoft's Winsock functions reference
+  #
+  #
+  def listen: (Integer backlog) -> void
+
+  # Accepts a new connection. It returns the new file descriptor which is an
+  # integer.
+  #
+  #     UNIXServer.open("/tmp/sock") {|serv|
+  #       UNIXSocket.open("/tmp/sock") {|c|
+  #         fd = serv.sysaccept
+  #         s = IO.new(fd)
+  #         s.puts "hi"
+  #         s.close
+  #         p c.read #=> "hi\n"
+  #       }
+  #     }
+  #
+  def sysaccept: () -> Integer
+
+  private
+
+  def __accept_nonblock: (untyped) -> untyped
+
+  # Creates a new UNIX server socket bound to *path*.
+  #
+  #     require 'socket'
+  #
+  #     serv = UNIXServer.new("/tmp/sock")
+  #     s = serv.accept
+  #     p s.read
+  #
+  def initialize: (untyped) -> untyped
+end