activerecord 8.0.2.1 → 8.1.0.beta1

data/lib/active_record/associations.rb

@@ -39,6 +39,8 @@ module ActiveRecord
       autoload :AssociationScope
       autoload :DisableJoinsAssociationScope
       autoload :AliasTracker
+
+      autoload :Deprecation
     end
 
     def self.eager_load!
@@ -79,7 +81,7 @@ module ActiveRecord
 
       # Returns the specified association instance if it exists, +nil+ otherwise.
       def association_instance_get(name)
-        @association_cache[name]
+        (@association_cache ||= {})[name]
       end
 
       # Set the specified association instance.
@@ -87,6 +89,14 @@ module ActiveRecord
         @association_cache[name] = association
       end
 
+      def deprecated_associations_api_guard(association, method_name)
+        Deprecation.guard(association.reflection) { "the method #{method_name} was invoked" }
+      end
+
+      def report_deprecated_association(reflection, context:)
+        Deprecation.report(reflection, context: context)
+      end
+
       # = Active Record \Associations
       #
       # \Associations are a set of macro-like class methods for tying objects together through
@@ -1020,6 +1030,116 @@ module ActiveRecord
       # associated records themselves, you can always do something along the lines of
       # <tt>person.tasks.each(&:destroy)</tt>.
       #
+      # == Deprecated Associations
+      #
+      # Associations can be marked as deprecated by passing <tt>deprecated: true</tt>:
+      #
+      #     has_many :posts, deprecated: true
+      #
+      # When a deprecated association is used, a warning is issued using the
+      # Active Record logger, though more options are available via
+      # configuration.
+      #
+      # The message includes some context that helps understand the deprecated
+      # usage:
+      #
+      #     The association Author#posts is deprecated, the method post_ids was invoked (...)
+      #     The association Author#posts is deprecated, referenced in query to preload records (...)
+      #
+      # The dots in the examples above would have the application-level spot
+      # where usage occurred, to help locate what triggered the warning. That
+      # location is computed using the Active Record backtrace cleaner.
+      #
+      # === What is considered to be usage?
+      #
+      # * Invocation of any association methods like +posts+, <tt>posts=</tt>,
+      #   etc.
+      #
+      # * If the association accepts nested attributes, assignment to those
+      #   attributes.
+      #
+      # * If the association is a through association and some of its nested
+      #   associations are deprecated, you'll get warnings for them whenever the
+      #   top-level through is used. This is so regardless of whether the
+      #   through itself is deprecated.
+      #
+      # * Execution of queries that refer to the association. Think execution of
+      #   <tt>eager_load(:posts)</tt>, <tt>joins(author: :posts)</tt>, etc.
+      #
+      # * If the association has a +:dependent+ option, destroying the
+      #   associated record issues warnings (because that has a side-effect that
+      #   would not happen if the association was removed).
+      #
+      # * If the association has a +:touch+ option, saving or destroying the
+      #   record issues a warning (because that has a side-effect that would not
+      #   happen if the association was removed).
+      #
+      # === Things that do NOT issue warnings
+      #
+      # The rationale behind most of the following edge cases is that Active
+      # Record accesses associations lazily, when used. Before that, the
+      # reference to the association is basically just a Ruby symbol.
+      #
+      # * If +posts+ is deprecated, <tt>has_many :comments, through: :posts</tt>
+      #   does not warn. Usage of the +comments+ association reports usage of
+      #   +posts+, as we explained above, but the definition of the +has_many+
+      #   itself does not.
+      #
+      # * Similarly, <tt>accepts_nested_attributes_for :posts</tt> does not
+      #   warn. Assignment to the posts attributes warns, as explained above,
+      #   but the +accepts_nested_attributes_for+ call itself does not.
+      #
+      # * Same if an association declares to be inverse of a deprecated one, the
+      #   macro itself does not warn.
+      #
+      # * In the same line, the declaration <tt>validates_associated :posts</tt>
+      #   does not warn by itself, though access is reported when the validation
+      #   runs.
+      #
+      # * Relation query methods like <tt>Author.includes(:posts)</tt> do not
+      #   warn by themselves. At that point, that is a relation that internally
+      #   stores a symbol for later use. As explained in the previous section,
+      #   you get a warning when/if the query is executed.
+      #
+      # * Access to the reflection object of the association as in
+      #   <tt>Author.reflect_on_association(:posts)</tt> or
+      #   <tt>Author.reflect_on_all_associations</tt> does not warn.
+      #
+      # === Configuration
+      #
+      # Reporting deprecated usage can be configured:
+      #
+      #     config.active_record.deprecated_associations_options = { ... }
+      #
+      # If present, this has to be a hash with keys +:mode+ and/or +:backtrace+.
+      #
+      # ==== Mode
+      #
+      # * In +:warn+ mode, usage issues a warning that includes the
+      #   application-level place where the access happened, if any. This is the
+      #   default mode.
+      #
+      # * In +:raise+ mode, usage raises an
+      #   ActiveRecord::DeprecatedAssociationError with a similar message and a
+      #   clean backtrace in the exception object.
+      #
+      # * In +:notify+ mode, a <tt>deprecated_association.active_record</tt>
+      #   Active Support notification is published. The event payload has the
+      #   association reflection (+:reflection+), the application-level location
+      #   (+:location+) where the access happened (a Thread::Backtrace::Location
+      #   object, or +nil+), and a deprecation message (+:message+).
+      #
+      # ==== Backtrace
+      #
+      # If +:backtrace+ is true, warnings include a clean backtrace in the message
+      # and notifications have a +:backtrace+ key in the payload with an array
+      # of clean Thread::Backtrace::Location objects. Exceptions always get a
+      # clean stack trace set.
+      #
+      # Clean backtraces are computed using the Active Record backtrace cleaner.
+      # In Rails applications, that is by the default the same as
+      # <tt>Rails.backtrace_cleaner</tt>.
+      #
       # == Type safety with ActiveRecord::AssociationTypeMismatch
       #
       # If you attempt to assign an object to an association that doesn't match the inferred
