Permalink
Browse files

Merge with docrails

  • Loading branch information...
lifo committed Nov 1, 2008
1 parent 5a02f0b commit b047929c14f088d535eea460ddd8769f43cd4ae5
Showing with 1,096 additions and 611 deletions.
  1. +3 −0 actionpack/lib/action_controller/base.rb
  2. +5 −5 actionpack/lib/action_view/helpers/text_helper.rb
  3. +103 −1 activesupport/lib/active_support/cache.rb
  4. +1 −0 activesupport/lib/active_support/cache/file_store.rb
  5. +33 −9 activesupport/lib/active_support/cache/mem_cache_store.rb
  6. +14 −0 activesupport/lib/active_support/cache/memory_store.rb
  7. +1 −0 activesupport/lib/active_support/cache/synchronized_memory_store.rb
  8. +44 −24 railties/doc/guides/html/2_2_release_notes.html
  9. +0 −1 railties/doc/guides/html/actioncontroller_basics.html
  10. +9 −1 railties/doc/guides/html/association_basics.html
  11. +343 −310 railties/doc/guides/html/finders.html
  12. +5 −0 railties/doc/guides/html/getting_started_with_rails.html
  13. +0 −16 railties/doc/guides/html/index.html
  14. +110 −48 railties/doc/guides/html/layouts_and_rendering.html
  15. +1 −1 railties/doc/guides/html/routing_outside_in.html
  16. +14 −0 railties/doc/guides/html/security.html
  17. +28 −24 railties/doc/guides/source/2_2_release_notes.txt
  18. +0 −2 railties/doc/guides/source/actioncontroller_basics/filters.txt
  19. +2 −2 railties/doc/guides/source/active_record_basics.txt
  20. +3 −1 railties/doc/guides/source/association_basics.txt
  21. +302 −143 railties/doc/guides/source/finders.txt
  22. +1 −0 railties/doc/guides/source/getting_started_with_rails.txt
  23. +0 −4 railties/doc/guides/source/index.txt
  24. +67 −18 railties/doc/guides/source/layouts_and_rendering.txt
  25. +1 −1 railties/doc/guides/source/routing_outside_in.txt
  26. +6 −0 railties/doc/guides/source/security.txt
