socketpool 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov
+  rspec (~> 2.3.0)

data/LICENSE.txt

@@ -0,0 +1,12 @@
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.

data/README.rdoc

@@ -0,0 +1,44 @@
+= socketpool
+
+Class for managing a pool of sockets
+
+== Using socketpool
+
+Install:
+
+  gem install socketpool
+
+Initialize a socket pool:
+  
+  pool = SocketPool.new("127.0.0.1", "11211")  # => a socket pool with a max size of 2, connected via tcp to 127.0.0.1:11211
+  pool = SocketPool.new("127.0.0.1", "11211", :size => 10) # => a socket pool with a max size of 10, connected via tcp to 127.0.0.1:11211 
+  pool = SocketPool.new("127.0.0.1", "11211", :size => 10, :type => :udp) # => a socket pool with a max size of 10, connected via udp to 127.0.0.1:11211 
+
+  s = pool.checkout   #=> gets socket from pool
+  pool.checkin(s)    #=> puts socket back in pool
+
+Initialization Options: 
+  :size #=> determines the max size of the socket pool (number of sockets that can eventually be in the pool)
+  :type #=> the "type" of socket in the pool: must be one of [:udp, :udp6, :tcp, :tcp6, :unix, :unigram]
+        #=> :unigram specifies a datagram unix socket; if using a unix socket then set host and port to the "path"
+
+  :eager #=> default false, if set to "true" then all sockets will be initialized on pool initialization
+  :timeout #=> defaults to 5.0, the number of seconds to wait for an unused socket from the pool to be freed
+  :socketopts #=> an array of options to be set (via setsockopts) on each socket initialization
+              #=> example: [{:level => Socket::IPPROTO_TCP, :optname => Socket::TCP_NODELAY, :optval => 1}]
+
+== Credits
+* "socketpool" is heavily influenced by utils/pool.rb from MongoDB (Apache 2.0 licensed).  
+The socket checkout/checkin functionality is a direct copy, unfortunately all of the functionality I wanted (like eager initialization) was not
+implemented so I augmented it for "socketpool".
+
+== Contributing to socketpool
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "socketpool"
+  gem.homepage = "http://github.com/bdewitt/socketpool"
+  gem.license = "Apache 2.0"
+  gem.summary = "Provides class for managing a socket pool"
+  gem.description = "SocketPool class to mangage socket based client access [based on MongoDB pool class]"
+  gem.email = "brandon+socketpool@myjibe.com"
+  gem.authors = ["Brandon Dewitt"]
+  gem.add_development_dependency 'rspec', '> 2.0'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "socketpool #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/socketpool.rb

