cassandra-driver 1.0.0.rc.1-java → 1.1.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 325bb43b4250cf8631082f0427667fd07a0de7fd
-  data.tar.gz: 5868c433339ac05cef2b683873418f2caeb3151d
+  metadata.gz: ba36bd754db916c52e42130906733192c16ec6fa
+  data.tar.gz: dd30b1f020b3647d686e901638305b93c6286412
 SHA512:
-  metadata.gz: e029b8d4e24cc483b0a0b3c5258dd2d41fd9ff502d9a729ac9930d8dd830149625987563f10153e5b0941d55b99609dd1356ee57761b1b5f07f4537dd02ded91
-  data.tar.gz: 54989da93f758c4c9f1d3130e5c9396ace3d48919286ee418d7e183cf7453bf27b2278bb2f0e7fe839b637c5496d00e8dfc56143ef6606314879aaef6f60aec2
+  metadata.gz: e4e143ed5e11f1d2f88fefee54acd0ac3a92ffd2d8f650cf34b2c090041ee1f8e359c3b9c2b93dafd2e6ec8582a691d351e1c8371c4bc376e630273f3e1c0e0e
+  data.tar.gz: bca986745e23c0efc77e24cf2f816e94db79479079dfa2c115476f6d9c14b9c69ad17468f112ea6b65dc4f803f62da14048d25f16ec1eb4f1a073b8e4efb71c7

data/README.md

@@ -9,27 +9,35 @@ the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.
 
 - Code: https://github.com/datastax/ruby-driver
 - Docs: http://datastax.github.io/ruby-driver/
-- JIRA: https://datastax-oss.atlassian.net/browse/RUBY
-- MAILING LIST: https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user
+- Jira: https://datastax-oss.atlassian.net/browse/RUBY
+- Mailing List: https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user
 - IRC: #datastax-drivers on [irc.freenode.net](http://freenode.net>)
