Permalink
Browse files

Update session rdoc

  • Loading branch information...
durran committed May 28, 2012
1 parent 1329daa commit 81f253f2b124a8b281e77d08159f606e793daf8f
Showing with 148 additions and 96 deletions.
  1. +148 −96 lib/moped/session.rb
View
@@ -30,54 +30,81 @@ module Moped
class Session
extend Forwardable
- # @return [Hash] this session's options
- attr_reader :options
-
- # @private
- # @return [Cluster] this session's cluster
- attr_reader :cluster
-
- # @private
- # @return [Context] this session's context
- attr_reader :context
-
- # @param [Array] seeds an of host:port pairs
- # @param [Hash] options
- # @option options [Boolean] :safe (false) ensure writes are persisted
- # @option options [Hash] :safe ensure writes are persisted with the
- # specified safety level e.g., "fsync: true", or "w: 2, wtimeout: 5"
- # @option options [Symbol, String] :database the database to use
- # @option options [:strong, :eventual] :consistency (:eventual)
- def initialize(seeds, options = {})
- @cluster = Cluster.new(seeds, {})
- @context = Context.new(self)
- @options = options
- @options[:consistency] ||= :eventual
- end
+ # @attribute [r] cluster The session cluster.
+ # @attribute [r] context The session context.
+ # @attribute [r] options The session options.
+ attr_reader :cluster, :context, :options
- # @return [Boolean] whether the current session requires safe operations.
- def safe?
- !!safety
- end
+ # @method [](collection)
+ # Return +collection+ from the current database.
+ #
+ # @param (see Moped::Database#[])
+ # @return (see Moped::Database#[])
+ delegate :"[]" => :current_database
+
+ # @method command(command)
+ # Run +command+ on the current database.
+ #
+ # @param (see Moped::Database#command)
+ # @return (see Moped::Database#command)
+ delegate :command => :current_database
- # @return [:strong, :eventual] the session's consistency
+ # @method drop
+ # Drop the current database.
+ #
+ # @param (see Moped::Database#drop)
+ # @return (see Moped::Database#drop)
+ delegate :drop => :current_database
+
+ # @method login(username, password)
+ # Log in with +username+ and +password+ on the current database.
+ #
+ # @param (see Moped::Database#login)
+ # @raise (see Moped::Database#login)
+ delegate :login => :current_database
+
+ # @method logout
+ # Log out from the current database.
+ #
+ # @param (see Moped::Database#logout)
+ # @raise (see Moped::Database#login)
+ delegate :logout => :current_database
+
+ # Get the session's consistency.
+ #
+ # @example Get the session consistency.
+ # session.consistency
+ #
+ # @return [ :strong, :eventual ] The session's consistency.
+ #
+ # @since 1.0.0
def consistency
options[:consistency]
end
- # Switch the session's current database.
+ # Initialize a new database session.
#
- # @example
- # session.use :moped
- # session[:people].find.one # => { :name => "John" }
+ # @example Initialize a new session.
+ # Session.new([ "localhost:27017" ])
#
- # @param [String] database the database to use
- def use(database)
- options[:database] = database
- set_current_database database
+ # @param [ Array ] seeds an of host:port pairs
+ # @param [ Hash ] options
+ #
+ # @option options [ Boolean ] :safe (false) Ensure writes are persisted.
+ # @option options [ Hash ] :safe Ensure writes are persisted with the
+ # specified safety level e.g., "fsync: true", or "w: 2, wtimeout: 5".
+ # @option options [ Symbol, String ] :database The database to use.
+ # @option options [ :strong, :eventual ] :consistency (:eventual).
+ #
+ # @since 1.0.0
+ def initialize(seeds, options = {})
+ @cluster = Cluster.new(seeds, {})
+ @context = Context.new(self)
+ @options = options
+ @options[:consistency] ||= :eventual
end
- # Create a new session with +options+ reusing existing connections.
+ # Create a new session with +options+ and use new socket connections.
#
# @example Change safe mode
# session.with(safe: { w: 2 })[:people].insert(name: "Joe")
@@ -100,82 +127,107 @@ def use(database)
# end
# end
#
- # @yieldparam [Moped::Session] session the new session
- # @return [Moped::Session, Object] the new session, or the value returned
- # by the block if provided.
- def with(options = {})
- session = dup
- session.options.update options
-
- if block_given?
- yield session
- else
- session
- end
- end
-
- # Create a new session with +options+ and use new socket connections.
+ # @param [ Hash ] options The options.
+ #
+ # @return [ Session ] The new session.
#
# @see #with
- # @yieldparam [Moped::Session] session the new session
- # @return [Moped::Session] the new session
+ #
+ # @since 1.0.0
+ #
+ # @yieldparam [ Session ] session The new session.
def new(options = {})
session = with(options)
session.instance_variable_set(:@cluster, cluster.dup)
-
if block_given?
yield session
else
session
end
end
- # @method [](collection)
- # Return +collection+ from the current database.
+ # Is the session operating in safe mode?
#
- # @param (see Moped::Database#[])
- # @return (see Moped::Database#[])
- delegate :"[]" => :current_database
-
- # @method command(command)
- # Run +command+ on the current database.
+ # @example Is the session operating in safe mode?
+ # session.safe?
#
- # @param (see Moped::Database#command)
- # @return (see Moped::Database#command)
- delegate :command => :current_database
-
- # @method drop
- # Drop the current database.
+ # @return [ true, false ] Whether the current session requires safe
+ # operations.
#
- # @param (see Moped::Database#drop)
- # @return (see Moped::Database#drop)
- delegate :drop => :current_database
+ # @since 1.0.0
+ def safe?
+ !!safety
+ end
- # @method login(username, password)
- # Log in with +username+ and +password+ on the current database.
+ # Get the safety level for the session.
#
- # @param (see Moped::Database#login)
- # @raise (see Moped::Database#login)
- delegate :login => :current_database
-
- # @method logout
- # Log out from the current database.
+ # @example Get the safety level.
+ # session.safety
#
- # @param (see Moped::Database#logout)
- # @raise (see Moped::Database#login)
- delegate :logout => :current_database
-
- # @return [Boolean, Hash] the safety level for this session
+ # @return [ Boolean, Hash ] The safety level for this session.
+ #
+ # @since 1.0.0
def safety
safe = options[:safe]
-
case safe
- when false
- false
- when true
- { safe: true }
+ when false then false
+ when true then { safe: true }
+ else safe
+ end
+ end
+
+ # Switch the session's current database.
+ #
+ # @example Switch the current database.
+ # session.use :moped
+ # session[:people].find.one # => { :name => "John" }
+ #
+ # @param [ String, Symbol ] database The database to use.
+ #
+ # @since 1.0.0
+ def use(database)
+ options[:database] = database
+ set_current_database database
+ end
+
+ # Create a new session with +options+ reusing existing connections.
+ #
+ # @example Change safe mode
+ # session.with(safe: { w: 2 })[:people].insert(name: "Joe")
+ #
+ # @example Change safe mode with block
+ # session.with(safe: { w: 2 }) do |session|
+ # session[:people].insert(name: "Joe")
+ # end
+ #
+ # @example Temporarily change database
+ # session.with(database: "admin") do |admin|
+ # admin.command ismaster: 1
+ # end
+ #
+ # @example Copy between databases
+ # session.use "moped"
+ # session.with(database: "backup") do |backup|
+ # session[:people].each do |person|
+ # backup[:people].insert person
+ # end
+ # end
+ #
+ # @param [ Hash ] options The session options.
+ #
+ # @return [ Session, Object ] The new session, or the value returned
+ # by the block if provided.
+ #
+ # @since 1.0.0
+ #
+ # @yieldparam [ Session ] session The new session.
+ def with(options = {})
+ session = dup
+ session.options.update(options)
+ if block_given?
+ yield session
else
- safe
+ session
end
end
@@ -191,10 +243,6 @@ def current_database
end
end
- def set_current_database(database)
- @current_database = Database.new(self, database)
- end
-
def initialize_copy(_)
@context = Context.new(self)
@options = @options.dup
@@ -203,5 +251,9 @@ def initialize_copy(_)
remove_instance_variable :@current_database
end
end
+
+ def set_current_database(database)
+ @current_database = Database.new(self, database)
+ end
end
end

0 comments on commit 81f253f

Please sign in to comment.