@@ -1208,8 +1328,10 @@ module ActiveRecord
         # [+:as+]
         #   Specifies a polymorphic interface (See #belongs_to).
         # [+:through+]
-        #   Specifies an association through which to perform the query. This can be any other type
-        #   of association, including other <tt>:through</tt> associations. Options for <tt>:class_name</tt>,
+        #   Specifies an association through which to perform the query.
+        #
+        #   This can be any other type of association, including other <tt>:through</tt> associations,
+        #   but it cannot be a polymorphic association. Options for <tt>:class_name</tt>,
         #   <tt>:primary_key</tt> and <tt>:foreign_key</tt> are ignored, as the association uses the
         #   source reflection.
         #
@@ -1285,6 +1407,9 @@ module ActiveRecord
         #   Defines an {association callback}[rdoc-ref:Associations::ClassMethods@Association+callbacks] that gets triggered <b>before an object is removed</b> from the association collection.
         # [:after_remove]
         #   Defines an {association callback}[rdoc-ref:Associations::ClassMethods@Association+callbacks] that gets triggered <b>after an object is removed</b> from the association collection.
+        # [+:deprecated+]
+        #   If true, marks the association as deprecated. Usage of deprecated associations is reported.
+        #   Please, check the class documentation above for details.
         #
         # Option examples:
         #   has_many :comments, -> { order("posted_on") }
@@ -1301,7 +1426,7 @@ module ActiveRecord
         #   has_many :comments, index_errors: :nested_attributes_order
         def has_many(name, scope = nil, **options, &extension)
           reflection = Builder::HasMany.build(self, name, scope, options, &extension)
-          Reflection.add_reflection self, name, reflection
+          Reflection.add_reflection(self, name, reflection)
         end
 
         # Specifies a one-to-one association with another class. This method
@@ -1411,10 +1536,12 @@ module ActiveRecord
         # [+:as+]
         #   Specifies a polymorphic interface (See #belongs_to).
         # [+:through+]
-        #   Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt>,
-        #   <tt>:primary_key</tt>, and <tt>:foreign_key</tt> are ignored, as the association uses the
-        #   source reflection. You can only use a <tt>:through</tt> query through a #has_one
-        #   or #belongs_to association on the join model.
+        #   Specifies an association through which to perform the query.
+        #
+        #   The through association must be a +has_one+, <tt>has_one :through</tt>, or non-polymorphic +belongs_to+.
+        #   That is, a non-polymorphic singular association. Options for <tt>:class_name</tt>, <tt>:primary_key</tt>,
+        #   and <tt>:foreign_key</tt> are ignored, as the association uses the source reflection. You can only
+        #   use a <tt>:through</tt> query through a #has_one or #belongs_to association on the join model.
         #
         #   If the association on the join model is a #belongs_to, the collection can be modified
         #   and the records on the <tt>:through</tt> model will be automatically created and removed