@@ -0,0 +1,174 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'socket'
+require 'thread'
+
+class SocketPool
+
+  attr_accessor :host, :port, :size, :timeout, :checked_out
+
+  # Create a new socket pool
+  #
+  def initialize(host, port, opts={})
+    @host, @port = host, port
+
+    # Pool size and timeout.
+    @size      = opts[:size] || 2
+    @timeout   = opts[:timeout]   || 5.0
+    @eager      = opts[:eager] || false
+
+    # Mutex for synchronizing pool access
+    @connection_mutex = Mutex.new
+
+    # Condition variable for signal and wait
+    @queue = ConditionVariable.new
+    
+    @socktype     = opts[:type] || :tcp
+    @sockopts     = opts[:socketopts].nil? ? [] : [opts[:socketopts]].flatten.inject([]){|s, so| s << so}
+    @sockets      = []
+    @pids         = {}
+    @checked_out  = []
+    
+    initialize_socketpool if @eager
+  end
+  
+  def close
+    @sockets.each do |sock|
+      begin
+        sock.close
+      rescue IOError => ex
+        warn "IOError when attempting to close socket connected to #{@host}:#{@port}: #{ex.inspect}"
+      end
+    end
+    @host = @port = nil
+    @sockets.clear
+    @pids.clear
+    @checked_out.clear
+  end
+  
+  # Return a socket to the pool.
+  def checkin(socket)
+    @connection_mutex.synchronize do
+      @checked_out.delete(socket)
+      @queue.signal
+    end
+    true
+  end
+
+  # Adds a new socket to the pool and checks it out.
+  #
+  # This method is called exclusively from #checkout;
+  # therefore, it runs within a mutex.
+  def checkout_new_socket
+    begin
+    socket = Socket.new(so_domain(@socktype), so_type(@socktype), 0)
+    @sockaddr ||= Socket.pack_sockaddr_in(@port, @host) if ![:unix, :unigram].include?(@socktype)
+    @sockaddr ||= Socket.pack_sockaddr_un(@host) if [:unix, :unigram].include?(@socktype)
+    socket.connect(@sockaddr)
+    if @sockopts.size > 0
+      @sockopts.each{ |opt| socket.setsockopt(opt[:level], opt[:optname], opt[:optval]) }  
+    end
+    rescue => ex
+      raise ConnectionFailure, "Failed to connect to host #{@host} and port #{@port}: #{ex}"
+    end
+
+    @sockets << socket
+    @pids[socket] = Process.pid
+    @checked_out << socket
+    socket
+  end
+
+  # Checks out the first available socket from the pool.
+  #
+  # If the pid has changed, remove the socket and check out
+  # new one.
+  #
+  # This method is called exclusively from #checkout;
+  # therefore, it runs within a mutex.
+  def checkout_existing_socket
+    socket = (@sockets - @checked_out).first
+    if @pids[socket] != Process.pid
+       @pids[socket] = nil
+       @sockets.delete(socket)
+       socket.close
+       checkout_new_socket
+    else
+      @checked_out << socket
+      socket
+    end
+  end
+
+  # Check out an existing socket or create a new socket if the maximum
+  # pool size has not been exceeded. Otherwise, wait for the next
+  # available socket.
+  def checkout
+    start_time = Time.now
+    loop do
+      if (Time.now - start_time) > @timeout
+          raise ConnectionTimeoutError, "could not obtain connection within " +
+            "#{@timeout} seconds. The max pool size is currently #{@size}; " +
+            "consider increasing the pool size or timeout."
+      end
+
+      @connection_mutex.synchronize do
+        socket = if @checked_out.size < @sockets.size
+                   checkout_existing_socket
+                 elsif @sockets.size < @size
+                   checkout_new_socket
+                 end
+
+        if socket
+          return socket
+        else
+          # Otherwise, wait
+          @queue.wait(@connection_mutex)
+        end
+      end
+    end
+  end
+  
+  def so_type(val)
+    val = val.downcase.to_sym if val.respond_to?(:downcase) && val.respond_to?(:to_sym)
+    @so_type ||= {
+      :tcp => Socket::SOCK_STREAM,
+      :tcp6 => Socket::SOCK_STREAM,
+      :udp => Socket::SOCK_DGRAM,
+      :udp6 => Socket::SOCK_DGRAM,
+      :unix => Socket::SOCK_STREAM,
+      :unigram => Socket::SOCK_DGRAM
+    }[val]
+  end
+  
+  def so_domain(val)
+    val = val.downcase.to_sym if val.respond_to?(:downcase) && val.respond_to?(:to_sym)
+    @so_domain ||= {
+      :tcp => Socket::AF_INET,
+      :tcp6 => Socket::AF_INET6,
+      :udp => Socket::AF_INET,
+      :udp6 => Socket::AF_INET6,
+      :unix => Socket::AF_UNIX,
+      :unigram => Socket::AF_UNIX
+    }[val]
+  end
+
+  private 
+  
+  def initialize_socketpool
+    begin
+      @size.times{ checkout_new_socket }
+    ensure
+      @checked_out = []
+    end
+  end
+end

data/spec/socketpool_spec.rb

