ruby-changes:20930
From: drbrain <ko1@a...>
Date: Tue, 16 Aug 2011 08:22:54 +0900 (JST)
Subject: [ruby-changes:20930] drbrain:r32979 (ruby_1_9_3): * backport r32977 from trunk
drbrain 2011-08-16 08:20:44 +0900 (Tue, 16 Aug 2011) New Revision: 32979 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=32979 Log: * backport r32977 from trunk * ext/socket: Make Socket documentation appear. Add documentation for Socket, TCPServer, SOCKSSocket. Patch by Sylvain Daubert. [Ruby 1.9 - Feature #5182] Modified files: branches/ruby_1_9_3/ChangeLog branches/ruby_1_9_3/ext/socket/ancdata.c branches/ruby_1_9_3/ext/socket/basicsocket.c branches/ruby_1_9_3/ext/socket/init.c branches/ruby_1_9_3/ext/socket/ipsocket.c branches/ruby_1_9_3/ext/socket/lib/socket.rb branches/ruby_1_9_3/ext/socket/mkconstants.rb branches/ruby_1_9_3/ext/socket/option.c branches/ruby_1_9_3/ext/socket/raddrinfo.c branches/ruby_1_9_3/ext/socket/socket.c branches/ruby_1_9_3/ext/socket/sockssocket.c branches/ruby_1_9_3/ext/socket/tcpserver.c branches/ruby_1_9_3/ext/socket/tcpsocket.c branches/ruby_1_9_3/ext/socket/udpsocket.c branches/ruby_1_9_3/ext/socket/unixserver.c branches/ruby_1_9_3/ext/socket/unixsocket.c Index: ruby_1_9_3/ChangeLog =================================================================== --- ruby_1_9_3/ChangeLog (revision 32978) +++ ruby_1_9_3/ChangeLog (revision 32979) @@ -1,3 +1,11 @@ +Tue Aug 16 08:00:15 2011 Eric Hodel <drbrain@s...> + + * backport r32977 from trunk + + * ext/socket: Make Socket documentation appear. Add documentation for + Socket, TCPServer, SOCKSSocket. Patch by Sylvain Daubert. + [Ruby 1.9 - Feature #5182] + Mon Aug 15 10:16:55 2011 Martin Bosslet <Martin.Bosslet@g...> * backport r32973 from trunk. Index: ruby_1_9_3/ext/socket/tcpsocket.c =================================================================== --- ruby_1_9_3/ext/socket/tcpsocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/tcpsocket.c (revision 32979) @@ -55,14 +55,27 @@ tcp_sockaddr); } -/* - * Document-class: ::TCPSocket < IPSocket - * - * TCPSocket represents a TCP/IP client socket. - */ void rsock_init_tcpsocket(void) { + /* + * Document-class: TCPSocket < IPSocket + * + * 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 + * + */ rb_cTCPSocket = rb_define_class("TCPSocket", rb_cIPSocket); rb_define_singleton_method(rb_cTCPSocket, "gethostbyname", tcp_s_gethostbyname, 1); rb_define_method(rb_cTCPSocket, "initialize", tcp_init, -1); Index: ruby_1_9_3/ext/socket/udpsocket.c =================================================================== --- ruby_1_9_3/ext/socket/udpsocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/udpsocket.c (revision 32979) @@ -246,14 +246,15 @@ return rsock_s_recvfrom_nonblock(sock, argc, argv, RECV_IP); } -/* - * Document-class: ::UDPSocket < IPSocket - * - * UDPSocket represents a UDP/IP socket. - */ void rsock_init_udpsocket(void) { + /* + * Document-class: UDPSocket < IPSocket + * + * UDPSocket represents a UDP/IP socket. + * + */ rb_cUDPSocket = rb_define_class("UDPSocket", rb_cIPSocket); rb_define_method(rb_cUDPSocket, "initialize", udp_init, -1); rb_define_method(rb_cUDPSocket, "connect", udp_connect, 2); Index: ruby_1_9_3/ext/socket/init.c =================================================================== --- ruby_1_9_3/ext/socket/init.c (revision 32978) +++ ruby_1_9_3/ext/socket/init.c (revision 32979) @@ -531,12 +531,12 @@ return ss.ss_family; } -/* - * SocketError is the error class for socket. - */ void rsock_init_socket_init() { + /* + * SocketError is the error class for socket. + */ rb_eSocket = rb_define_class("SocketError", rb_eStandardError); rsock_init_ipsocket(); rsock_init_tcpsocket(); Index: ruby_1_9_3/ext/socket/option.c =================================================================== --- ruby_1_9_3/ext/socket/option.c (revision 32978) +++ ruby_1_9_3/ext/socket/option.c (revision 32979) @@ -888,16 +888,17 @@ return rb_funcall(sockopt_data(self), rb_intern("unpack"), 1, template); } -/* - * Document-class: ::Socket::Option - * - * Socket::Option represents a socket option used by getsockopt and setsockopt - * system call. - * It contains socket family, protocol level, option name and option value. - */ void rsock_init_sockopt(void) { + /* + * Document-class: Socket::Option + * + * Socket::Option represents a socket option used by + * BasicSocket#getsockopt and BasicSocket#setsockopt. A socket option + * contains the socket #family, protocol #level, option name #optname and + * option value #data. + */ rb_cSockOpt = rb_define_class_under(rb_cSocket, "Option", rb_cObject); rb_define_method(rb_cSockOpt, "initialize", sockopt_initialize, 4); rb_define_method(rb_cSockOpt, "family", sockopt_family_m, 0); Index: ruby_1_9_3/ext/socket/raddrinfo.c =================================================================== --- ruby_1_9_3/ext/socket/raddrinfo.c (revision 32978) +++ ruby_1_9_3/ext/socket/raddrinfo.c (revision 32979) @@ -2151,6 +2151,10 @@ void rsock_init_addrinfo(void) { + /* + * The Addrinfo class maps <tt>struct addrinfo</tt> to ruby. This + * structure identifies an Internet host and a service. + */ rb_cAddrinfo = rb_define_class("Addrinfo", rb_cData); rb_define_alloc_func(rb_cAddrinfo, addrinfo_s_allocate); rb_define_method(rb_cAddrinfo, "initialize", addrinfo_initialize, -1); Index: ruby_1_9_3/ext/socket/unixserver.c =================================================================== --- ruby_1_9_3/ext/socket/unixserver.c (revision 32978) +++ ruby_1_9_3/ext/socket/unixserver.c (revision 32979) @@ -135,15 +135,16 @@ #endif -/* - * Document-class: ::UNIXServer < UNIXSocket - * - * UNIXServer represents a UNIX domain stream server socket. - */ void rsock_init_unixserver(void) { #ifdef HAVE_SYS_UN_H + /* + * Document-class: UNIXServer < UNIXSocket + * + * UNIXServer represents a UNIX domain stream server socket. + * + */ rb_cUNIXServer = rb_define_class("UNIXServer", rb_cUNIXSocket); rb_define_method(rb_cUNIXServer, "initialize", unix_svr_init, 1); rb_define_method(rb_cUNIXServer, "accept", unix_accept, 0); Index: ruby_1_9_3/ext/socket/tcpserver.c =================================================================== --- ruby_1_9_3/ext/socket/tcpserver.c (revision 32978) +++ ruby_1_9_3/ext/socket/tcpserver.c (revision 32979) @@ -128,14 +128,40 @@ return rsock_s_accept(0, fptr->fd, (struct sockaddr*)&from, &fromlen); } -/* - * Document-class: ::TCPServer < TCPSocket - * - * TCPServer represents a TCP/IP server socket. - */ void rsock_init_tcpserver(void) { + /* + * Document-class: TCPServer < TCPSocket + * + * 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 + * + */ rb_cTCPServer = rb_define_class("TCPServer", rb_cTCPSocket); rb_define_method(rb_cTCPServer, "accept", tcp_accept, 0); rb_define_method(rb_cTCPServer, "accept_nonblock", tcp_accept_nonblock, 0); Index: ruby_1_9_3/ext/socket/ipsocket.c =================================================================== --- ruby_1_9_3/ext/socket/ipsocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/ipsocket.c (revision 32979) @@ -288,14 +288,14 @@ return rsock_make_ipaddr((struct sockaddr*)&addr); } -/* - * Document-class: ::IPSocket < BasicSocket - * - * IPSocket is the super class of TCPSocket and UDPSocket. - */ void rsock_init_ipsocket(void) { + /* + * Document-class: IPSocket < BasicSocket + * + * IPSocket is the super class of TCPSocket and UDPSocket. + */ rb_cIPSocket = rb_define_class("IPSocket", rb_cBasicSocket); rb_define_method(rb_cIPSocket, "addr", ip_addr, -1); rb_define_method(rb_cIPSocket, "peeraddr", ip_peeraddr, -1); Index: ruby_1_9_3/ext/socket/lib/socket.rb =================================================================== --- ruby_1_9_3/ext/socket/lib/socket.rb (revision 32978) +++ ruby_1_9_3/ext/socket/lib/socket.rb (revision 32979) @@ -643,17 +643,28 @@ # UDP/IP address information used by Socket.udp_server_loop. class UDPSource + # +remote_adress+ is an Addrinfo object. + # + # +local_adress+ is an Addrinfo object. + # + # +reply_proc+ is a Proc used to send reply back to the source. def initialize(remote_address, local_address, &reply_proc) @remote_address = remote_address @local_address = local_address @reply_proc = reply_proc end - attr_reader :remote_address, :local_address - def inspect + # Address of the source + attr_reader :remote_address + + # Local address + attr_reader :local_address + + def inspect # :nodoc: "\#<#{self.class}: #{@remote_address.inspect_sockaddr} to #{@local_address.inspect_sockaddr}>" end + # Sends the String +msg+ to the source def reply(msg) @reply_proc.call msg end Index: ruby_1_9_3/ext/socket/mkconstants.rb =================================================================== --- ruby_1_9_3/ext/socket/mkconstants.rb (revision 32978) +++ ruby_1_9_3/ext/socket/mkconstants.rb (revision 32979) @@ -284,18 +284,20 @@ <%= INTERN_DEFS.map {|vardef, gen_hash, decl, func| vardef }.join("\n") %> -/* - * Document-module: ::Socket::Constants - * - * Socket::Constants provides socket related constants. - * Following lists possible constants. - * If underlying platform doesn't define a constant, - * the corresponding Ruby constant is not defined. - * - */ static void init_constants(void) { + /* + * Document-module: Socket::Constants + * + * Socket::Constants provides socket-related constants. All possible + * socket constants are listed in the documentation but they may not all + * be present on your platform. + * + * If the underlying platform doesn't define a constant the corresponding + * Ruby constant is not defined. + * + */ rb_mSockConst = rb_define_module_under(rb_cSocket, "Constants"); <%= gen_const_defs %> Index: ruby_1_9_3/ext/socket/socket.c =================================================================== --- ruby_1_9_3/ext/socket/socket.c (revision 32978) +++ ruby_1_9_3/ext/socket/socket.c (revision 32979) @@ -1792,48 +1792,116 @@ #define socket_s_ip_address_list rb_f_notimplement #endif -/* - * Document-class: ::Socket < BasicSocket - * - * Class +Socket+ provides access to the underlying operating system - * socket implementations. It can be used to provide more operating system - * specific functionality than the protocol-specific socket classes. - * - * The constants defined under Socket::Constants are also defined under Socket. - * For example, Socket::AF_INET is usable as well as Socket::Constants::AF_INET. - * See Socket::Constants for the list of constants. - * - * === Exception Handling - * Ruby's implementation of +Socket+ causes an exception to be raised - * based on the error generated by the system dependent implementation. - * This is why the methods are documented in a way that isolate - * Unix-based system exceptions from Windows based exceptions. If more - * information on particular exception is needed please refer to the - * Unix manual pages or the Windows WinSock reference. - * - * === Convenient methods - * - * Although the general way to create socket is Socket.new, - * there are several methods for socket creation for most cases. - * - * * TCP client socket: Socket.tcp, TCPSocket.open - * * TCP server socket: Socket.tcp_server_loop, TCPServer.open - * * UNIX client socket: Socket.unix, UNIXSocket.open - * * UNIX server socket: Socket.unix_server_loop, UNIXServer.open - * - * === Documentation by - * * Zach Dennis - * * Sam Roberts - * * <em>Programming Ruby</em> from The Pragmatic Bookshelf. - * - * Much material in this documentation is taken with permission from - * <em>Programming Ruby</em> from The Pragmatic Bookshelf. - */ void Init_socket() { rsock_init_basicsocket(); + /* + * Document-class: Socket < BasicSocket + * + * Class +Socket+ provides access to the underlying operating system + * socket implementations. It can be used to provide more operating system + * specific functionality than the protocol-specific socket classes. + * + * The constants defined under Socket::Constants are also defined under + * Socket. For example, Socket::AF_INET is usable as well as + * Socket::Constants::AF_INET. See Socket::Constants for the list of + * constants. + * + * === What's a socket? + * + * Sockets are endpoints of a bidirectionnal communication channel. + * Sockets can communicate within a process, between processes on the same + * machine or between different machines. There are many types of socket: + * TCPSocket, UDPSocket or UNIXSocket for example. + * + * Sockets have their own vocabulary: + * domain:: + * The family of protocols: Socket::PF_INET, Socket::PF_INET6, + * Socket::PF_UNIX, etc. + * type:: + * The type of communications between the two endpoints, typically + * Socket::SOCK_STREAM or Socket::SOCK_DGRAM. + * protocol:: + * Typically zero. This may be used to identify a variant of a + * protocol. + * hostname:: + * The identifier of a network interface: + * * a string (hostname, IPv4 or IPv6 adress or <tt><broadcast></tt> + * which specifies a broadcast address) + * * a zero-length string which specifies INADDR_ANY + * * an integer (interpreted as binary address in host byte order). + * + * === Quick start + * + * Some classes such as TCPSocket, UDPSocket or UNIXSocket ease use of + * sockets of these types compared to C programming. + * + * # Creating a TCP socket in a C-like manner + * s = Socket.new Socket::INET, Socket::SOCK_STREAM + * s.connect Socket.pack_sockaddr_in(80, 'example.com') + * + * # Using TCPSocket + * s = TCPSocket.new 'example.com', 80 + * + * A simple server would look like: + * + * require 'socket' + * + * server = TCPServer.new 2000 # Server bound 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 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 + * + * === Exception Handling + * + * Ruby's Socket implementation raises exceptions based on the error + * generated by the system dependent implementation. This is why the + * methods are documented in a way that isolate Unix-based system + * exceptions from Windows based exceptions. If more information on + * particular exception is needed please refer to the Unix manual pages or + * the Windows WinSock reference. + * + * === Convenient methods + * + * Although the general way to create socket is Socket.new, + * there are several methods for socket creation for most cases. + * + * TCP client socket:: + * Socket.tcp, TCPSocket.open + * TCP server socket:: + * Socket.tcp_server_loop, TCPServer.open + * UNIX client socket:: + * Socket.unix, UNIXSocket.open + * UNIX server socket:: + * Socket.unix_server_loop, UNIXServer.open + * + * === Documentation by + * + * * Zach Dennis + * * Sam Roberts + * * <em>Programming Ruby</em> from The Pragmatic Bookshelf. + * + * Much material in this documentation is taken with permission from + * <em>Programming Ruby</em> from The Pragmatic Bookshelf. + */ rb_cSocket = rb_define_class("Socket", rb_cBasicSocket); rsock_init_socket_init(); Index: ruby_1_9_3/ext/socket/basicsocket.c =================================================================== --- ruby_1_9_3/ext/socket/basicsocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/basicsocket.c (revision 32979) @@ -732,12 +732,14 @@ return val; } -/* - * BasicSocket is the super class for the all socket classes. - */ void rsock_init_basicsocket(void) { + /* + * Document-class: BasicSocket < IO + * + * BasicSocket is the super class for all the Socket classes. + */ rb_cBasicSocket = rb_define_class("BasicSocket", rb_cIO); rb_undef_method(rb_cBasicSocket, "initialize"); Index: ruby_1_9_3/ext/socket/ancdata.c =================================================================== --- ruby_1_9_3/ext/socket/ancdata.c (revision 32978) +++ ruby_1_9_3/ext/socket/ancdata.c (revision 32979) @@ -1774,17 +1774,17 @@ } #endif -/* - * Document-class: ::Socket::AncillaryData - * - * Socket::AncillaryData represents the ancillary data (control information) - * used by sendmsg and recvmsg system call. - * It contains socket family, cmsg level, cmsg type and cmsg data. - */ void rsock_init_ancdata(void) { #if defined(HAVE_ST_MSG_CONTROL) + /* + * Document-class: Socket::AncillaryData + * + * Socket::AncillaryData represents the ancillary data (control information) + * used by sendmsg and recvmsg system call. It contains socket #family, + * control message (cmsg) #level, cmsg #type and cmsg #data. + */ rb_cAncillaryData = rb_define_class_under(rb_cSocket, "AncillaryData", rb_cObject); rb_define_method(rb_cAncillaryData, "initialize", ancillary_initialize, 4); rb_define_method(rb_cAncillaryData, "inspect", ancillary_inspect, 0); Index: ruby_1_9_3/ext/socket/sockssocket.c =================================================================== --- ruby_1_9_3/ext/socket/sockssocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/sockssocket.c (revision 32979) @@ -11,6 +11,13 @@ #include "rubysocket.h" #ifdef SOCKS +/* + * call-seq: + * SOCKSSocket.new(host, serv) => socket + * + * Opens a SOCKS connection to +host+ via the SOCKS server +serv+. + * + */ static VALUE socks_init(VALUE sock, VALUE host, VALUE serv) { @@ -25,6 +32,10 @@ } #ifdef SOCKS5 +/* + * Closes the SOCKS connection. + * + */ static VALUE socks_s_close(VALUE sock) { @@ -40,15 +51,17 @@ #endif #endif -/* - * Document-class: ::SOCKSSocket < TCPSocket - * - * SOCKSSocket class - */ void rsock_init_sockssocket(void) { #ifdef SOCKS + /* + * Document-class: SOCKSSocket < TCPSocket + * + * SOCKS is an Internet protocol that routes packets between a client and + * a server through a proxy server. SOCKS5, if supported, additionally + * provides authentication so only authorized users may access a server. + */ rb_cSOCKSSocket = rb_define_class("SOCKSSocket", rb_cTCPSocket); rb_define_method(rb_cSOCKSSocket, "initialize", socks_init, 2); #ifdef SOCKS5 Index: ruby_1_9_3/ext/socket/unixsocket.c =================================================================== --- ruby_1_9_3/ext/socket/unixsocket.c (revision 32978) +++ ruby_1_9_3/ext/socket/unixsocket.c (revision 32979) @@ -492,15 +492,15 @@ } #endif -/* - * Document-class: ::UNIXSocket < BasicSocket - * - * UNIXSocket represents a UNIX domain stream client socket. - */ void rsock_init_unixsocket(void) { #ifdef HAVE_SYS_UN_H + /* + * Document-class: UNIXSocket < BasicSocket + * + * UNIXSocket represents a UNIX domain stream client socket. + */ rb_cUNIXSocket = rb_define_class("UNIXSocket", rb_cBasicSocket); rb_define_method(rb_cUNIXSocket, "initialize", unix_init, 1); rb_define_method(rb_cUNIXSocket, "path", unix_path, 0); -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/