polyphony 0.99.4 → 0.99.6

data/lib/polyphony/extensions/socket.rb

@@ -28,19 +28,16 @@ end
 class ::Socket < ::BasicSocket
 
   # Accepts an incoming connection.
-  
+
   # @return [TCPSocket] new connection
   def accept
     Polyphony.backend_accept(self, TCPSocket)
   end
 
-  # call-seq:
-  #   socket.accept_loop { |conn| ... }
-  #
   # Accepts incoming connections in an infinite loop.
   #
-  # @yield [Socket] block receiving accepted sockets
-  # @return [void]
+  # @yield [Socket] accepted socket
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, TCPSocket, &block)
   end
@@ -61,12 +58,6 @@ class ::Socket < ::BasicSocket
   # @!visibility private
   alias_method :orig_read, :read
 
-  # call-seq:
-  #   socket.read -> string
-  #   socket.read(maxlen) -> string
-  #   socket.read(maxlen, buf) -> buf
-  #   socket.read(maxlen, buf, buf_pos) -> buf
-  #
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
@@ -98,11 +89,6 @@ class ::Socket < ::BasicSocket
     buf
   end
 
-  # call-seq:
-  #   socket.recv(maxlen) -> string
-  #   socket.recv(maxlen, flags) -> string
-  #   socket.recv(maxlen, flags, buf) -> buf
-  #
   # Receives up to `maxlen` bytes from the socket. If `outbuf` is given, it is
   # used as the buffer to receive into, otherwise a new string is allocated and
   # used as buffer.
@@ -118,27 +104,17 @@ class ::Socket < ::BasicSocket
     Polyphony.backend_recv(self, outbuf || +'', maxlen, 0)
   end
 
-  # call-seq:
-  #   socket.recv_loop { |data| ... }
-  #   socket.recv_loop(maxlen) { |data| ... }
-  #   socket.read_loop { |data| ... }
-  #   socket.read_loop(maxlen) { |data| ... }
-  #
   # Receives up to `maxlen` bytes at a time in an infinite loop. Read buffers
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @yield [String] handler block
-  # @return [void]
+  # @yield [String] received data
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
   alias_method :read_loop, :recv_loop
 
-  # call-seq:
-  #   socket.feed_loop(receiver, method)
-  #   socket.feed_loop(receiver, method) { |result| ... }
-  #
   # Receives data from the socket in an infinite loop, passing the data to the
   # given receiver using the given method. If a block is given, the result of
   # the method call to the receiver is passed to the block.
@@ -155,8 +131,7 @@ class ::Socket < ::BasicSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @yield [any] block to handle result of method call to receiver
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
@@ -179,12 +154,6 @@ class ::Socket < ::BasicSocket
     end
   end
 
-  # call-seq:
-  #   socket.readpartial(maxlen) -> string
-  #   socket.readpartial(maxlen, buf) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos, raise_on_eof) -> buf
-  #
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
@@ -246,7 +215,7 @@ class ::Socket < ::BasicSocket
   class << self
   # @!visibility private
   alias_method :orig_getaddrinfo, :getaddrinfo
-    
+
     # Resolves the given addr using a worker thread from the default thread
     # pool.
     #
@@ -291,7 +260,7 @@ class ::TCPSocket < ::IPSocket
 
   # @!visibility private
   alias_method :orig_close, :close
-  
+
   # Closes the socket.
   #
   # @return [TCPSocket] self
@@ -302,7 +271,7 @@ class ::TCPSocket < ::IPSocket
 
   # @!visibility private
   alias_method :orig_setsockopt, :setsockopt
-  
+
   # Calls `setsockopt` with the given arguments.
   #
   # @return [TCPSocket] self
@@ -313,7 +282,7 @@ class ::TCPSocket < ::IPSocket
 
   # @!visibility private
   alias_method :orig_closed?, :closed?
-  
+
   # Returns true if the socket is closed.
   #
   # @return [bool] is socket closed
