diff options
Diffstat (limited to 'activesupport/lib/active_support')
4 files changed, 78 insertions, 39 deletions
diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb index 1445cec446..037cfffae2 100644 --- a/activesupport/lib/active_support/cache.rb +++ b/activesupport/lib/active_support/cache.rb @@ -129,13 +129,6 @@ module ActiveSupport # cache.namespace = lambda { @last_mod_time } # Set the namespace to a variable # @last_mod_time = Time.now # Invalidate the entire cache by changing namespace # - # All caches support auto expiring content after a specified number of seconds. - # To set the cache entry time to live, you can either specify +:expires_in+ as - # an option to the constructor to have it affect all entries or to the +fetch+ - # or +write+ methods for just one entry. - # - # cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes) - # cache.write(key, value, :expire_in => 1.minute) # Set a lower value for one entry # # Caches can also store values in a compressed format to save space and reduce # time spent sending data. Since there is some overhead, values must be large @@ -211,23 +204,30 @@ module ActiveSupport # Setting <tt>:compress</tt> will store a large cache entry set by the call # in a compressed format. # - # Setting <tt>:expires_in</tt> will set an expiration time on the cache - # entry if it is set by call. # - # Setting <tt>:race_condition_ttl</tt> will invoke logic on entries set with - # an <tt>:expires_in</tt> option. If an entry is found in the cache that is - # expired and it has been expired for less than the number of seconds specified - # by this option and a block was passed to the method call, then the expiration - # future time of the entry in the cache will be updated to that many seconds - # in the and the block will be evaluated and written to the cache. + # Setting <tt>:expires_in</tt> will set an expiration time on the cache. All caches + # support auto expiring content after a specified number of seconds. This value can + # be specified as an option to the construction in which call all entries will be + # affected. Or it can be supplied to the +fetch+ or +write+ method for just one entry. + # + # cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes) + # cache.write(key, value, :expire_in => 1.minute) # Set a lower value for one entry + # + # Setting <tt>:race_condition_ttl</tt> is very useful in situations where a cache entry + # is used very frequently unver heavy load. If a cache expires and due to heavy load + # seven different processes will try to read data natively and then they all will try to + # write to cache. To avoid that case the first process to find an expired cache entry will + # bump the cache expiration time by the value set in <tt>:race_condition_ttl</tt>. Yes + # this process is extending the time for a stale value by another few seconds. Because + # of extended life of the previous cache, other processes will continue to use slightly + # stale data for a just a big longer. In the meantime that first process will go ahead + # and will write into cache the new value. After that all the processes will start + # getting new value. The key is to keep <tt>:race_condition_ttl</tt> small. # - # This is very useful in situations where a cache entry is used very frequently - # under heavy load. The first process to find an expired cache entry will then - # become responsible for regenerating that entry while other processes continue - # to use the slightly out of date entry. This can prevent race conditions where - # too many processes are trying to regenerate the entry all at once. If the - # process regenerating the entry errors out, the entry will be regenerated - # after the specified number of seconds. + # If the process regenerating the entry errors out, the entry will be regenerated + # after the specified number of seconds. Also note that the life of stale cache is + # extended only if it expired recently. Otherwise a new value is generated and + # <tt>:race_condition_ttl</tt> does not play any role. # # # Set all values to expire after one minute. # cache = ActiveSupport::Cache::MemoryCache.new(:expires_in => 1.minute) @@ -252,6 +252,7 @@ module ActiveSupport # # # val_1 => "new value 1" # # val_2 => "original value" + # # sleep 10 # First thread extend the life of cache by another 10 seconds # # cache.fetch("foo") => "new value 1" # # Other options will be handled by the specific cache store implementation. diff --git a/activesupport/lib/active_support/core_ext/class/attribute.rb b/activesupport/lib/active_support/core_ext/class/attribute.rb index 576366e496..bfa57fe1f7 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute.rb @@ -2,8 +2,8 @@ require 'active_support/core_ext/kernel/singleton_class' require 'active_support/core_ext/module/remove_method' class Class - # Declare a class-level attribute whose value is inheritable and - # overwritable by subclasses: + # Declare a class-level attribute whose value is inheritable by subclasses. + # Subclasses can change their own value and it will not impact parent class. # # class Base # class_attribute :setting @@ -18,12 +18,34 @@ class Class # Subclass.setting # => false # Base.setting # => true # + # In the above case as long as Subclass does not assign a value to setting + # by performing <tt>Subclass.setting = _something_ </tt>, <tt>Subclass.setting</tt> + # would read value assigned to parent class. Once Subclass assigns a value then + # the value assigned by Subclass would be returned. + # # This matches normal Ruby method inheritance: think of writing an attribute - # on a subclass as overriding the reader method. + # on a subclass as overriding the reader method. However, you need to be aware + # when using +class_attribute+ with mutable structures as +Array+ or +Hash+. + # In such cases, you don't want to do changes in places but use setters: + # + # Base.setting = [] + # Base.setting #=> [] + # Subclass.setting #=> [] + # + # # Appending in child changes both parent and child because it is the same object: + # Subclass.setting << :foo + # Base.setting #=> [:foo] + # Subclass.setting #=> [:foo] + # + # # Use setters to not propagate changes: + # Base.setting = [] + # Subclass.setting += [:foo] + # Base.setting #=> [] + # Subclass.setting #=> [:foo] # # For convenience, a query method is defined as well: # - # Subclass.setting? # => false + # Subclass.setting? # => false # # Instances may overwrite the class value in the same way: # diff --git a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb index feef5d2d57..4e35b1b488 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb @@ -3,11 +3,27 @@ require 'active_support/core_ext/array/extract_options' # Extends the class object with class and instance accessors for class attributes, # just like the native attr* accessors for instance attributes. # +# Note that unlike +class_attribute+, if a subclass changes the value then that would +# also change the value for parent class. Similarly if parent class changes the value +# then that would change the value of subclasses too. +# # class Person # cattr_accessor :hair_colors # end # # Person.hair_colors = [:brown, :black, :blonde, :red] +# Person.hair_colors #=> [:brown, :black, :blonde, :red] +# Person.new.hair_colors #=> [:brown, :black, :blonde, :red] +# +# To opt out of the instance writer method, pass :instance_writer => false. +# To opt out of the instance reader method, pass :instance_reader => false. +# +# class Person +# cattr_accessor :hair_colors, :instance_writer => false, :instance_reader => false +# end +# +# Person.new.hair_colors = [:brown] # => NoMethodError +# Person.new.hair_colors # => NoMethodError class Class def cattr_reader(*syms) options = syms.extract_options! diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb index e6a213625c..c5b54318ce 100644 --- a/activesupport/lib/active_support/core_ext/date/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date/calculations.rb @@ -40,23 +40,23 @@ class Date end end - # Tells whether the Date object's date lies in the past + # Returns true if the Date object's date lies in the past. Otherwise returns false. def past? self < ::Date.current end - # Tells whether the Date object's date is today + # Returns true if the Date object's date is today. def today? self.to_date == ::Date.current # we need the to_date because of DateTime end - # Tells whether the Date object's date lies in the future + # Returns true if the Date object's date lies in the future. def future? self > ::Date.current end # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00) - # and then subtracts the specified number of seconds + # and then subtracts the specified number of seconds. def ago(seconds) to_time_in_current_zone.since(-seconds) end @@ -127,22 +127,22 @@ class Date ) end - # Returns a new Date/DateTime representing the time a number of specified months ago + # Returns a new Date/DateTime representing the time a number of specified months ago. def months_ago(months) advance(:months => -months) end - # Returns a new Date/DateTime representing the time a number of specified months in the future + # Returns a new Date/DateTime representing the time a number of specified months in the future. def months_since(months) advance(:months => months) end - # Returns a new Date/DateTime representing the time a number of specified years ago + # Returns a new Date/DateTime representing the time a number of specified years ago. def years_ago(years) advance(:years => -years) end - # Returns a new Date/DateTime representing the time a number of specified years in the future + # Returns a new Date/DateTime representing the time a number of specified years in the future. def years_since(years) advance(:years => years) end @@ -152,22 +152,22 @@ class Date years_ago(1) end unless method_defined?(:prev_year) - # Short-hand for years_since(1) + # Shorthand for years_since(1) def next_year years_since(1) end unless method_defined?(:next_year) - # Short-hand for months_ago(1) + # Shorthand for months_ago(1) def prev_month months_ago(1) end unless method_defined?(:prev_month) - # Short-hand for months_since(1) + # Shorthand for months_since(1) def next_month months_since(1) end unless method_defined?(:next_month) - # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00) + # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00). def beginning_of_week days_to_monday = self.wday!=0 ? self.wday-1 : 6 result = self - days_to_monday @@ -176,7 +176,7 @@ class Date alias :monday :beginning_of_week alias :at_beginning_of_week :beginning_of_week - # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59) + # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59). def end_of_week days_to_sunday = self.wday!=0 ? 7-self.wday : 0 result = self + days_to_sunday.days |