@@ -1480,12 +1607,15 @@ module ActiveRecord
         #   Serves as a composite foreign key. Defines the list of columns to be used to query the associated object.
         #   This is an optional option. By default Rails will attempt to derive the value automatically.
         #   When the value is set the Array size must match associated model's primary key or +query_constraints+ size.
+        # [+:deprecated+]
+        #   If true, marks the association as deprecated. Usage of deprecated associations is reported.
+        #   Please, check the class documentation above for details.
         #
         # Option examples:
         #   has_one :credit_card, dependent: :destroy  # destroys the associated credit card
         #   has_one :credit_card, dependent: :nullify  # updates the associated records foreign
         #                                                 # key value to NULL rather than destroying it
-        #   has_one :last_comment, -> { order('posted_on') }, class_name: "Comment"
+        #   has_one :last_comment, -> { order('posted_on desc') }, class_name: "Comment"
         #   has_one :project_manager, -> { where(role: 'project_manager') }, class_name: "Person"
         #   has_one :attachment, as: :attachable
         #   has_one :boss, -> { readonly }
@@ -1497,7 +1627,7 @@ module ActiveRecord
         #   has_one :employment_record_book, query_constraints: [:organization_id, :employee_id]
         def has_one(name, scope = nil, **options)
           reflection = Builder::HasOne.build(self, name, scope, options)
-          Reflection.add_reflection self, name, reflection
+          Reflection.add_reflection(self, name, reflection)
         end
 
         # Specifies a one-to-one association with another class. This method
@@ -1576,7 +1706,9 @@ module ActiveRecord
         # [+:class_name+]
         #   Specify the class name of the association. Use it only if that name can't be inferred
         #   from the association name. So <tt>belongs_to :author</tt> will by default be linked to the Author class, but
-        #   if the real class name is Person, you'll have to specify it with this option.
+        #   if the real class name is Person, you'll have to specify it with this option. +:class_name+
+        #   is not supported in polymorphic associations, since in that case the class name of the
+        #   associated record is stored in the type column.
         # [+:foreign_key+]
         #   Specify the foreign key used for the association. By default this is guessed to be the name
         #   of the association with an "_id" suffix. So a class that defines a <tt>belongs_to :person</tt>
@@ -1670,6 +1802,9 @@ module ActiveRecord
         #   Serves as a composite foreign key. Defines the list of columns to be used to query the associated object.
         #   This is an optional option. By default Rails will attempt to derive the value automatically.
         #   When the value is set the Array size must match associated model's primary key or +query_constraints+ size.
+        # [+:deprecated+]
+        #   If true, marks the association as deprecated. Usage of deprecated associations is reported.
+        #   Please, check the class documentation above for details.
         #
         # Option examples:
         #   belongs_to :firm, foreign_key: "client_of"
@@ -1688,7 +1823,7 @@ module ActiveRecord
         #   belongs_to :note, query_constraints: [:organization_id, :note_id]
         def belongs_to(name, scope = nil, **options)
           reflection = Builder::BelongsTo.build(self, name, scope, options)
-          Reflection.add_reflection self, name, reflection
+          Reflection.add_reflection(self, name, reflection)
         end
 
         # Specifies a many-to-many relationship with another class. This associates two classes via an
@@ -1708,7 +1843,7 @@ module ActiveRecord
         # The join table should not have a primary key or a model associated with it. You must manually generate the
         # join table with a migration such as this:
         #
-        #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[8.0]
+        #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[8.1]
         #     def change
         #       create_join_table :developers, :projects
         #     end
@@ -1859,6 +1994,9 @@ module ActiveRecord
         #   <tt>:autosave</tt> to <tt>true</tt>.
         # [+:strict_loading+]
         #   Enforces strict loading every time an associated record is loaded through this association.
+        # [+:deprecated+]
+        #   If true, marks the association as deprecated. Usage of deprecated associations is reported.
+        #   Please, check the class documentation above for details.
         #
         # Option examples:
         #   has_and_belongs_to_many :projects
@@ -1870,17 +2008,17 @@ module ActiveRecord
         def has_and_belongs_to_many(name, scope = nil, **options, &extension)
           habtm_reflection = ActiveRecord::Reflection::HasAndBelongsToManyReflection.new(name, scope, options, self)
 