@@ -356,12 +325,6 @@ class ::TCPSocket < ::IPSocket
   # @!visibility private
   alias_method :orig_read, :read
 
-  # call-seq:
-  #   socket.read -> string
-  #   socket.read(maxlen) -> string
-  #   socket.read(maxlen, buf) -> buf
-  #   socket.read(maxlen, buf, buf_pos) -> buf
-  #
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
@@ -393,11 +356,6 @@ class ::TCPSocket < ::IPSocket
     buf
   end
 
-  # call-seq:
-  #   socket.recv(maxlen) -> string
-  #   socket.recv(maxlen, flags) -> string
-  #   socket.recv(maxlen, flags, buf) -> buf
-  #
   # Receives up to `maxlen` bytes from the socket. If `outbuf` is given, it is
   # used as the buffer to receive into, otherwise a new string is allocated and
   # used as buffer.
@@ -413,27 +371,17 @@ class ::TCPSocket < ::IPSocket
     Polyphony.backend_recv(self, outbuf || +'', maxlen, 0)
   end
 
-  # call-seq:
-  #   socket.recv_loop { |data| ... }
-  #   socket.recv_loop(maxlen) { |data| ... }
-  #   socket.read_loop { |data| ... }
-  #   socket.read_loop(maxlen) { |data| ... }
-  #
   # Receives up to `maxlen` bytes at a time in an infinite loop. Read buffers
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @yield [String] handler block
-  # @return [void]
+  # @yield [String] received data
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
   alias_method :read_loop, :recv_loop
 
-  # call-seq:
-  #   socket.feed_loop(receiver, method)
-  #   socket.feed_loop(receiver, method) { |result| ... }
-  #
   # Receives data from the socket in an infinite loop, passing the data to the
   # given receiver using the given method. If a block is given, the result of
   # the method call to the receiver is passed to the block.
@@ -450,18 +398,11 @@ class ::TCPSocket < ::IPSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @yield [any] block to handle result of method call to receiver
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
 
-  # call-seq:
-  #   socket.readpartial(maxlen) -> string
-  #   socket.readpartial(maxlen, buf) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos, raise_on_eof) -> buf
-  #
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
@@ -530,7 +471,7 @@ class ::TCPServer < ::TCPSocket
   alias_method :orig_accept, :accept
 
   # Accepts an incoming connection.
-  
+
   # @return [TCPSocket] new connection
   def accept
     Polyphony.backend_accept(@io, TCPSocket)
@@ -544,27 +485,23 @@ class ::TCPServer < ::TCPSocket
     #     server.accept_loop { |c| handle_connection(c) }
     #   end
     #
-    # @yield [TCPSocket] code block
     # @return [any] return value of code block
     def multishot_accept(&block)
       Polyphony.backend_multishot_accept(@io, &block)
     end
   end
 
-  # call-seq:
-  #   socket.accept_loop { |conn| ... }
-  #
   # Accepts incoming connections in an infinite loop.
   #
-  # @yield [TCPSocket] handler block
-  # @return [void]
+  # @yield [TCPSocket] accepted socket
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(@io, TCPSocket, &block)
   end
 
   # @!visibility private
   alias_method :orig_close, :close
-  
+
   # Closes the server socket.
   #
   # @return [TCPServer] self
@@ -580,19 +517,16 @@ class ::UNIXServer < ::UNIXSocket
   alias_method :orig_accept, :accept
 
   # Accepts an incoming connection.
-  
+
   # @return [UNIXSocket] new connection
   def accept
     Polyphony.backend_accept(self, UNIXSocket)
   end
 
-  # call-seq:
-  #   socket.accept_loop { |conn| ... }
-  #
   # Accepts incoming connections in an infinite loop.
   #
-  # @yield [UNIXSocket] handler block
-  # @return [void]
+  # @yield [UNIXSocket] accepted socket
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, UNIXSocket, &block)
   end
@@ -602,13 +536,7 @@ end
 class ::UNIXSocket < ::BasicSocket
   # @!visibility private
   alias_method :orig_read, :read
