async-io 1.20.0 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69adfd1cd876361c3b94bc80a5f5c164d45df0156a37c6f9fc54542a79bc443c
-  data.tar.gz: 32758166362e4780b7d251d4f649cdc2eb14fd4ab48a378be94968c5719053df
+  metadata.gz: ef50d94f2e881c86637e32d46f307a88b457537e9a649592d851e768474ffe2a
+  data.tar.gz: 24aac313f12b07478e080fa5713432b6e270be5d74e21688bb39efed2d4cf296
 SHA512:
-  metadata.gz: 9fc9a5d6e563b8dbe9b2c700ce284ae905efb90a338b79ebed4daff5368912707355fe40efcbda243948e061bd0b143cd8e4bf22bf232dbc9afcf9d93aa5356b
-  data.tar.gz: 94d7271c1c6e50a84c3120ae408989b2caeab045a8b07e54d417d4bc6159eea35138cc20cc86ba879d4492e457aee75eaa078ad23d2826c80c21fa12ed24d128
+  metadata.gz: '02688618b5035611cc4753acd581c0691c957ea0daefbdd4c357c52a4a31c12783b44dae77a5654aed36022abccac05a0813d300974dd94be26e97d5b25c47e9'
+  data.tar.gz: 811063ba4e91b823be5e8037fcf537bb40aa35bbbf7210df5fe21348b1394e579f27a7c0721114da9671c2ad108d0a70413040850d0643f5602cfc7ad5abc44f

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+

data/examples/udp/client.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'async'
+require 'async/io'
+
+endpoint = Async::IO::Endpoint.udp("localhost", 5678)
+
+Async do |task|
+	endpoint.connect do |socket|
+		socket.send("Hello World")
+		pp socket.recv(1024)
+	end
+end

data/examples/udp/server.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'async'
+require 'async/io'
+
+endpoint = Async::IO::Endpoint.udp("localhost", 5678)
+
+Async do |task|
+	endpoint.bind do |socket|
+		while true
+			data, address = socket.recvfrom(1024)
+			socket.send(data.reverse, 0, address)
+		end
+	end
+end

data/lib/async/io/endpoint.rb

@@ -28,29 +28,62 @@ module Async
 		# Endpoints represent a way of connecting or binding to an address.
 		class Endpoint
 			def initialize(**options)
-				@options = options
+				@options = options.freeze
 			end
 			
-			attr :options
+			def with(**options)
+				dup = self.dup
+				
+				dup.options = @options.merge(options)
+				
+				return dup
+			end
+			
+			attr_accessor :options
 			
+			# @return [String] The hostname of the bound socket.
 			def hostname
 				@options[:hostname]
 			end
 			
+			# If `SO_REUSEPORT` is enabled on a socket, the socket can be successfully bound even if there are existing sockets bound to the same address, as long as all prior bound sockets also had `SO_REUSEPORT` set before they were bound.
+			# @return [Boolean, nil] The value for `SO_REUSEPORT`.
 			def reuse_port
 				@options[:reuse_port]
 			end
 			
+			# If `SO_REUSEADDR` is enabled on a socket prior to binding it, the socket can be successfully bound unless there is a conflict with another socket bound to exactly the same combination of source address and port. Additionally, when set, binding a socket to the address of an existing socket in `TIME_WAIT` is not an error.
+			# @return [Boolean] The value for `SO_REUSEADDR`.
+			def reuse_address
+				@options[:reuse_address]
+			end
+			
+			# Controls SO_LINGER. The amount of time the socket will stay in the `TIME_WAIT` state after being closed.
+			# @return [Integer, nil] The value for SO_LINGER.
+			def linger
+				@options[:linger]
+			end
+			
+			# @return [Numeric] The default timeout for socket operations.
 			def timeout
 				@options[:timeout]
 			end
 			
+			# @return [Address] the address to bind to before connecting.
+			def local_address
+				@options[:local_address]
+			end
+			
+			# Endpoints sometimes have multiple paths.
+			# @yield [Endpoint] Enumerate all discrete paths as endpoints.
 			def each
 				return to_enum unless block_given?
 				
 				yield self
 			end
 			
+			# Accept connections from the specified endpoint.
+			# @param backlog [Integer] the number of connections to listen for.
 			def accept(backlog = Socket::SOMAXCONN, &block)
 				bind do |server|
 					server.listen(backlog)
@@ -59,10 +92,36 @@ module Async
 				end
 			end
 			