-          builder = Builder::HasAndBelongsToMany.new name, self, options
+          builder = Builder::HasAndBelongsToMany.new(name, self, options)
 
           join_model = builder.through_model
 
-          const_set join_model.name, join_model
-          private_constant join_model.name
+          const_set(join_model.name, join_model)
+          private_constant(join_model.name)
 
-          middle_reflection = builder.middle_reflection join_model
+          middle_reflection = builder.middle_reflection(join_model)
 
-          Builder::HasMany.define_callbacks self, middle_reflection
-          Reflection.add_reflection self, middle_reflection.name, middle_reflection
+          Builder::HasMany.define_callbacks(self, middle_reflection)
+          Reflection.add_reflection(self, middle_reflection.name, middle_reflection)
           middle_reflection.parent_reflection = habtm_reflection
 
           include Module.new {
@@ -1897,8 +2035,8 @@ module ActiveRecord
           hm_options[:through] = middle_reflection.name
           hm_options[:source] = join_model.right_reflection.name
 
-          [:before_add, :after_add, :before_remove, :after_remove, :autosave, :validate, :join_table, :class_name, :extend, :strict_loading].each do |k|
-            hm_options[k] = options[k] if options.key? k
+          [:before_add, :after_add, :before_remove, :after_remove, :autosave, :validate, :join_table, :class_name, :extend, :strict_loading, :deprecated].each do |k|
+            hm_options[k] = options[k] if options.key?(k)
           end
 
           has_many name, scope, **hm_options, &extension

data/lib/active_record/attribute_methods/query.rb

@@ -3,6 +3,38 @@
 module ActiveRecord
   module AttributeMethods
     # = Active Record Attribute Methods \Query
+    #
+    # Adds query methods for attributes that return either +true+ or +false+
+    # depending on the attribute type and value.
+    #
+    # For Boolean attributes this will return +true+ if the value is present
+    # and return +false+ otherwise:
+    #
+    #   class Product < ActiveRecord::Base
+    #   end
+    #
+    #   product = Product.new(archived: false)
+    #   product.archived? # => false
+    #   product.archived = true
+    #   product.archived? # => true
+    #
+    # For Numeric attributes this will return +true+ if the value is a non-zero
+    # number and return +false+ otherwise:
+    #
+    #   product.inventory_count = 0
+    #   product.inventory_count? # => false
+    #   product.inventory_count = 1
+    #   product.inventory_count? # => true
+    #
+    # For other attributes it will return +true+ if the value is present
+    # and return +false+ otherwise:
+    #
+    #   product.name = nil
+    #   product.name? # => false
+    #   product.name = " "
+    #   product.name? # => false
+    #   product.name = "Orange"
+    #   product.name? # => true
     module Query
       extend ActiveSupport::Concern
 
@@ -10,6 +42,8 @@ module ActiveRecord
         attribute_method_suffix "?", parameters: false
       end
 
+      # Returns +true+ or +false+ for the attribute identified by +attr_name+,
+      # depending on the attribute type and value.
       def query_attribute(attr_name)
         value = self.public_send(attr_name)
 

data/lib/active_record/attribute_methods/serialization.rb

@@ -51,6 +51,16 @@ module ActiveRecord
         #     ActiveRecord::SerializationTypeMismatch error.
         #   * If the column is +NULL+ or starting from a new record, the default value
         #     will set to +type.new+
+        # * +comparable+ - Specify whether the deserialized object is safely comparable
+        #   for the purpose of detecting changes. Defaults to +false+
+        #   When set to +false+ the old and new values will be compared by their serialized
+        #   representation (e.g. JSON or YAML), which can sometimes cause two objects that are
+        #   semantically equal to be considered different.
+        #   For instance two hashes with the same keys and values but a different order have a
+        #   different serialized representation, but are semantically equal once deserialized.
+        #   If set to +true+ the comparison will be done on the deserialized object.
+        #   This options should only be enabled if the +type+ is known to have
+        #   a proper <tt>==</tt> method that deeply compare the objects.
         # * +yaml+ - Optional. Yaml specific options. The allowed config is:
         #   * +:permitted_classes+ - +Array+ with the permitted classes.
         #   * +:unsafe_load+ - Unsafely load YAML blobs, allow YAML to load any class.
@@ -130,7 +140,7 @@ module ActiveRecord
         # silently cast unsupported types to +String+:
         #
         #   >> JSON.parse(JSON.dump(Struct.new(:foo)))
-        #   => "#<Class:0x000000013090b4c0>"
+        #   # => "#<Class:0x000000013090b4c0>"
         #
         # ==== Examples
         #
@@ -180,7 +190,7 @@ module ActiveRecord
         #     serialize :preferences, coder: Rot13JSON
         #   end
         #
-        def serialize(attr_name, coder: nil, type: Object, yaml: {}, **options)
+        def serialize(attr_name, coder: nil, type: Object, comparable: false, yaml: {}, **options)
           coder ||= default_column_serializer
           unless coder
             raise ArgumentError, <<~MSG.squish
@@ -200,7 +210,7 @@ module ActiveRecord
             end
 
             cast_type = cast_type.subtype if Type::Serialized === cast_type
-            Type::Serialized.new(cast_type, column_serializer)
+            Type::Serialized.new(cast_type, column_serializer, comparable: comparable)
           end
         end
 
@@ -209,7 +219,10 @@ module ActiveRecord
             # When ::JSON is used, force it to go through the Active Support JSON encoder
             # to ensure special objects (e.g. Active Record models) are dumped correctly
             # using the #as_json hook.
-            coder = Coders::JSON if coder == ::JSON
+
+            if coder == ::JSON || coder == Coders::JSON
+              coder = Coders::JSON.new
+            end
 
             if coder == ::YAML || coder == Coders::YAMLColumn
               Coders::YAMLColumn.new(attr_name, type, **(yaml || {}))

data/lib/active_record/attributes.rb

@@ -7,6 +7,7 @@ module ActiveRecord
   module Attributes
     extend ActiveSupport::Concern
     include ActiveModel::AttributeRegistration
+    include ActiveModel::Attributes::Normalization
 
     # = Active Record \Attributes
     module ClassMethods
@@ -21,28 +22,34 @@ module ActiveRecord
       # your domain objects across much of Active Record, without having to
       # rely on implementation details or monkey patching.
       #
-      # +name+ The name of the methods to define attribute methods for, and the
-      # column which this will persist to.
+      # ==== Parameters
       #
-      # +cast_type+ A symbol such as +:string+ or +:integer+, or a type object
-      # to be used for this attribute. If this parameter is not passed, the previously
-      # defined type (if any) will be used.
-      # Otherwise, the type will be ActiveModel::Type::Value.
-      # See the examples below for more information about providing custom type objects.
+      # [+name+]
+      #   The name of the methods to define attribute methods for, and the
+      #   column which this will persist to.
       #
-      # ==== Options
+      # [+cast_type+]
+      #   A symbol such as +:string+ or +:integer+, or a type object to be used
+      #   for this attribute. If this parameter is not passed, the previously
+      #   defined type (if any) will be used. Otherwise, the type will be
+      #   ActiveModel::Type::Value. See the examples below for more information
+      #   about providing custom type objects.
       #
-      # The following options are accepted:
+      # ==== Options
       #
-      # +default+ The default value to use when no value is provided. If this option
-      # is not passed, the previously defined default value (if any) on the superclass or in the schema will be used.
-      # Otherwise, the default will be +nil+.
+      # [+:default+]
+      #   The default value to use when no value is provided. If this option is
+      #   not passed, the previously defined default value (if any) on the
+      #   superclass or in the schema will be used. Otherwise, the default will
+      #   be +nil+.
       #
-      # +array+ (PostgreSQL only) specifies that the type should be an array (see the
-      # examples below).
+      # [+:array+]
+      #   (PostgreSQL only) Specifies that the type should be an array. See the
+      #   examples below.
       #
-      # +range+ (PostgreSQL only) specifies that the type should be a range (see the
-      # examples below).
+      # [+:range+]
+      #   (PostgreSQL only) Specifies that the type should be a range. See the
+      #   examples below.
       #
       # When using a symbol for +cast_type+, extra options are forwarded to the
       # constructor of the type object.
@@ -217,17 +224,22 @@ module ActiveRecord
       # is provided so it can be used by plugin authors, application code
       # should probably use ClassMethods#attribute.
       #
-      # +name+ The name of the attribute being defined. Expected to be a +String+.
+      # ==== Parameters
+      #
+      # [+name+]
+      #   The name of the attribute being defined. Expected to be a +String+.
       #
-      # +cast_type+ The type object to use for this attribute.
+      # [+cast_type+]
+      #   The type object to use for this attribute.
       #
-      # +default+ The default value to use when no value is provided. If this option
-      # is not passed, the previous default value (if any) will be used.
-      # Otherwise, the default will be +nil+. A proc can also be passed, and
-      # will be called once each time a new value is needed.
+      # [+default+]
+      #   The default value to use when no value is provided. If this option
+      #   is not passed, the previous default value (if any) will be used.
+      #   Otherwise, the default will be +nil+. A proc can also be passed, and
+      #   will be called once each time a new value is needed.
       #
-      # +user_provided_default+ Whether the default value should be cast using
-      # +cast+ or +deserialize+.
+      # [+user_provided_default+]
+      #   Whether the default value should be cast using +cast+ or +deserialize+.
       def define_attribute(
         name,
         cast_type,
@@ -240,6 +252,7 @@ module ActiveRecord
 
       def _default_attributes # :nodoc:
         @default_attributes ||= begin
+          # TODO: Remove the need for a connection after we release 8.1.
           attributes_hash = with_connection do |connection|
             columns_hash.transform_values do |column|
               ActiveModel::Attribute.from_database(column.name, column.default, type_for_column(connection, column))
@@ -299,6 +312,7 @@ module ActiveRecord
         end
 
         def type_for_column(connection, column)
+          # TODO: Remove the need for a connection after we release 8.1.
           hook_attribute_type(column.name, super)
         end
     end

data/lib/active_record/base.rb

@@ -328,7 +328,6 @@ module ActiveRecord # :nodoc:
     include TokenFor
     include SignedId
     include Suppressor
-    include Normalization
     include Marshalling::Methods
 
     self.param_delimiter = "_"

data/lib/active_record/coders/json.rb

@@ -1,14 +1,23 @@
 # frozen_string_literal: true
 
+require "active_support/json"
+
 module ActiveRecord
   module Coders # :nodoc:
-    module JSON # :nodoc:
-      def self.dump(obj)
-        ActiveSupport::JSON.encode(obj)
+    class JSON # :nodoc:
+      DEFAULT_OPTIONS = { escape: false }.freeze
+
+      def initialize(options = nil)
+        @options = options ? DEFAULT_OPTIONS.merge(options) : DEFAULT_OPTIONS
+        @encoder = ActiveSupport::JSON::Encoding.json_encoder.new(options)
+      end
+
+      def dump(obj)
+        @encoder.encode(obj)
       end
 
-      def self.load(json)
-        ActiveSupport::JSON.decode(json) unless json.blank?
+      def load(json)
+        ActiveSupport::JSON.decode(json, @options) unless json.blank?
       end
     end
   end

data/lib/active_record/connection_adapters/abstract/connection_handler.rb

@@ -158,9 +158,7 @@ module ActiveRecord
         each_connection_pool(role).any?(&:active_connection?)
       end
 
-      # Returns any connections in use by the current thread back to the pool,
-      # and also returns connections to the pool cached by threads that are no
-      # longer alive.
+      # Returns any connections in use by the current thread back to the pool.
       def clear_active_connections!(role = nil)
         each_connection_pool(role).each do |pool|
           pool.release_connection
@@ -168,7 +166,7 @@ module ActiveRecord
         end
       end
 
-      # Clears the cache which maps classes.
+      # Clears reloadable connection caches in all connection pools.
       #
       # See ConnectionPool#clear_reloadable_connections! for details.
       def clear_reloadable_connections!(role = nil)

data/lib/active_record/connection_adapters/abstract/connection_pool/queue.rb

@@ -40,6 +40,14 @@ module ActiveRecord
           end
         end
 
+        # Add +element+ to the back of the queue.  Never blocks.
+        def add_back(element)
+          synchronize do
+            @queue.unshift element
+            @cond.signal
+          end
+        end
+
         # If +element+ is in the queue, remove and return it, or +nil+.
         def delete(element)
           synchronize do
@@ -54,6 +62,13 @@ module ActiveRecord
           end
         end
 
+        # Number of elements in the queue.
+        def size
+          synchronize do
+            @queue.size
+          end
+        end
+
         # Remove the head of the queue.
         #
         # If +timeout+ is not given, remove and return the head of the