-  
-  # call-seq:
-  #   socket.read -> string
-  #   socket.read(maxlen) -> string
-  #   socket.read(maxlen, buf) -> buf
-  #   socket.read(maxlen, buf, buf_pos) -> buf
-  #
+
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
@@ -640,11 +568,6 @@ class ::UNIXSocket < ::BasicSocket
     buf
   end
 
-  # call-seq:
-  #   socket.recv(maxlen) -> string
-  #   socket.recv(maxlen, flags) -> string
-  #   socket.recv(maxlen, flags, buf) -> buf
-  #
   # Receives up to `maxlen` bytes from the socket. If `outbuf` is given, it is
   # used as the buffer to receive into, otherwise a new string is allocated and
   # used as buffer.
@@ -660,27 +583,17 @@ class ::UNIXSocket < ::BasicSocket
     Polyphony.backend_recv(self, outbuf || +'', maxlen, 0)
   end
 
-  # call-seq:
-  #   socket.recv_loop { |data| ... }
-  #   socket.recv_loop(maxlen) { |data| ... }
-  #   socket.read_loop { |data| ... }
-  #   socket.read_loop(maxlen) { |data| ... }
-  #
   # Receives up to `maxlen` bytes at a time in an infinite loop. Read buffers
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @yield [String] handler block
-  # @return [void]
+  # @yield [String] received data
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
   alias_method :read_loop, :recv_loop
 
-  # call-seq:
-  #   socket.feed_loop(receiver, method)
-  #   socket.feed_loop(receiver, method) { |result| ... }
-  #
   # Receives data from the socket in an infinite loop, passing the data to the
   # given receiver using the given method. If a block is given, the result of
   # the method call to the receiver is passed to the block.
@@ -697,8 +610,7 @@ class ::UNIXSocket < ::BasicSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @yield [any] block to handle result of method call to receiver
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
@@ -729,12 +641,6 @@ class ::UNIXSocket < ::BasicSocket
     Polyphony.backend_send(self, mesg, 0)
   end
 
-  # call-seq:
-  #   socket.readpartial(maxlen) -> string
-  #   socket.readpartial(maxlen, buf) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos, raise_on_eof) -> buf
-  #
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the

data/lib/polyphony/extensions/thread.rb

@@ -12,8 +12,6 @@ class ::Thread
 
   # Initializes the thread.
   # @param args [Array] arguments to pass to thread block
-  # @yield [any] thread block
-  # @return [void]
   def initialize(*args, &block)
     @join_wait_queue = []
     @finalization_mutex = Mutex.new
@@ -24,22 +22,17 @@ class ::Thread
 
   # Sets up the thread and its main fiber.
   #
-  # @return [void]
+  # @return [Thread] self
   def setup
     @main_fiber = Fiber.current
     @main_fiber.setup_main_fiber
     setup_fiber_scheduling
+    self
   end
 
   # @!visibility private
   alias_method :orig_join, :join
 
-  # call-seq:
-  #   thread.join -> result
-  #   thread.join(timeout) -> result
-  #   thread.await -> result
-  #   thread.await(timeout) -> result
-  # 
   # Waits for the thread to terminate and returns its return value. If the
   # thread terminated with an uncaught exception, it is propagated to the
   # waiting fiber. If a timeout interval is specified, the thread will be
@@ -64,11 +57,6 @@ class ::Thread
   # @!visibility private
   alias_method :orig_raise, :raise
 
-  # call-seq:
-  #   thread.raise
-  #   thread.raise(exception_class)
-  #   thread.raise(exception_instance)
-  # 
   # Raises an exception in the context of the thread. If no exception is given,
   # a `RuntimeError` is raised.
   #
@@ -136,7 +124,6 @@ class ::Thread
 
   # Sets the idle handler for the thread's backend.
   #
-  # @yield [] idle handler
   # @return [Proc] idle handler
   def on_idle(&block)
     backend.idle_proc = block
@@ -146,7 +133,7 @@ class ::Thread
 
   # Runs the thread's block, handling any uncaught exceptions.
   #