@@ -0,0 +1,75 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "SocketPool arguments" do
+  describe SocketPool.new('127.0.0.1', '11222') do 
+    specify { subject.port.should eq('11222')}
+    specify { subject.host.should eq('127.0.0.1')}
+    specify { subject.size.should eq(2)}
+    specify { subject.timeout.should eq(5.0)}
+    specify { subject.instance_variable_get(:@sockets).should eq([])}
+    specify { subject.instance_variable_get(:@checked_out).should eq([])}
+    specify { subject.instance_variable_get(:@pids).should eq({})}
+    specify { subject.instance_variable_get(:@eager).should eq(false)}
+    specify { subject.instance_variable_get(:@socktype).should eq(:tcp)}
+    specify { subject.instance_variable_get(:@sockopts).should eq([])}
+    
+    it "should create socket on checkout" do 
+      s = subject.checkout
+      subject.instance_variable_get(:@sockets).should_not eq([])
+      subject.instance_variable_get(:@sockets).size.should eq(1)
+      subject.instance_variable_get(:@checked_out).size.should eq(1)
+
+      subject.checkin(s)
+      subject.instance_variable_get(:@checked_out).size.should eq(0)
+    end    
+  end
+
+  describe "UDP => Eager SocketPool" do 
+    subject { SocketPool.new('127.0.0.1', '11222', :type => :udp, :eager => true) }
+    
+    specify { subject.port.should eq('11222')}
+    specify { subject.host.should eq('127.0.0.1')}
+    specify { subject.size.should eq(2)}
+    specify { subject.timeout.should eq(5.0)}
+    specify { subject.instance_variable_get(:@sockets).size.should eq(2)}
+    specify { subject.instance_variable_get(:@checked_out).should eq([])}
+    specify { subject.instance_variable_get(:@eager).should eq(true)}
+    specify { subject.instance_variable_get(:@socktype).should eq(:udp)}
+    specify { subject.instance_variable_get(:@sockopts).should eq([])}    
+  end
+
+  describe "UDP => Eager SocketPool => resized, short timeout" do 
+    subject { SocketPool.new('127.0.0.1', '11222', :type => :udp, :eager => true, :size => 19, :timeout => 1) }
+    
+    specify { subject.port.should eq('11222')}
+    specify { subject.host.should eq('127.0.0.1')}
+    specify { subject.size.should eq(19)}
+    specify { subject.timeout.should eq(1.0)}
+    specify { subject.instance_variable_get(:@sockets).size.should eq(19)}
+    specify { subject.instance_variable_get(:@checked_out).should eq([])}
+    specify { subject.instance_variable_get(:@eager).should eq(true)}
+    specify { subject.instance_variable_get(:@socktype).should eq(:udp)}
+    specify { subject.instance_variable_get(:@sockopts).should eq([])}    
+  end
+
+  describe "TCP => Eager SocketPool => resized, short timeout => TCP_NODELAY" do 
+    subject { 
+      SocketPool.new('127.0.0.1', '11222', 
+        :type => :tcp, 
+        :eager => true, 
+        :size => 19, 
+        :timeout => 1, 
+        :socketopts => [{:level => Socket::IPPROTO_TCP, :optname => Socket::TCP_NODELAY, :optval => 1}]) 
+    }
+    
+    specify { subject.port.should eq('11222')}
+    specify { subject.host.should eq('127.0.0.1')}
+    specify { subject.size.should eq(19)}
+    specify { subject.timeout.should eq(1.0)}
+    specify { subject.instance_variable_get(:@sockets).size.should eq(19)}
+    specify { subject.instance_variable_get(:@checked_out).should eq([])}
+    specify { subject.instance_variable_get(:@eager).should eq(true)}
+    specify { subject.instance_variable_get(:@socktype).should eq(:tcp)}
+    specify { subject.instance_variable_get(:@sockopts).should_not eq([])}    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'socketpool'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification 
+name: socketpool
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Brandon Dewitt
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-03 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 3
+        - 0
+        version: 2.3.0
+  name: rspec
+  version_requirements: *id001
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  name: bundler
+  version_requirements: *id002
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  name: jeweler
+  version_requirements: *id003
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: rcov
+  version_requirements: *id004
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  name: rspec
+  version_requirements: *id005
+  prerelease: false
+description: SocketPool class to mangage socket based client access [based on MongoDB pool class]
+email: brandon+socketpool@myjibe.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- .document
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/socketpool.rb
+- spec/socketpool_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/bdewitt/socketpool
+licenses: 
+- Apache 2.0
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Provides class for managing a socket pool
+test_files: 
+- spec/socketpool_spec.rb
+- spec/spec_helper.rb