+			# Map all endpoints by invoking `#bind`.
+			# @yield the bound wrapper.
+			def bound
+				wrappers = []
+				
+				self.each do |endpoint|
+					wrapper = endpoint.bind
+					wrappers << wrapper
+					
+					yield wrapper
+				end
+				
+				return wrappers
+			ensure
+				wrappers.each(&:close) if $!
+			end
+			
+			# Create an Endpoint instance by URI scheme. The host and port of the URI will be passed to the Endpoint factory method, along with any options.
+			#
+			# @param string [String] URI as string. Scheme will decide implementation used.
+			# @param options keyword arguments passed through to {#initialize}
+			#
+			# @see Endpoint.ssl ssl - invoked when parsing a URL with the ssl scheme "ssl://127.0.0.1"
+			# @see Endpoint.tcp tcp - invoked when parsing a URL with the tcp scheme: "tcp://127.0.0.1"
+			# @see Endpoint.udp udp - invoked when parsing a URL with the udp scheme: "udp://127.0.0.1"
+			# @see Endpoint.unix unix - invoked when parsing a URL with the unix scheme: "unix://127.0.0.1"
 			def self.parse(string, **options)
 				uri = URI.parse(string)
 				
-				self.send(uri.scheme, uri.host, uri.port, **options)
+				self.public_send(uri.scheme, uri.host, uri.port, **options)
 			end
 		end
 	end

data/lib/async/io/endpoint/each.rb

@@ -41,7 +41,7 @@ module Async
 				end
 			end
 			
-			# Generate a list of endpoint from an array.
+			# Generate a list of endpoints from an array.
 			def self.each(specifications, &block)
 				return to_enum(:each, specifications) unless block_given?
 				

data/lib/async/io/host_endpoint.rb

@@ -43,15 +43,24 @@ module Async
 			# @yield [Socket] the socket which is being connected, may be invoked more than once
 			# @return [Socket] the connected socket
 			# @raise if no connection could complete successfully
-			def connect(&block)
+			def connect
 				last_error = nil
 				
+				task = Task.current
+				
 				Addrinfo.foreach(*@specification) do |address|
 					begin
-						return Socket.connect(address, **@options, &block)
-					# This is a little bit risky. In theory, what it is supposed to do is catch the failed connection, and try the next address. In practice, it can catch other kinds of failures. Ideally, it only applies to `#connect`, but it also applies to what's executed in `&block`.
-					rescue
+						wrapper = Socket.connect(address, **@options, task: task)
+					rescue Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::EAGAIN
 						last_error = $!
+					else
+						return wrapper unless block_given?
+						
+						begin
+							return yield wrapper, task
+						ensure
+							wrapper.close
+						end
 					end
 				end
 				
@@ -78,13 +87,20 @@ module Async
 		end
 		
 		class Endpoint
-			# args: nodename, service, family, socktype, protocol, flags
+			# @param args nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_STREAM.
+			# @param options keyword arguments passed on to {HostEndpoint#initialize}
+			#
+			# @return [HostEndpoint]
 			def self.tcp(*args, **options)
 				args[3] = ::Socket::SOCK_STREAM
 				
 				HostEndpoint.new(args, **options)
 			end
 
+			# @param args nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_DGRAM.
+			# @param options keyword arguments passed on to {HostEndpoint#initialize}
+			#
+			# @return [HostEndpoint]
 			def self.udp(*args, **options)
 				args[3] = ::Socket::SOCK_DGRAM
 				

data/lib/async/io/shared_endpoint.rb

@@ -22,31 +22,27 @@ require_relative 'endpoint'
 
 module Async
 	module IO
+		# Pre-connect and pre-bind sockets so that it can be used between processes.
 		class SharedEndpoint < Endpoint
+			# Create a new `SharedEndpoint` by binding to the given endpoint.
 			def self.bound(endpoint, backlog = Socket::SOMAXCONN)
-				wrappers = []
-				
-				endpoint.each do |endpoint|
-					server = endpoint.bind
-					
+				wrappers = endpoint.bound do |server|
 					server.listen(backlog)
-					
 					server.close_on_exec = false
 					server.reactor = nil
-					
-					wrappers << server
 				end
 				
-				self.new(endpoint, wrappers)
+				return self.new(endpoint, wrappers)
 			end
 			
+			# Create a new `SharedEndpoint` by connecting to the given endpoint.
 			def self.connected(endpoint)
