From 12979424515344460afb12002ce07b670bf7cd6f Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 15 Aug 2011 23:08:39 +0000 Subject: * ext/socket: Make Socket documentation appear. Add documentation for Socket, TCPServer, SOCKSSocket. Patch by Sylvain Daubert. [Ruby 1.9 - Feature #5182] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32977 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/socket/socket.c | 142 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 105 insertions(+), 37 deletions(-) (limited to 'ext/socket/socket.c') diff --git a/ext/socket/socket.c b/ext/socket/socket.c index c2743cd621..4613892e7d 100644 --- a/ext/socket/socket.c +++ b/ext/socket/socket.c @@ -1792,48 +1792,116 @@ socket_s_ip_address_list(VALUE self) #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 - * * Programming Ruby from The Pragmatic Bookshelf. - * - * Much material in this documentation is taken with permission from - * Programming Ruby 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 + * 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 + * * Programming Ruby from The Pragmatic Bookshelf. + * + * Much material in this documentation is taken with permission from + * Programming Ruby from The Pragmatic Bookshelf. + */ rb_cSocket = rb_define_class("Socket", rb_cBasicSocket); rsock_init_socket_init(); -- cgit v1.2.3