class Mongo::Server
Represents a single server on the server side that can be standalone, part of a replica set, or a mongos.
@since 2.0.0
Constants
- CONNECT_TIMEOUT
The default time in seconds to timeout a connection attempt.
@since 2.4.3
Attributes
@return [ String ] The configured address for the server.
@return [ Cluster ] cluster The server cluster.
@return [ Monitor ] monitor The server monitor.
@return [ Monitoring ] monitoring The monitoring.
@return [ Hash ] The options hash.
Public Class Methods
When the server is flagged for garbage collection, stop the monitor thread.
@example Finalize the object.
Server.finalize(monitor)
@param [ Server::Monitor ] monitor The server monitor.
@since 2.2.0
# File lib/mongo/server.rb, line 206 def self.finalize(monitor) proc { monitor.stop! } end
Instantiate a new server object. Will start the background refresh and subscribe to the appropriate events.
@api private
@example Initialize the server.
Mongo::Server.new('127.0.0.1:27017', cluster, monitoring, listeners)
@note Server must never be directly instantiated outside of a Cluster.
@param [ Address ] address The host:port address to connect to. @param [ Cluster ] cluster The cluster the server belongs to. @param [ Monitoring ] monitoring The monitoring. @param [ Event::Listeners ] event_listeners The event listeners. @param [ Hash ] options The server options.
@option options [ Boolean ] :monitor For internal driver use only:
whether to monitor the server after instantiating it.
@option options [ true, false ] :monitoring_io For internal driver
use only. Set to false to prevent SDAM-related I/O from being done by this server. Note: setting this option to false will make the server non-functional. It is intended for use in tests which manually invoke SDAM state transitions.
@since 2.0.0
# File lib/mongo/server.rb, line 56 def initialize(address, cluster, monitoring, event_listeners, options = {}) @address = address @cluster = cluster @monitoring = monitoring options = options.dup monitor = options.delete(:monitor) @options = options.freeze @event_listeners = event_listeners @monitor = Monitor.new(address, event_listeners, monitoring, options.merge(app_metadata: Monitor::AppMetadata.new(cluster.options))) unless monitor == false start_monitoring end @connected = true @pool_lock = Mutex.new end
Public Instance Methods
Is this server equal to another?
@example Is the server equal to the other?
server == other
@param [ Object ] other The object to compare to.
@return [ true, false ] If the servers are equal.
@since 2.0.0
# File lib/mongo/server.rb, line 137 def ==(other) return false unless other.is_a?(Server) address == other.address end
Determine if a connection to the server is able to be established and messages can be sent to it.
@example Is the server connectable?
server.connectable?
@return [ true, false ] If the server is connectable.
@since 2.1.0
@deprecated No longer necessary with Server Selection specification.
# File lib/mongo/server.rb, line 167 def connectable?; end
Whether the server is connected.
@return [ true|false ] Whether the server is connected.
@api private @since 2.7.0
# File lib/mongo/server.rb, line 193 def connected? @connected end
Get a new context for this server in which to send messages.
@example Get the server context.
server.context
@return [ Mongo::Server::Context ] context The server context.
@since 2.0.0
@deprecated Will be removed in version 3.0
# File lib/mongo/server.rb, line 152 def context Context.new(self) end
Disconnect the server from the connection.
@example Disconnect the server.
server.disconnect!
@param [ Boolean ] wait Whether to wait for background threads to
finish running.
@return [ true ] Always true with no exception.
@since 2.0.0
# File lib/mongo/server.rb, line 180 def disconnect!(wait=false) pool.disconnect! monitor.stop!(wait) @connected = false true end
Handle authentication failure.
@example Handle possible authentication failure.
server.handle_auth_failure! do Auth.get(user).login(self) end
@raise [ Auth::Unauthorized ] If the authentication failed.
@return [ Object ] The result of the block execution.
@since 2.3.0
# File lib/mongo/server.rb, line 360 def handle_auth_failure! yield rescue Mongo::Error::SocketTimeoutError # possibly cluster is slow, do not give up on it raise rescue Mongo::Error::SocketError # non-timeout network error unknown! pool.disconnect! raise rescue Auth::Unauthorized # auth error, keep server description and topology as they are pool.disconnect! raise end
Handle handshake failure.
@since 2.7.0 @api private
# File lib/mongo/server.rb, line 341 def handle_handshake_failure! yield rescue Mongo::Error::SocketError, Mongo::Error::SocketTimeoutError unknown! raise end
Get a pretty printed server inspection.
@example Get the server inspection.
server.inspect
@return [ String ] The nice inspection string.
@since 2.0.0
# File lib/mongo/server.rb, line 235 def inspect "#<Mongo::Server:0x#{object_id} address=#{address.host}:#{address.port}>" end
Determine if the provided tags are a subset of the server's tags.
@example Are the provided tags a subset of the server's tags.
server.matches_tag_set?({ 'rack' => 'a', 'dc' => 'nyc' })
@param [ Hash ] tag_set The tag set to compare to the server's tags.
@return [ true, false ] If the provided tags are a subset of the server's tags.
@since 2.0.0
# File lib/mongo/server.rb, line 303 def matches_tag_set?(tag_set) tag_set.keys.all? do |k| tags[k] && tags[k] == tag_set[k] end end
Get the connection pool for this server.
@example Get the connection pool for the server.
server.pool
@return [ Mongo::Server::ConnectionPool ] The connection pool.
@since 2.0.0
# File lib/mongo/server.rb, line 283 def pool @pool_lock.synchronize do @pool ||= begin ConnectionPool.new(options) do |generation| Connection.new(self, options.merge(generation: generation)) end end end end
Restart the server monitor.
@example Restart the server monitor.
server.reconnect!
@return [ true ] Always true.
@since 2.1.0
# File lib/mongo/server.rb, line 317 def reconnect! monitor.restart! @connected = true end
Will writes sent to this server be retried.
@example Will writes be retried.
server.retry_writes?
@return [ true, false ] If writes will be retried.
@note Retryable writes are only available on server versions 3.6+ and with
sharded clusters or replica sets.
@since 2.5.0
# File lib/mongo/server.rb, line 387 def retry_writes? !!(features.sessions_enabled? && logical_session_timeout && !standalone?) end
Start monitoring the server.
Used internally by the driver to add a server to a cluster while delaying monitoring until the server is in the cluster.
@api private
# File lib/mongo/server.rb, line 216 def start_monitoring publish_sdam_event( Monitoring::SERVER_OPENING, Monitoring::Event::ServerOpening.new(address, cluster.topology) ) if options[:monitoring_io] != false monitor.run! ObjectSpace.define_finalizer(self, self.class.finalize(monitor)) end end
@note This method is experimental and subject to change.
@api experimental @since 2.7.0
# File lib/mongo/server.rb, line 243 def summary status = case when primary? 'PRIMARY' when secondary? 'SECONDARY' when standalone? 'STANDALONE' when arbiter? 'ARBITER' when ghost? 'GHOST' when other? 'OTHER' when unknown? 'UNKNOWN' else # Since the summary method is often used for debugging, do not raise # an exception in case none of the expected types matched '' end if replica_set_name status += " replica_set=#{replica_set_name}" end address_bit = if address "#{address.host}:#{address.port}" else 'nil' end "#<Server address=#{address_bit} #{status}>" end
Marks server unknown and publishes the associated SDAM event (server description changed).
@since 2.4.0, SDAM events are sent as of version 2.7.0
# File lib/mongo/server.rb, line 395 def unknown! # Just dispatch the description changed event here, SDAM flow # will update description on the server without in-place mutations # and invoke SDAM transitions as needed. publish(Event::DESCRIPTION_CHANGED, description, Description.new(address)) end
@api private
# File lib/mongo/server.rb, line 403 def update_description(description) monitor.instance_variable_set('@description', description) end
Execute a block of code with a connection, that is checked out of the server's pool and then checked back in.
@example Send a message with the connection.
server.with_connection do |connection| connection.dispatch([ command ]) end
@return [ Object ] The result of the block execution.
@since 2.3.0
# File lib/mongo/server.rb, line 333 def with_connection(&block) pool.with_connection(&block) end