-  # @return [void]
+  # @return [any] thread result value
   def execute
     # backend must be created in the context of the new thread, therefore it
     # cannot be created in Thread#initialize
@@ -172,7 +159,6 @@ class ::Thread
   # Finalizes the thread.
   #
   # @param result [any] thread's return value
-  # @return [void]
   def finalize(result)
     unless Fiber.current.children.empty?
       Fiber.current.shutdown_all_children
@@ -188,7 +174,6 @@ class ::Thread
   # Signals all fibers waiting for the thread to terminate.
   #
   # @param result [any] thread's return value
-  # @return [void]
   def signal_waiters(result)
     @join_wait_queue.each { |w| w.signal(result) }
   end

data/lib/polyphony/extensions/timeout.rb

@@ -13,7 +13,6 @@ module ::Timeout
   # @param sec [Number] timeout period in seconds
   # @param klass [Class] exception class
   # @param message [String] exception message
-  # @yield [] code to run
   # @return [any] block's return value
   def self.timeout(sec, klass = Timeout::Error, message = 'execution expired', &block)
     cancel_after(sec, with_exception: [klass, message], &block)

data/lib/polyphony/net.rb

@@ -4,16 +4,11 @@ require_relative './extensions/socket'
 require_relative './extensions/openssl'
 
 module Polyphony
-  
+
   # A more elegant networking API
   module Net
     class << self
 
-      # call-seq:
-      #   Polyphony::Net.tcp_connect(host, port) -> TCPSocket
-      #   Polyphony::Net.tcp_connect(host, port, secure: true) -> SSLSocket
-      #   Polyphony::Net.tcp_connect(host, port, secure_context: ctx) -> SSLSocket
-      #
       # Create a TCP connection to the given host and port, returning the new
       # socket. If `opts[:secure]` is true, or if an SSL context is given in
       # `opts[:secure_context]`, a TLS handshake is performed, and an SSLSocket
@@ -21,7 +16,9 @@ module Polyphony
       #
       # @param host [String] hostname
       # @param port [Integer] port number
-      # @param opts [Hash] connection options
+      # @param opts [Hash] options to use
+      # @option opts [boolean] :secure use a default context as SSL context, return `SSLSocket` instance
+      # @option opts [OpenSSL::SSL::SSLContext] :secure_context SSL context to use, return `SSLSocket` instance
       # @return [TCPSocket, SSLSocket] connected socket
       def tcp_connect(host, port, opts = {})
         socket = TCPSocket.new(host, port)
@@ -57,10 +54,9 @@ module Polyphony
       # context will select the first protocol from the list given by the client
       # that appears in the list of given protocols, according to the specified
       # order.
-      # 
+      #
       # @param context [SSLContext] SSL context
       # @param protocols [Array] array of supported protocols
-      # @return [void]
       def setup_alpn(context, protocols)
         context.alpn_protocols = protocols
         context.alpn_select_cb = lambda do |peer_protocols|

data/lib/polyphony/version.rb

@@ -2,5 +2,5 @@
 
 module Polyphony
   # @!visibility private
-  VERSION = '0.99.4'
+  VERSION = '0.99.6'
 end

data/lib/polyphony.rb

@@ -43,11 +43,7 @@ module Polyphony
       end
     end
 
-    # call-seq:
-    #   Polyphony.watch_process(cmd)
-    #   Polyphony.watch_process { sleep 1 }
-    # 
-    # Lubnches a process using either a command or a block for a forked process,
+    # Launches a process using either a command or a block for a forked process,
     # waiting for the child process to terminate.
     def watch_process(cmd = nil, &block)
       Polyphony::Process.watch(cmd, &block)
@@ -136,7 +132,7 @@ module Polyphony
   $VERBOSE = nil
   Object.const_set(:Queue, Polyphony::Queue)
   Object.const_set(:Mutex, Polyphony::Mutex)
-  
+
   require 'monitor'
   Object.const_set(:Monitor, Polyphony::Mutex)