Feature https://bugs.ruby-lang.org/issues/15974.

The idea of this feature is to warn when a finalizer captures the object to be finalized, because this prevents the finalizer being run until the process exits, which is likely not what is intended. This PR covers the most simple and common case, where the receiver of the finalizer is the object to be finalized.

It's easy to do this https://www.mikeperham.com/2010/02/24/the-trouble-with-ruby-finalizers/ and I've done it myself before.

I originally implemented this feature in #2264, but there I tired to solve the general case of warning if the finalizer transitively captured the object to be finalized, by using the GC's mechanism to walk the object graph. That's useful, but impactical. This PR is simple, easy, can always be on, and will capture what I would guess is the most common case. The original implementation was also part of a hack-day, so was very rough, which is why it got reverted in 23c92b6, which was understandable.

I've also improved the specification and documentation of ObjectSpace.define_finalizer.

Overall, this is the idea:

class CapturesSelf
  def initialize(name)
    ObjectSpace.define_finalizer(self, proc {
      # this finalizer will only be run on exit because it has captured self
      puts "finalizing #{name}"
    })
  end
end

CapturesSelf.new('foo')

./test.rb:3: warning: finalizer references object to be finalized