-				peer = endpoint.connect
+				wrapper = endpoint.connect
 				
-				peer.close_on_exec = false
-				peer.reactor = nil
+				wrapper.close_on_exec = false
+				wrapper.reactor = nil
 				
-				self.new(endpoint, [peer])
+				return self.new(endpoint, [wrapper])
 			end
 			
 			def initialize(endpoint, wrappers, **options)
@@ -59,8 +55,10 @@ module Async
 			attr :endpoint
 			attr :wrappers
 			
+			# Close all the internal wrappers.
 			def close
 				@wrappers.each(&:close)
+				@wrappers.clear
 			end
 			
 			def bind

data/lib/async/io/socket.rb

@@ -108,6 +108,7 @@ module Async
 			
 			include ::Socket::Constants
 			
+			# @raise Errno::EAGAIN the connection failed due to the remote end being overloaded.
 			def connect(*args)
 				begin
 					async_send(:connect_nonblock, *args)
@@ -142,9 +143,23 @@ module Async
 			alias sysaccept accept
 			
 			# Build and wrap the underlying io.
-			def self.build(*args, timeout: nil, task: Task.current)
+			# @option reuse_port [Boolean] Allow this port to be bound in multiple processes.
+			# @option reuse_address [Boolean] Allow this port to be bound in multiple processes.
+			def self.build(*args, timeout: nil, reuse_address: true, reuse_port: nil, linger: nil, task: Task.current)
 				socket = wrapped_klass.new(*args)
 				
+				if reuse_address
+					socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEADDR, 1)
+				end
+				
+				if reuse_port
+					socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEPORT, 1)
+				end
+				
+				if linger
+					socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_LINGER, linger)
+				end
+				
 				yield socket
 				
 				wrapper = self.new(socket, task.reactor)
@@ -160,19 +175,14 @@ module Async
 			# Establish a connection to a given `remote_address`.
 			# @example
 			#  socket = Async::IO::Socket.connect(Async::IO::Address.tcp("8.8.8.8", 53))
-			# @param remote_address [Addrinfo] The remote address to connect to.
-			# @param local_address [Addrinfo] The local address to bind to before connecting.
-			# @option protcol [Integer] The socket protocol to use.
-			def self.connect(remote_address, local_address = nil, reuse_port: nil, task: Task.current, **options)
+			# @param remote_address [Address] The remote address to connect to.
+			# @option local_address [Address] The local address to bind to before connecting.
+			def self.connect(remote_address, local_address: nil, task: Task.current, **options)
 				Async.logger.debug(self) {"Connecting to #{remote_address.inspect}"}
 				
 				task.annotate "connecting to #{remote_address.inspect}"
 				
 				wrapper = build(remote_address.afamily, remote_address.socktype, remote_address.protocol, **options) do |socket|
-					if reuse_port
-						socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEADDR, 1)
-					end
-					
 					if local_address
 						socket.bind(local_address.to_sockaddr)
 					end
@@ -200,19 +210,10 @@ module Async
 			#  socket = Async::IO::Socket.bind(Async::IO::Address.tcp("0.0.0.0", 9090))
 			# @param local_address [Address] The local address to bind to.
 			# @option protocol [Integer] The socket protocol to use.
-			# @option reuse_port [Boolean] Allow this port to be bound in multiple processes.
-			def self.bind(local_address, protocol: 0, reuse_port: nil, reuse_address: true, task: Task.current, **options, &block)
+			def self.bind(local_address, protocol: 0, task: Task.current, **options, &block)
 				Async.logger.debug(self) {"Binding to #{local_address.inspect}"}
 				
 				wrapper = build(local_address.afamily, local_address.socktype, protocol, **options) do |socket|
-					if reuse_address
-						socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEADDR, 1)
-					end
-					
-					if reuse_port
-						socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEPORT, 1)
-					end
-					
 					socket.bind(local_address.to_sockaddr)
 				end
 				

data/lib/async/io/ssl_endpoint.rb

@@ -90,7 +90,7 @@ module Async
 				return to_enum unless block_given?
 				
 				@endpoint.each do |endpoint|
-					yield self.class.new(endpoint, @options)
+					yield self.class.new(endpoint, **@options)
 				end
 			end
 		end
@@ -99,6 +99,12 @@ module Async
 		SecureEndpoint = SSLEndpoint
 		
 		class Endpoint