@@ -1062,6 +1062,9 @@ def default_url_options(options = nil)
# When using <tt>redirect_to :back</tt>, if there is no referrer,
# RedirectBackError will be raised. You may specify some fallback
# behavior for this case by rescuing RedirectBackError.
+ #
+ # When using <tt>redirect_to</tt> an instance variable called
+ # @performed_redirect will be set to true.
def redirect_to(options = {}, response_status = {}) #:doc:
raise ActionControllerError.new("Cannot redirect to nil!") if options.nil?
@@ -344,9 +344,9 @@ def simple_format(text, html_options={})
text << "</p>"
end
- # Turns all URLs and e-mail addresses into clickable links. The +link+ parameter
+ # Turns all URLs and e-mail addresses into clickable links. The <tt>:link</tt> option
# will limit what should be linked. You can add HTML attributes to the links using
- # +href_options+. Options for +link+ are <tt>:all</tt> (default),
+ # <tt>:href_options</tt>. Possible values for <tt>:link</tt> are <tt>:all</tt> (default),
# <tt>:email_addresses</tt>, and <tt>:urls</tt>. If a block is given, each URL and
# e-mail address is yielded and the result is used as the link text.
#
@@ -355,15 +355,15 @@ def simple_format(text, html_options={})
# # => "Go to <a href=\"http://www.rubyonrails.org\">http://www.rubyonrails.org</a> and
# # say hello to <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>"
#
- # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :urls)
+ # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :urls)
# # => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a>
# # or e-mail david@loudthinking.com"
#
- # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :email_addresses)
+ # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :email_addresses)
# # => "Visit http://www.loudthinking.com/ or e-mail <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>"
#
# post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com."
- # auto_link(post_body, :all, :target => '_blank') do |text|
+ # auto_link(post_body, :href_options => { :target => '_blank' }) do |text|
# truncate(text, 15)
# end
# # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.m...</a>.
@@ -1,7 +1,33 @@
require 'benchmark'
module ActiveSupport
+ # See ActiveSupport::Cache::Store for documentation.
module Cache
+ # Creates a new CacheStore object according to the given options.
+ #
+ # If no arguments are passed to this method, then a new
+ # ActiveSupport::Cache::MemoryStore object will be returned.
+ #
+ # If you pass a Symbol as the first argument, then a corresponding cache
+ # store class under the ActiveSupport::Cache namespace will be created.
+ # For example:
+ #
+ # ActiveSupport::Cache.lookup_store(:memory_store)
+ # # => returns a new ActiveSupport::Cache::MemoryStore object
+ #
+ # ActiveSupport::Cache.lookup_store(:drb_store)
+ # # => returns a new ActiveSupport::Cache::DRbStore object
+ #
+ # Any additional arguments will be passed to the corresponding cache store
+ # class's constructor:
+ #
+ # ActiveSupport::Cache.lookup_store(:file_store, "/tmp/cache")
+ # # => same as: ActiveSupport::Cache::FileStore.new("/tmp/cache")
+ #
+ # If the first argument is not a Symbol, then it will simply be returned:
+ #
+ # ActiveSupport::Cache.lookup_store(MyOwnCacheStore.new)
+ # # => returns MyOwnCacheStore.new
def self.lookup_store(*store_option)
store, *parameters = *([ store_option ].flatten)
@@ -36,6 +62,21 @@ def self.expand_cache_key(key, namespace = nil)
expanded_cache_key
end
+ # An abstract cache store class. There are multiple cache store
+ # implementations, each having its own additional features. See the classes
+ # under the ActiveSupport::Cache module, e.g.
+ # ActiveSupport::Cache::MemCacheStore. MemCacheStore is currently the most
+ # popular cache store for large production websites.
+ #
+ # ActiveSupport::Cache::Store is meant for caching strings. Some cache
+ # store implementations, like MemoryStore, are able to cache arbitrary
+ # Ruby objects, but don't count on every cache store to be able to do that.
+ #
+ # cache = ActiveSupport::Cache::MemoryStore.new
+ #
+ # cache.read("city") # => nil
+ # cache.write("city", "Duckburgh")
+ # cache.read("city") # => "Duckburgh"
class Store
cattr_accessor :logger
@@ -44,7 +85,46 @@ def silence!
self
end
- # Pass <tt>:force => true</tt> to force a cache miss.
+ # Fetches data from the cache, using the given key. If there is data in
+ # the cache with the given key, then that data is returned.
+ #
+ # If there is no such data in the cache (a cache miss occurred), then
+ # then nil will be returned. However, if a block has been passed, then
+ # that block will be run in the event of a cache miss. The return value
+ # of the block will be written to the cache under the given cache key,
+ # and that return value will be returned.
+ #
+ # cache.write("today", "Monday")
+ # cache.fetch("today") # => "Monday"
+ #
+ # cache.fetch("city") # => nil
+ # cache.fetch("city") do
+ # "Duckburgh"
+ # end
+ # cache.fetch("city") # => "Duckburgh"
+ #
+ # You may also specify additional options via the +options+ argument.
+ # Setting <tt>:force => true</tt> will force a cache miss:
+ #
+ # cache.write("today", "Monday")
+ # cache.fetch("today", :force => true) # => nil
+ #
+ # Other options will be handled by the specific cache store implementation.
+ # Internally, #fetch calls #read, and calls #write on a cache miss.
+ # +options+ will be passed to the #read and #write calls.
+ #
+ # For example, MemCacheStore's #write method supports the +:expires_in+
+ # option, which tells the memcached server to automatically expire the
+ # cache item after a certain period. We can use this option with #fetch
+ # too:
+ #
+ # cache = ActiveSupport::Cache::MemCacheStore.new
+ # cache.fetch("foo", :force => true, :expires_in => 5.seconds) do
+ # "bar"
+ # end
+ # cache.fetch("foo") # => "bar"
+ # sleep(6)
+ # cache.fetch("foo") # => nil
def fetch(key, options = {})
@logger_off = true
if !options[:force] && value = read(key, options)
@@ -68,10 +148,32 @@ def fetch(key, options = {})
end
end
+ # Fetches data from the cache, using the given key. If there is data in
+ # the cache with the given key, then that data is returned. Otherwise,
+ # nil is returned.
+ #
+ # You may also specify additional options via the +options+ argument.
+ # The specific cache store implementation will decide what to do with
+ # +options+.
def read(key, options = nil)
log("read", key, options)
end
+ # Writes the given value to the cache, with the given key.
+ #
+ # You may also specify additional options via the +options+ argument.
+ # The specific cache store implementation will decide what to do with
+ # +options+.
+ #
+ # For example, MemCacheStore supports the +:expires_in+ option, which
+ # tells the memcached server to automatically expire the cache item after
+ # a certain period:
+ #
+ # cache = ActiveSupport::Cache::MemCacheStore.new
+ # cache.write("foo", "bar", :expires_in => 5.seconds)
+ # cache.read("foo") # => "bar"
+ # sleep(6)
+ # cache.read("foo") # => nil
def write(key, value, options = nil)
log("write", key, options)
end
@@ -1,5 +1,6 @@
module ActiveSupport
module Cache
+ # A cache store implementation which stores everything on the filesystem.
class FileStore < Store
attr_reader :cache_path
@@ -2,8 +2,19 @@
module ActiveSupport
module Cache
+ # A cache store implementation which stores data in Memcached:
+ # http://www.danga.com/memcached/
+ #
+ # This is currently the most popular cache store for production websites.
+ #
+ # Special features:
+ # - Clustering and load balancing. One can specify multiple memcached servers,
+ # and MemCacheStore will load balance between all available servers. If a
+ # server goes down, then MemCacheStore will ignore it until it goes back
+ # online.
+ # - Time-based expiry support. See #write and the +:expires_in+ option.
class MemCacheStore < Store
- module Response
+ module Response # :nodoc:
STORED = "STORED\r\n"
NOT_STORED = "NOT_STORED\r\n"
EXISTS = "EXISTS\r\n"
@@ -13,6 +24,14 @@ module Response
attr_reader :addresses
+ # Creates a new MemCacheStore object, with the given memcached server
+ # addresses. Each address is either a host name, or a host-with-port string
+ # in the form of "host_name:port". For example:
+ #
+ # ActiveSupport::Cache::MemCacheStore.new("localhost", "server-downstairs.localnetwork:8229")
+ #
+ # If no addresses are specified, then MemCacheStore will connect to
+ # localhost port 11211 (the default memcached port).
def initialize(*addresses)
addresses = addresses.flatten
options = addresses.extract_options!
@@ -21,16 +40,21 @@ def initialize(*addresses)
@data = MemCache.new(addresses, options)
end
- def read(key, options = nil)
+ def read(key, options = nil) # :nodoc:
super
@data.get(key, raw?(options))
rescue MemCache::MemCacheError => e
logger.error("MemCacheError (#{e}): #{e.message}")
nil
end
- # Set key = value. Pass :unless_exist => true if you don't
- # want to update the cache if the key is already set.
+ # Writes a value to the cache.
+ #
+ # Possible options:
+ # - +:unless_exist+ - set to true if you don't want to update the cache
+ # if the key is already set.
+ # - +:expires_in+ - the number of seconds that this value may stay in
+ # the cache. See ActiveSupport::Cache::Store#write for an example.
def write(key, value, options = nil)
super
method = options && options[:unless_exist] ? :add : :set
@@ -44,7 +68,7 @@ def write(key, value, options = nil)
false
end
- def delete(key, options = nil)
+ def delete(key, options = nil) # :nodoc:
super
response = @data.delete(key, expires_in(options))
response == Response::DELETED
@@ -53,13 +77,13 @@ def delete(key, options = nil)
false
end
- def exist?(key, options = nil)
+ def exist?(key, options = nil) # :nodoc:
# Doesn't call super, cause exist? in memcache is in fact a read
# But who cares? Reading is very fast anyway
!read(key, options).nil?
end
- def increment(key, amount = 1)
+ def increment(key, amount = 1) # :nodoc:
log("incrementing", key, amount)
response = @data.incr(key, amount)
@@ -68,7 +92,7 @@ def increment(key, amount = 1)
nil
end
- def decrement(key, amount = 1)
+ def decrement(key, amount = 1) # :nodoc:
log("decrement", key, amount)
response = @data.decr(key, amount)
@@ -77,7 +101,7 @@ def decrement(key, amount = 1)
nil
end
- def delete_matched(matcher, options = nil)
+ def delete_matched(matcher, options = nil) # :nodoc:
super
raise "Not supported by Memcache"
end
@@ -1,5 +1,19 @@
module ActiveSupport
module Cache
+ # A cache store implementation which stores everything into memory in the
+ # same process. If you're running multiple Ruby on Rails server processes
+ # (which is the case if you're using mongrel_cluster or Phusion Passenger),
+ # then this means that your Rails server process instances won't be able
+ # to share cache data with each other. If your application never performs
+ # manual cache item expiry (e.g. when you're using generational cache keys),
+ # then using MemoryStore is ok. Otherwise, consider carefully whether you
+ # should be using this cache store.
+ #
+ # MemoryStore is not only able to store strings, but also arbitrary Ruby
+ # objects.
+ #
+ # MemoryStore is not thread-safe. Use SynchronizedMemoryStore instead
+ # if you need thread-safety.
class MemoryStore < Store
def initialize
@data = {}
@@ -1,5 +1,6 @@
module ActiveSupport
module Cache
+ # Like MemoryStore, but thread-safe.
class SynchronizedMemoryStore < MemoryStore
def initialize
super
Oops, something went wrong.

0 comments on commit b047929

Please sign in to comment.