-- TWITTER: Follow the latest news about DataStax Drivers - [@avalanche123](http://twitter.com/avalanche123), [@mfiguiere](http://twitter.com/mfiguiere), [@al3xandru](https://twitter.com/al3xandru)
+- Twitter: Follow the latest news about DataStax Drivers - [@avalanche123](http://twitter.com/avalanche123), [@mfiguiere](http://twitter.com/mfiguiere), [@al3xandru](https://twitter.com/al3xandru)
 
 This driver is based on [the cql-rb gem](https://github.com/iconara/cql-rb) by [Theo Hultberg](https://github.com/iconara) and we added support for:
 
-* [asynchronous execution](http://datastax.github.io/ruby-driver/features/asynchronous_io/)
-* one-off, [prepared](http://datastax.github.io/ruby-driver/features/basics/prepared_statements/) and [batch statements](http://datastax.github.io/ruby-driver/features/basics/batch_statements/)
-* automatic peer discovery and cluster metadata
-* various [load-balancing](http://datastax.github.io/ruby-driver/features/load_balancing/), [retry](http://datastax.github.io/ruby-driver/features/retry_policies/) and reconnection policies, [with ability to write your own](http://datastax.github.io/ruby-driver/features/load_balancing/implementing_a_policy/)
+* [Asynchronous execution](http://datastax.github.io/ruby-driver/features/asynchronous_io/)
+* One-off, [prepared](http://datastax.github.io/ruby-driver/features/basics/prepared_statements/) and [batch statements](http://datastax.github.io/ruby-driver/features/basics/batch_statements/)
+* Automatic peer discovery and cluster metadata with [support for change notifications](http://datastax.github.io/ruby-driver/features/state_listeners/)
+* Various [load-balancing](http://datastax.github.io/ruby-driver/features/load_balancing/), [retry](http://datastax.github.io/ruby-driver/features/retry_policies/) and [reconnection](http://datastax.github.io/ruby-driver/features/reconnection/) policies with [ability to write your own](http://datastax.github.io/ruby-driver/features/load_balancing/implementing_a_policy/)
 * [SSL encryption](http://datastax.github.io/ruby-driver/features/security/ssl_encryption/)
+* [Flexible and robust error handling](http://datastax.github.io/ruby-driver/features/error_handling/)
+* [Per-request execution information and tracing](http://datastax.github.io/ruby-driver/features/debugging/)
+* [Configurable address resolution](http://datastax.github.io/ruby-driver/features/address_resolution/)
+
+[Check out the slides from Ruby Driver Explained](https://speakerdeck.com/avalanche123/ruby-driver-explained) for a detailed overview of the Ruby Driver architecture.
 
 ## Compability
 
 This driver works exclusively with the Cassandra Query Language v3 (CQL3) and Cassandra's native protocol. The current version works with:
 
-* Cassandra versions 1.2 and 2.0
-* Ruby 1.9.3 and 2.0
+* Apache Cassandra versions 1.2, 2.0 and partially 2.1
+* DataStax Enterprise 3.1, 3.2, 4.0 and 4.5
+* Ruby (MRI) 1.9.3, 2.0 and 2.1
 * JRuby 1.7
-* Rubinius 2.1
+* Rubinius 2.2
+
+__Note__: Apache Cassandra 2.1 support is limited to the Cassandra 2.0 API, e.g. no user-defined types.
 
 __Note__: JRuby 1.6 is not officially supported, although 1.6.8 should work.
 
@@ -56,7 +64,7 @@ end
 future.join
 ```
 
-The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.
+__Note__: The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.
 
 Read more:
 
@@ -69,29 +77,59 @@ Read more:
 Install via rubygems
 
 ```bash
-gem install cassandra-driver --pre
+gem install cassandra-driver
 ```
 
 Install via Gemfile
 
 ```ruby
-gem 'cassandra-driver', '~> 1.0.0.beta'
+gem 'cassandra-driver', '~> 1.0.0'
 ```
 
-Note: if you want to use compression you should also install [snappy](http://rubygems.org/gems/snappy) or [lz4-ruby](http://rubygems.org/gems/lz4-ruby). [Read more about compression.](http://datastax.github.io/ruby-driver/features/#compression)
+__Note__: if you want to use compression you should also install [snappy](http://rubygems.org/gems/snappy) or [lz4-ruby](http://rubygems.org/gems/lz4-ruby). [Read more about compression.](http://datastax.github.io/ruby-driver/features/#compression)
 
 
 ## Upgrading from cql-rb
 
 Some of the new features added to the driver have unfortunately led to changes in the original cql-rb API. In the examples directory, you can find [an example of how to wrap the ruby driver to achieve almost complete interface parity with cql-rb](https://github.com/datastax/ruby-driver/blob/master/examples/cql-rb-wrapper.rb) to assist you with gradual upgrade.
 
-## What's new in v1.0.0.beta.3
+## What's new in v1.1.0
 
 Current release introduces the following new features:
 
-* [Token-aware load balancing policy](http://datastax.github.io/ruby-driver/features/load_balancing/token_aware/)
-* [SSL encryption](http://datastax.github.io/ruby-driver/features/security/ssl_encryption/)
-* Domain names
+* Ability to disable automatic schema synchronization
+* Schema change event storm protection using a sliding delay
+* [`Cassandra::LoadBalancing::Policy#teardown`](http://datastax.github.io/ruby-driver/api/load_balancing/policy/#teardown-instance_method) for cleaning up resources
+* [`Cassandra::Cluster#refresh_schema`](http://datastax.github.io/ruby-driver/api/cluster/#refresh_schema-instance_method) for manually refreshing schema metadata
+* Host list randomization to prevent hotspots between multiple clients
+* Future listeners run in a dedicated threadpool to not block the reactor
+
+## Code examples
+
+The DataStax Ruby Driver uses the awesome [Cucumber Framework](http://cukes.info/) for both end-to-end, or acceptance, testing and constructing documentation. All of the features supported by the driver have appropriate acceptance tests with easy-to-copy code examples in the `features/` directory.
+
+## Running tests
+
+If you don't feel like reading through the following instructions on how to run ruby-driver tests, feel free to [check out .travis.yml for the entire build code](https://github.com/datastax/ruby-driver/blob/master/.travis.yml).
+
+* Check out the driver codebase and install test dependencies:
+
+```bash
+git clone https://github.com/datastax/ruby-driver.git
+cd ruby-driver
+bundle install --without docs
+```
+
+* [Install ccm](http://www.datastax.com/dev/blog/ccm-a-development-tool-for-creating-local-cassandra-clusters)
+
+* Run tests:
+
+```bash
+bundle exec cucumber # runs end-to-end tests (or bundle exec rake cucumber)
+bundle exec rspec # runs unit tests (or bundle exec rake rspec)
+bundle exec rake integration # run integration tests
+bundle exec rake test # run both as well as integration tests
+```
 
 ## Changelog & versioning
 
@@ -105,7 +143,9 @@ Prereleases will be stable, in the sense that they will have finished and proper
 
 * JRuby 1.6 is not officially supported, although 1.6.8 should work, if you're stuck in JRuby 1.6.8 try and see if it works for you.
 * Because the driver reactor is using `IO.select`, the maximum number of tcp connections allowed is 1024.
+* Because the driver uses `IO#write_nonblock`, Windows is not supported.
 
+Please [refer to the usage documentation for more information on common pitfalls](http://datastax.github.io/ruby-driver/features/)
 
 ## Credits
 

data/lib/cassandra.rb

@@ -25,7 +25,6 @@ require 'ipaddr'
 require 'set'
 require 'bigdecimal'
 require 'forwardable'
-require 'timeout'
 require 'digest'
 require 'stringio'
 require 'resolv'
@@ -51,7 +50,7 @@ module Cassandra
   # @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L591-L603 Description of possible types of writes in Apache Cassandra native protocol spec v1
   WRITE_TYPES = [:simple, :batch, :unlogged_batch, :counter, :batch_log].freeze
 
-  # Creates a {Cassandra::Cluster} instance
+  # Creates a {Cassandra::Cluster Cluster instance}.
   #
   # @option options [Array<String, IPAddr>] :hosts (['127.0.0.1']) a list of
   #   initial addresses. Note that the entire list of cluster members will be
@@ -65,22 +64,27 @@ module Cassandra
   #   can skip this option if you specify only hosts from the local datacenter
   #   in `:hosts` option.
   #
+  # @option options [Boolean] :shuffle_replicas (true) whether replicas list
+  #   found by the default Token-Aware Load Balancing Policy should be
+  #   shuffled. See {Cassandra::LoadBalancing::Policies::TokenAware#initialize Token-Aware Load Balancing Policy}.
+  #
   # @option options [Numeric] :connect_timeout (10) connection timeout in
-  #   seconds.
+  #   seconds. Setting value to `nil` will reset it to 5 seconds.
   #
   # @option options [Numeric] :timeout (10) request execution timeout in
-  #   seconds.
+  #   seconds. Setting value to `nil` will remove request timeout.
   #
   # @option options [Numeric] :heartbeat_interval (30) how often should a
   #   heartbeat be sent to determine if a connection is alive. Several things to
   #   note about this option. Only one heartbeat request will ever be
   #   outstanding on a given connection. Each heatbeat will be sent in at least
   #   `:heartbeat_interval` seconds after the last request has been sent on a
-  #   given connection.
+  #   given connection. Setting value to `nil` will remove connection timeout.
   #
   # @option options [Numeric] :idle_timeout (60) period of inactivity after
   #   which a connection is considered dead. Note that this value should be at
-  #   least a few times larger than `:heartbeat_interval`.
+  #   least a few times larger than `:heartbeat_interval`. Setting value to
+  #   `nil` will remove automatic connection termination.
   #
   # @option options [String] :username (none) username to use for
   #   authentication to cassandra. Note that you must also specify `:password`.
@@ -118,12 +122,33 @@ module Cassandra
   #   address resolver to use. Must be one of `:none` or
   #   `:ec2_multi_region`.
   #
+  # @option options [Boolean] :synchronize_schema (true) whether the driver
+  #   should automatically keep schema metadata synchronized. When enabled, the
+  #   driver updates schema metadata after receiving schema change
+  #   notifications from Cassandra. Setting this setting to `false` disables
+  #   automatic schema updates. Schema metadata is used by the driver to
+  #   determine cluster partitioners as well as to find partition keys and
+  #   replicas of prepared statements, this information makes token aware load
+  #   balancing possible. One can still {Cassandra::Cluster#refresh_schema refresh schema manually}.
+  #
+  # @option options [Numeric] :schema_refresh_delay (1) the driver will wait
+  #   for `:schema_refresh_delay` before fetching metadata after receiving a
+  #   schema change event. This timer is restarted every time a new schema
+  #   change event is received. Finally, when the timer expires or a maximum
+  #   wait time of `:schema_refresh_timeout` has been reached, a schema refresh
+  #   attempt will be made and the timeout is reset.
+  #
+  # @option options [Numeric] :schema_refresh_timeout (10) the maximum delay
+  #   before automatically refreshing schema. Such delay can occur whenever
+  #   multiple schema change events are continuously arriving within
+  #   `:schema_refresh_delay` interval.
+  #
   # @option options [Cassandra::Reconnection::Policy] :reconnection_policy
-  #   default: {Cassandra::Reconnection::Policies::Exponential}. Note that the
-  #   default policy is configured with `(0.5, 30, 2)`.
+  #   default: {Cassandra::Reconnection::Policies::Exponential Exponential}.
+  #   Note that the default policy is configured with `(0.5, 30, 2)`.
   #
   # @option options [Cassandra::Retry::Policy] :retry_policy default:
-  #   {Cassandra::Retry::Policies::Default}.
+  #   {Cassandra::Retry::Policies::Default Default Retry Policy}.
   #
   # @option options [Logger] :logger (none) logger. a {Logger} instance from the
   #   standard library or any object responding to standard log methods
@@ -139,28 +164,28 @@ module Cassandra
   # @option options [Boolean] :trace (false) whether or not to trace all
   #   requests by default.
   #
-  # @option options [Integer] :page_size (nil) default page size for all select
-  #   queries.
+  # @option options [Integer] :page_size (10000) default page size for all
+  #   select queries. Set this value to `nil` to disable paging.
   #
   # @option options [Hash{String => String}] :credentials (none) a hash of credentials - to be used with [credentials authentication in cassandra 1.2](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L238-L250). Note that if you specified `:username` and `:password` options, those credentials are configured automatically.
   #
-  # @option options [Cassandra::Auth::Provider] :auth_provider (none) a custom auth provider to be used with [SASL authentication in cassandra 2.0](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v2.spec#L257-L273). Note that if you have specified `:username` and `:password`, then a {Cassandra::Auth::Providers::Password} will be used automatically.
+  # @option options [Cassandra::Auth::Provider] :auth_provider (none) a custom auth provider to be used with [SASL authentication in cassandra 2.0](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v2.spec#L257-L273). Note that if you have specified `:username` and `:password`, then a {Cassandra::Auth::Providers::Password Password Provider} will be used automatically.
   #
-  # @option options [Cassandra::Compressor] :compressor (none) a custom
-  #   compressor. Note that if you have specified `:compression`, an
+  # @option options [Cassandra::Compression::Compressor] :compressor (none) a
+  #   custom compressor. Note that if you have specified `:compression`, an
   #   appropriate compressor will be provided automatically.
   #
   # @option options [Cassandra::AddressResolution::Policy]
   #   :address_resolution_policy default:
-  #   {Cassandra::AddressResolution::Policies::None} a custom address resolution
+  #   {Cassandra::AddressResolution::Policies::None No Resolution Policy} a custom address resolution
   #   policy. Note that if you have specified `:address_resolution`, an
   #   appropriate address resolution policy will be provided automatically.
   #
   # @option options [Object<#all, #error, #value, #promise>] :futures_factory
-  #   (none) a custom futures factory to assist with integration into existing
-  #   futures library. Note that promises returned by this object must conform
-  #   to {Cassandra::Promise} api, which is not yet public. Things may change,
-  #   use at your own risk.
+  #   default: {Cassandra::Future} a futures factory to assist with integration
+  #   into existing futures library. Note that promises returned by this object
+  #   must conform to {Cassandra::Promise} api, which is not yet public. Things
+  #   may change, use at your own risk.
   #
   # @example Connecting to localhost
   #   cluster = Cassandra.cluster
@@ -174,13 +199,25 @@ module Cassandra
   #
   # @return [Cassandra::Cluster] a cluster instance
   def self.cluster(options = {})
+    cluster_async(options).get
+  end
+
+  # Creates a {Cassandra::Cluster Cluster instance}.
+  #
+  # @see Cassandra.cluster
+  #
+  # @return [Cassandra::Future<Cassandra::Cluster>] a future resolving to the
+  #   cluster instance.
+  def self.cluster_async(options = {})
     options = options.select do |key, value|
       [ :credentials, :auth_provider, :compression, :hosts, :logger, :port,
         :load_balancing_policy, :reconnection_policy, :retry_policy, :listeners,
         :consistency, :trace, :page_size, :compressor, :username, :password,
         :ssl, :server_cert, :client_cert, :private_key, :passphrase,
         :connect_timeout, :futures_factory, :datacenter, :address_resolution,
-        :address_resolution_policy, :idle_timeout, :heartbeat_interval, :timeout
+        :address_resolution_policy, :idle_timeout, :heartbeat_interval, :timeout,
+        :synchronize_schema, :schema_refresh_delay, :schema_refresh_timeout,
+        :shuffle_replicas
       ].include?(key)
     end
 
@@ -195,11 +232,13 @@ module Cassandra
         raise ::ArgumentError, "both :username and :password options must be specified, but only :password given"
       end
 
-      username = String(options.delete(:username))
-      password = String(options.delete(:password))
+      username = options.delete(:username)
+      password = options.delete(:password)
 
-      raise ::ArgumentError, ":username cannot be empty" if username.empty?
-      raise ::ArgumentError, ":password cannot be empty" if password.empty?
+      Util.assert_instance_of(::String, username) { ":username must be a String, #{username.inspect} given" }
+      Util.assert_instance_of(::String, password) { ":password must be a String, #{password.inspect} given" }
+      Util.assert_not_empty(username) { ":username cannot be empty" }
+      Util.assert_not_empty(password) { ":password cannot be empty" }
 
       options[:credentials]   = {:username => username, :password => password}
       options[:auth_provider] = Auth::Providers::Password.new(username, password)
@@ -208,17 +247,13 @@ module Cassandra
     if options.has_key?(:credentials)
       credentials = options[:credentials]
 
-      unless credentials.is_a?(Hash)
-        raise ::ArgumentError, ":credentials must be a hash, #{credentials.inspect} given"
-      end
+      Util.assert_instance_of(::Hash, credentials) { ":credentials must be a hash, #{credentials.inspect} given" }
     end
 
     if options.has_key?(:auth_provider)
       auth_provider = options[:auth_provider]
 
-      unless auth_provider.respond_to?(:create_authenticator)
-        raise ::ArgumentError, ":auth_provider #{auth_provider.inspect} must respond to :create_authenticator, but doesn't"
-      end
+      Util.assert_responds_to(:create_authenticator, auth_provider) { ":auth_provider #{auth_provider.inspect} must respond to :create_authenticator, but doesn't" }
     end
 
     has_client_cert = options.has_key?(:client_cert)
@@ -236,13 +271,8 @@ module Cassandra
       client_cert = ::File.expand_path(options[:client_cert])
       private_key = ::File.expand_path(options[:private_key])
 
-      unless ::File.exists?(client_cert)
-        raise ::ArgumentError, ":client_cert #{client_cert.inspect} doesn't exist"
-      end
-
-      unless ::File.exists?(private_key)
-        raise ::ArgumentError, ":private_key #{private_key.inspect} doesn't exist"
-      end
+      Util.assert_file_exists(client_cert) { ":client_cert #{client_cert.inspect} doesn't exist" }
+      Util.assert_file_exists(private_key) { ":private_key #{private_key.inspect} doesn't exist" }
     end
 
     has_server_cert = options.has_key?(:server_cert)
@@ -250,9 +280,7 @@ module Cassandra
     if has_server_cert
       server_cert = ::File.expand_path(options[:server_cert])
 
-      unless ::File.exists?(server_cert)
-        raise ::ArgumentError, ":server_cert #{server_cert.inspect} doesn't exist"
-      end
+      Util.assert_file_exists(server_cert) { ":server_cert #{server_cert.inspect} doesn't exist" }
     end
 
     if has_client_cert || has_server_cert
@@ -279,9 +307,7 @@ module Cassandra
     if options.has_key?(:ssl)
       ssl = options[:ssl]
 
-      unless ssl.is_a?(::TrueClass) || ssl.is_a?(::FalseClass) || ssl.is_a?(::OpenSSL::SSL::SSLContext)
-        raise ::ArgumentError, ":ssl must be a boolean or an OpenSSL::SSL::SSLContext, #{ssl.inspect} given"
-      end
+      Util.assert_instance_of_one_of([::TrueClass, ::FalseClass, ::OpenSSL::SSL::SSLContext], ssl) { ":ssl must be a boolean or an OpenSSL::SSL::SSLContext, #{ssl.inspect} given" }
     end
 
     if options.has_key?(:compression)
@@ -303,26 +329,20 @@ module Cassandra
       compressor = options[:compressor]
       methods    = [:algorithm, :compress?, :compress, :decompress]
 
-      unless methods.all? {|method| compressor.respond_to?(method)}
-        raise ::ArgumentError, ":compressor #{compressor.inspect} must respond to #{methods.inspect}, but doesn't"
-      end
+      Util.assert_responds_to_all(methods, compressor) { ":compressor #{compressor.inspect} must respond to #{methods.inspect}, but doesn't" }
     end
 
     if options.has_key?(:logger)
       logger  = options[:logger]
       methods = [:debug, :info, :warn, :error, :fatal]
 
-      unless methods.all? {|method| logger.respond_to?(method)}
-        raise ::ArgumentError, ":logger #{logger.inspect} must respond to #{methods.inspect}, but doesn't"
-      end
+      Util.assert_responds_to_all(methods, logger) { ":logger #{logger.inspect} must respond to #{methods.inspect}, but doesn't" }
     end
 
     if options.has_key?(:port)
       port = options[:port] = Integer(options[:port])
 
-      if port < 0 || port > 65536
-        raise ::ArgumentError, ":port must be a valid ip port, #{port.given}"
-      end
+      Util.assert_one_of(0..65536, port) { ":port must be a valid ip port, #{port} given" }
     end
 
     if options.has_key?(:datacenter)
@@ -330,88 +350,99 @@ module Cassandra
     end
 
     if options.has_key?(:connect_timeout)
-      timeout = options[:connect_timeout] = Integer(options[:connect_timeout])
+      timeout = options[:connect_timeout]
 
-      if timeout < 0
-        raise ::ArgumentError, ":connect_timeout must be a positive value, #{timeout.given}"
+      unless timeout.nil?
+        Util.assert_instance_of(::Numeric, timeout) { ":connect_timeout must be a number of seconds, #{timeout} given" }
+        Util.assert(timeout > 0) { ":connect_timeout must be greater than 0, #{timeout} given" }
       end
     end
 
     if options.has_key?(:timeout)
-      timeout = options[:timeout] = Integer(options[:timeout])
+      timeout = options[:timeout]
 
-      if timeout < 0
-        raise ::ArgumentError, ":timeout must be a positive value, #{timeout.given}"
+      unless timeout.nil?
+        Util.assert_instance_of(::Numeric, timeout) { ":timeout must be a number of seconds, #{timeout} given" }
+        Util.assert(timeout > 0) { ":timeout must be greater than 0, #{timeout} given" }
       end
     end
 
     if options.has_key?(:heartbeat_interval)
-      timeout = options[:heartbeat_interval] = Integer(options[:heartbeat_interval])
+      timeout = options[:heartbeat_interval]
 
-      if timeout < 0
-        raise ::ArgumentError, ":heartbeat_interval must be a positive value, #{timeout.given}"
+      unless timeout.nil?
+        Util.assert_instance_of(::Numeric, timeout) { ":heartbeat_interval must be a number of seconds, #{timeout} given" }
+        Util.assert(timeout > 0) { ":heartbeat_interval must be greater than 0, #{timeout} given" }
       end
     end
 
     if options.has_key?(:idle_timeout)
-      timeout = options[:idle_timeout] = Integer(options[:idle_timeout])
+      timeout = options[:idle_timeout]
 
-      if timeout < 0
-        raise ::ArgumentError, ":idle_timeout must be a positive value, #{timeout.given}"
+      unless timeout.nil?
+        Util.assert_instance_of(::Numeric, timeout) { ":idle_timeout must be a number of seconds, #{timeout} given" }
+        Util.assert(timeout > 0) { ":idle_timeout must be greater than 0, #{timeout} given" }
       end
     end
 
+    if options.has_key?(:schema_refresh_delay)
+      timeout = options[:schema_refresh_delay]
+
+      Util.assert_instance_of(::Numeric, timeout) { ":schema_refresh_delay must be a number of seconds, #{timeout} given" }
+      Util.assert(timeout > 0) { ":schema_refresh_delay must be greater than 0, #{timeout} given" }
+    end
+
+    if options.has_key?(:schema_refresh_timeout)
+      timeout = options[:schema_refresh_timeout]
+
+      Util.assert_instance_of(::Numeric, timeout) { ":schema_refresh_timeout must be a number of seconds, #{timeout} given" }
+      Util.assert(timeout > 0) { ":schema_refresh_timeout must be greater than 0, #{timeout} given" }
+    end
+
     if options.has_key?(:load_balancing_policy)
       load_balancing_policy = options[:load_balancing_policy]
-      methods = [:host_up, :host_down, :host_found, :host_lost, :setup, :distance, :plan]
+      methods = [:host_up, :host_down, :host_found, :host_lost, :setup, :teardown, :distance, :plan]
 
-      unless methods.all? {|method| load_balancing_policy.respond_to?(method)}
-        raise ::ArgumentError, ":load_balancing_policy #{load_balancing_policy.inspect} must respond to #{methods.inspect}, but doesn't"
-      end
+      Util.assert_responds_to_all(methods, load_balancing_policy) { ":load_balancing_policy #{load_balancing_policy.inspect} must respond to #{methods.inspect}, but doesn't" }
     end
 
     if options.has_key?(:reconnection_policy)
       reconnection_policy = options[:reconnection_policy]
 
-      unless reconnection_policy.respond_to?(:schedule)
-        raise ::ArgumentError, ":reconnection_policy #{reconnection_policy.inspect} must respond to :schedule, but doesn't"
-      end
+      Util.assert_responds_to(:schedule, reconnection_policy) { ":reconnection_policy #{reconnection_policy.inspect} must respond to :schedule, but doesn't" }
     end
 
     if options.has_key?(:retry_policy)
       retry_policy = options[:retry_policy]
       methods = [:read_timeout, :write_timeout, :unavailable]
 
-      unless methods.all? {|method| retry_policy.respond_to?(method)}
-        raise ::ArgumentError, ":retry_policy #{retry_policy.inspect} must respond to #{methods.inspect}, but doesn't"
-      end
+      Util.assert_responds_to_all(methods, retry_policy) { ":retry_policy #{retry_policy.inspect} must respond to #{methods.inspect}, but doesn't" }
     end
 
     if options.has_key?(:listeners)
-      listeners = options[:listeners]
-
-      unless listeners.respond_to?(:each)
-        raise ::ArgumentError, ":listeners must be an Enumerable, #{listeners.inspect} given"
-      end
+      options[:listeners] = Array(options[:listeners])
     end
 
     if options.has_key?(:consistency)
       consistency = options[:consistency]
 
-      unless CONSISTENCIES.include?(consistency)
-        raise ::ArgumentError, ":consistency must be one of #{CONSISTENCIES.inspect}, #{consistency.inspect} given"
-      end
+      Util.assert_one_of(CONSISTENCIES, consistency) { ":consistency must be one of #{CONSISTENCIES.inspect}, #{consistency.inspect} given" }
     end
 
     if options.has_key?(:trace)
       options[:trace] = !!options[:trace]
     end
 
+    if options.has_key?(:shuffle_replicas)
+      options[:shuffle_replicas] = !!options[:shuffle_replicas]
+    end
+
     if options.has_key?(:page_size)
-      page_size = options[:page_size] = Integer(options[:page_size])
+      page_size = options[:page_size]
 
-      if page_size <= 0
-        raise ::ArgumentError, ":page_size must be a positive integer, #{page_size.inspect} given"
+      unless page_size.nil?
+        page_size = options[:page_size] = Integer(page_size)
+        Util.assert(page_size > 0) { ":page_size must be a positive integer, #{page_size.inspect} given" }
       end
     end
 
@@ -419,9 +450,7 @@ module Cassandra
       futures_factory = options[:futures_factory]
       methods = [:error, :value, :promise, :all]
 
-      unless methods.all? {|method| futures_factory.respond_to?(method)}
-        raise ::ArgumentError, ":futures_factory #{futures_factory.inspect} must respond to #{methods.inspect}, but doesn't"
-      end
+      Util.assert_responds_to_all(methods, futures_factory) { ":futures_factory #{futures_factory.inspect} must respond to #{methods.inspect}, but doesn't" }
     end
 
     if options.has_key?(:address_resolution)
@@ -429,6 +458,7 @@ module Cassandra
 
       case address_resolution
       when :none
+        # do nothing
       when :ec2_multi_region
         options[:address_resolution_policy] = AddressResolution::Policies::EC2MultiRegion.new
       else
@@ -439,9 +469,11 @@ module Cassandra
     if options.has_key?(:address_resolution_policy)
       address_resolver = options[:address_resolution_policy]
 
-      unless address_resolver.respond_to?(:resolve)
-        raise ::ArgumentError, ":address_resolution_policy must respond to :resolve, #{address_resolver.inspect} but doesn't"
-      end
+      Util.assert_responds_to(:resolve, address_resolver) { ":address_resolution_policy must respond to :resolve, #{address_resolver.inspect} but doesn't" }
+    end
+
+    if options.has_key?(:synchronize_schema)
+      options[:synchronize_schema] = !!options[:synchronize_schema]
     end
 
     hosts = []
@@ -463,7 +495,13 @@ module Cassandra
       raise ::ArgumentError, ":hosts #{options[:hosts].inspect} could not be resolved to any ip address"
     end
 
-    Driver.new(options).connect(hosts).value
+    hosts.shuffle!
+  rescue => e
+    futures = options.fetch(:futures_factory) { Driver.new.futures_factory }
+    futures.error(e)
+  else
+    driver = Driver.new(options)
+    driver.connect(hosts)
   end
 end
 
@@ -473,8 +511,9 @@ require 'cassandra/time_uuid'
 require 'cassandra/compression'
 require 'cassandra/protocol'
 require 'cassandra/auth'
-require 'cassandra/client'
+require 'cassandra/null_logger'
 
+require 'cassandra/executors'
 require 'cassandra/future'
 require 'cassandra/cluster'
 require 'cassandra/driver'