rbs 2.0.0 → 2.1.0

data/core/object_space.rbs

@@ -1,11 +1,12 @@
+# <!-- rdoc-file=gc.c -->
 # The ObjectSpace module contains a number of routines that interact with the
 # garbage collection facility and allow you to traverse all living objects with
 # an iterator.
 #
 # ObjectSpace also provides support for object finalizers, procs that will be
 # called when a specific object is about to be destroyed by garbage collection.
-#
-#     require 'objspace'
+# See the documentation for `ObjectSpace.define_finalizer` for important
+# information on how to use this method correctly.
 #
 #     a = "A"
 #     b = "B"
@@ -13,13 +14,27 @@
 #     ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
 #     ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
 #
+#     a = nil
+#     b = nil
+#
 # *produces:*
 #
 #     Finalizer two on 537763470
 #     Finalizer one on 537763480
+#
+%a{annotate:rdoc:source:from=gc.c}
 module ObjectSpace
+  # <!--
+  #   rdoc-file=gc.c
+  #   - _id2ref(p1)
+  # -->
+  #
   def self._id2ref: (Integer id) -> untyped
 
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.count_objects([result_hash]) -> hash
+  # -->
   # Counts all objects grouped by type.
   #
   # It returns a hash, such as:
@@ -50,13 +65,74 @@ module ObjectSpace
   #
   def self.count_objects: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
 
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.define_finalizer(obj, aProc=proc())
+  # -->
   # Adds *aProc* as a finalizer, to be called after *obj* was destroyed. The
   # object ID of the *obj* will be passed as an argument to *aProc*. If *aProc* is
   # a lambda or method, make sure it can be called with a single argument.
   #
+  # The return value is an array `[0, aProc]`.
+  #
+  # The two recommended patterns are to either create the finaliser proc in a
+  # non-instance method where it can safely capture the needed state, or to use a
+  # custom callable object that stores the needed state explicitly as instance
+  # variables.
+  #
+  #     class Foo
+  #       def initialize(data_needed_for_finalization)
+  #         ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
+  #       end
+  #
+  #       def self.create_finalizer(data_needed_for_finalization)
+  #         proc {
+  #           puts "finalizing #{data_needed_for_finalization}"
+  #         }
+  #       end
+  #     end
+  #
+  #     class Bar
+  #      class Remover
+  #         def initialize(data_needed_for_finalization)
+  #           @data_needed_for_finalization = data_needed_for_finalization
+  #         end
+  #
+  #         def call(id)
+  #           puts "finalizing #{@data_needed_for_finalization}"
+  #         end
+  #       end
+  #
+  #       def initialize(data_needed_for_finalization)
+  #         ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
+  #       end
+  #     end
+  #
+  # Note that if your finalizer references the object to be finalized it will
+  # never be run on GC, although it will still be run at exit. You will get a
+  # warning if you capture the object to be finalized as the receiver of the
+  # finalizer.
+  #
+  #     class CapturesSelf
+  #       def initialize(name)
+  #         ObjectSpace.define_finalizer(self, proc {
+  #           # this finalizer will only be run on exit
+  #           puts "finalizing #{name}"
+  #         })
+  #       end
+  #     end
+  #
+  # Also note that finalization can be unpredictable and is never guaranteed to be
+  # run except on exit.
+  #
   def self.define_finalizer: (untyped obj, ^(Integer id) -> void aProc) -> [ Integer, Proc ]
                            | (untyped obj) { (Integer id) -> void } -> [ Integer, Proc ]
 
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.each_object([module]) {|obj| ... } -> integer
+  #   - ObjectSpace.each_object([module])              -> an_enumerator
+  # -->
   # Calls the block once for each living, nonimmediate object in this Ruby
   # process. If *module* is specified, calls the block for only those classes or
   # modules that match (or are a subclass of) *module*. Returns the number of
@@ -86,13 +162,27 @@ module ObjectSpace
   def self.each_object: (?Module `module`) -> Enumerator[untyped, Integer]
                       | (?Module `module`) { (untyped obj) -> void } -> Integer
 
+  # <!--
+  #   rdoc-file=gc.rb
+  #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
+  # -->
+  #
   def self.garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.undefine_finalizer(obj)
+  # -->
   # Removes all finalizers for *obj*.
   #
   def self.undefine_finalizer: [X] (X obj) -> X
 
   private
 
+  # <!--
+  #   rdoc-file=gc.rb
+  #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
+  # -->
+  #
   def garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 end