+			# @param args
+			# @param ssl_context [OpenSSL::SSL::SSLContext, nil]
+			# @param hostname [String, nil]
+			# @param options keyword arguments passed through to {Endpoint.tcp}
+			#
+			# @return [SSLEndpoint]
 			def self.ssl(*args, ssl_context: nil, hostname: nil, **options)
 				SSLEndpoint.new(self.tcp(*args, **options), ssl_context: ssl_context, hostname: hostname)
 			end

data/lib/async/io/standard.rb

@@ -22,8 +22,26 @@ require_relative 'generic'
 
 module Async
 	module IO
-		STDIN = Generic.new($stdin)
-		STDOUT = Generic.new($stdout)
-		STDERR = Generic.new($stderr)
+		class StandardInput < Generic
+			def initialize(io = $stdin)
+				super(io)
+			end
+		end
+		
+		class StandardOutput < Generic
+			def initialize(io = $stdout)
+				super(io)
+			end
+		end
+		
+		class StandardError < Generic
+			def initialize(io = $stderr)
+				super(io)
+			end
+		end
+		
+		STDIN = StandardInput.new
+		STDOUT = StandardOutput.new
+		STDERR = StandardError.new
 	end
 end

data/lib/async/io/tcp_socket.rb

@@ -54,7 +54,7 @@ module Async
 				end
 			end
 			
-			def initialize(remote_host, remote_port = nil, local_host = nil, local_port = nil)
+			def initialize(remote_host, remote_port = nil, local_host = nil, local_port = 0)
 				if remote_host.is_a? ::TCPSocket
 					super(remote_host)
 				else
@@ -62,7 +62,7 @@ module Async
 					local_address = Addrinfo.tcp(local_host, local_port) if local_host
 					
 					# We do this unusual dance to avoid leaking an "open" socket instance.
-					socket = Socket.connect(remote_address, local_address)
+					socket = Socket.connect(remote_address, local_address: local_address)
 					fd = socket.fcntl(Fcntl::F_DUPFD)
 					Async.logger.debug(self) {"Connected to #{remote_address.inspect}: #{fd}"}
 					socket.close

data/lib/async/io/unix_endpoint.rb

@@ -59,6 +59,11 @@ module Async
 		end
 		
 		class Endpoint
+			# @param path [String]
+			# @param type Socket type
+			# @param options keyword arguments passed through to {UNIXEndpoint#initialize}
+			#
+			# @return [UNIXEndpoint]
 			def self.unix(path, type = ::Socket::SOCK_STREAM, **options)
 				UNIXEndpoint.new(path, type, **options)
 			end

data/lib/async/io/version.rb

@@ -20,6 +20,6 @@
 
 module Async
 	module IO
-		VERSION = "1.20.0"
+		VERSION = "1.21.0"
 	end
 end

data/spec/async/io/endpoint_spec.rb

@@ -57,6 +57,11 @@ RSpec.describe Async::IO::Endpoint do
 			expect(subject.hostname).to be == '0.0.0.0'
 		end
 		
+		it "has local address" do
+			address = Async::IO::Address.tcp('127.0.0.1', 8080)
+			expect(subject.with(local_address: address).local_address).to be == address
+		end
+		
 		let(:message) {"Hello World!"}
 		
 		it "can connect to bound server" do

data/spec/async/io/standard_spec.rb

@@ -31,7 +31,7 @@ end
 RSpec.describe Async::IO::STDOUT do
 	include_context Async::RSpec::Reactor
 	
-	it "should be able to read" do
+	it "should be able to write" do
 		expect(subject.write("")).to be == 0
 	end
 end
@@ -39,7 +39,7 @@ end
 RSpec.describe Async::IO::STDERR do
 	include_context Async::RSpec::Reactor
 	
-	it "should be able to read" do
+	it "should be able to write" do
 		expect(subject.write("")).to be == 0
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-io
 version: !ruby/object:Gem::Version
-  version: 1.20.0
+  version: 1.21.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-04 00:00:00.000000000 Z
+date: 2019-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -119,6 +119,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - README.md
 - Rakefile
@@ -131,6 +132,8 @@ files:
 - examples/issues/broken_ssl.rb
 - examples/millions/client.rb
 - examples/millions/server.rb
+- examples/udp/client.rb
+- examples/udp/server.rb
 - lib/async/io.rb
 - lib/async/io/address.rb
 - lib/async/io/address_endpoint.rb
@@ -201,7 +204,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Provides support for asynchonous TCP, UDP, UNIX and SSL sockets.