Skip to content

Commit

Permalink
Updated GC signatures
Browse files Browse the repository at this point in the history
  • Loading branch information
@sampersand
sampersand committed Sep 21, 2023
1 parent 9a5765e commit 6171416
Show file tree
Hide file tree
Showing 3 changed files with 404 additions and 159 deletions.
306 changes: 182 additions & 124 deletions core/gc.rbs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@
# You may obtain information about the operation of the GC through GC::Profiler.
#
module GC
# <!-- rdoc-file=gc.c -->
# internal constants
#
INTERNAL_CONSTANTS: Hash[Symbol, Integer | bool]

# <!-- rdoc-file=gc.c -->
# GC build options
#
OPTS: Array[String]

# <!--
# rdoc-file=gc.rb
# - GC.count -> Integer
Expand Down Expand Up @@ -64,7 +74,7 @@ module GC
# are not guaranteed to be future-compatible, and may be ignored if the
# underlying implementation does not support them.
#
def self.start: (?immediate_sweep: boolish immediate_sweep, ?immediate_mark: boolish immediate_mark, ?full_mark: boolish full_mark) -> nil
def self.start: (?immediate_sweep: boolish, ?immediate_mark: boolish, ?full_mark: boolish) -> nil

# <!--
# rdoc-file=gc.rb
Expand Down Expand Up @@ -150,16 +160,16 @@ module GC
#
# This method is only expected to work on CRuby.
#
def self.stat: (?::Hash[Symbol, Integer] arg0) -> ::Hash[Symbol, Integer]
| (?Symbol arg0) -> Integer
def self.stat: (?Hash[Symbol, Integer]? hash) -> Hash[Symbol, Integer]
| (Symbol key) -> Integer

# <!--
# rdoc-file=gc.rb
# - GC.stress -> integer, true or false
# -->
# Returns current status of GC stress mode.
#
def self.stress: () -> (Integer | TrueClass | FalseClass)
def self.stress: () -> (Integer | bool)

# <!--
# rdoc-file=gc.rb
Expand All @@ -177,7 +187,8 @@ module GC
# 0x02:: no immediate sweep
# 0x04:: full mark after malloc/calloc/realloc
#
def self.stress=: (Integer | TrueClass | FalseClass flag) -> (Integer | TrueClass | FalseClass)
def self.stress=: (Integer flag) -> Integer
| (bool flag) -> bool

# <!--
# rdoc-file=gc.rb
Expand All @@ -204,7 +215,11 @@ module GC
#
# GC.respond_to?(:compact)
#
def self.compact: () -> ::Hash[:considered | :moved, Hash[Symbol | Integer, Integer]]
def self.compact: () -> compact_info

# The type that `GC.compact` and related functions can return.
#
type compact_info = Hash[:considered | :moved |:moved_up | :moved_down, Hash[Symbol, Integer]]

# <!--
# rdoc-file=gc.rb
Expand All @@ -221,7 +236,7 @@ module GC
# a full GC. If any object contains a reference to a T_MOVED object, that
# object should be pushed on the mark stack, and will make a SEGV.
#
def self.verify_compaction_references: () -> ::Hash[:considered | :moved, Hash[Symbol | Integer, Integer]]
def self.verify_compaction_references: (?toward: :empty | untyped, ?double_heap: boolish, ?expand_heap: boolish) -> compact_info

# <!--
# rdoc-file=gc.c
Expand All @@ -245,155 +260,198 @@ module GC
# If the optional argument, hash, is given, it is overwritten and returned. This
# is intended to avoid probe effect.
#
def self.latest_gc_info: () -> ::Hash[::Symbol, untyped]
| [K] (?Hash[K, untyped] hash) -> ::Hash[::Symbol | K, untyped]
def self.latest_gc_info: (?nil) -> Hash[Symbol, untyped]
| (Hash[Symbol, untyped] hash) -> Hash[Symbol, untyped]
| (Symbol key) -> untyped

# <!--
# rdoc-file=gc.rb
# - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
# -->
#
def garbage_collect: (?immediate_sweep: boolish immediate_sweep, ?immediate_mark: boolish immediate_mark, ?full_mark: boolish full_mark) -> nil
end

# <!-- rdoc-file=gc.c -->
# internal constants
#
GC::INTERNAL_CONSTANTS: Hash[Symbol, Integer]
def garbage_collect: (?immediate_sweep: boolish, ?immediate_mark: boolish, ?full_mark: boolish) -> nil

# <!-- rdoc-file=gc.c -->
# GC build options
#
GC::OPTS: Array[String]
def verify_transient_heap_internal_consistency: () -> nil

# <!-- rdoc-file=gc.c -->
# The GC profiler provides access to information on GC runs including time,
# length and object space size.
#
# Example:
#
# GC::Profiler.enable
#
# require 'rdoc/rdoc'
#
# GC::Profiler.report
#
# GC::Profiler.disable
#
# See also GC.count, GC.malloc_allocated_size and GC.malloc_allocations
#
module GC::Profiler
# <!--
# rdoc-file=gc.c
# - GC::Profiler.clear -> nil
# - GC.auto_compact -> true or false
# -->
# Clears the GC profiler data.
# Returns whether or not automatic compaction has been enabled.
#
def self.clear: () -> void
def self.auto_compact: () -> bool

# <!--
# rdoc-file=gc.c
# - GC::Profiler.disable -> nil
# - GC.auto_compact = flag
# -->
# Stops the GC profiler.
# Updates automatic compaction mode.
#
def self.disable: () -> void

# <!--
# rdoc-file=gc.c
# - GC::Profiler.enable -> nil
# -->
# Starts the GC profiler.
# When enabled, the compactor will execute on every major collection.
#
def self.enable: () -> void
# Enabling compaction will degrade performance on major collections.
def self.auto_compact=: [T] (T enable) -> T

# <!--
# rdoc-file=gc.c
# - GC::Profiler.enabled? -> true or false
# rdoc-file=gc.rb
# - GC.latest_compact_info -> hash
# -->
# The current status of GC profile mode.
# Returns information about object moved in the most recent GC compaction.
#
# The returned hash has two keys :considered and :moved. The hash for
# :considered lists the number of objects that were considered for movement by
# the compactor, and the :moved hash lists the number of objects that were
# actually moved. Some objects can't be moved (maybe they were pinned) so these
# numbers can be used to calculate compaction efficiency.
#
def self.enabled?: () -> bool
def self.latest_compact_info: () -> compact_info

# <!--
# rdoc-file=gc.c
# - GC::Profiler.raw_data -> [Hash, ...]
# rdoc-file=gc.rb
# - GC.measure_total_time -> true/false
# -->
# Returns an Array of individual raw profile data Hashes ordered from earliest
# to latest by `:GC_INVOKE_TIME`.
#
# For example:
#
# [
# {
# :GC_TIME=>1.3000000000000858e-05,
# :GC_INVOKE_TIME=>0.010634999999999999,
# :HEAP_USE_SIZE=>289640,
# :HEAP_TOTAL_SIZE=>588960,
# :HEAP_TOTAL_OBJECTS=>14724,
# :GC_IS_MARKED=>false
# },
# # ...
# ]
#
# The keys mean:
#
# `:GC_TIME`
# : Time elapsed in seconds for this GC run
# `:GC_INVOKE_TIME`
# : Time elapsed in seconds from startup to when the GC was invoked
# `:HEAP_USE_SIZE`
# : Total bytes of heap used
# `:HEAP_TOTAL_SIZE`
# : Total size of heap in bytes
# `:HEAP_TOTAL_OBJECTS`
# : Total number of objects
# `:GC_IS_MARKED`
# : Returns `true` if the GC is in mark phase
#
#
# If ruby was built with `GC_PROFILE_MORE_DETAIL`, you will also have access to
# the following hash keys:
#
# `:GC_MARK_TIME`
# `:GC_SWEEP_TIME`
# `:ALLOCATE_INCREASE`
# `:ALLOCATE_LIMIT`
# `:HEAP_USE_PAGES`
# `:HEAP_LIVE_OBJECTS`
# `:HEAP_FREE_OBJECTS`
# `:HAVE_FINALIZE`
# :
#
def self.raw_data: () -> ::Array[::Hash[Symbol, untyped]]
# Return measure_total_time flag (default: `true`). Note that measurement can
# affect the application performance.
#
def self.measure_total_time: () -> bool

# <!--
# rdoc-file=gc.c
# - GC::Profiler.report
# - GC::Profiler.report(io)
# rdoc-file=gc.rb
# - GC.measure_total_time = true/false
# -->
# Writes the GC::Profiler.result to `$stdout` or the given IO object.
# Enable to measure GC time. You can get the result with `GC.stat(:time)`. Note
# that GC time measurement can cause some performance overhead.
#
def self.report: (?IO io) -> void
def self.measure_total_time=: [T] (T enable) -> T

# <!--
# rdoc-file=gc.c
# - GC::Profiler.result -> String
# -->
# Returns a profile data report such as:
# <!-- rdoc-file=gc.c -->
# The GC profiler provides access to information on GC runs including time,
# length and object space size.
#
# GC 1 invokes.
# Index Invoke Time(sec) Use Size(byte) Total Size(byte) Total Object GC time(ms)
# 1 0.012 159240 212940 10647 0.00000000000001530000
# Example:
#
def self.result: () -> String

# <!--
# rdoc-file=gc.c
# - GC::Profiler.total_time -> float
# -->
# The total time used for garbage collection in seconds
# GC::Profiler.enable
#
def self.total_time: () -> Float
# require 'rdoc/rdoc'
#
# GC::Profiler.report
#
# GC::Profiler.disable
#
# See also GC.count, GC.malloc_allocated_size and GC.malloc_allocations
#
module Profiler
# <!--
# rdoc-file=gc.c
# - GC::Profiler.clear -> nil
# -->
# Clears the GC profiler data.
#
def self.clear: () -> nil

# <!--
# rdoc-file=gc.c
# - GC::Profiler.disable -> nil
# -->
# Stops the GC profiler.
#
def self.disable: () -> nil

# <!--
# rdoc-file=gc.c
# - GC::Profiler.enable -> nil
# -->
# Starts the GC profiler.
#
def self.enable: () -> nil

# <!--
# rdoc-file=gc.c
# - GC::Profiler.enabled? -> true or false
# -->
# The current status of GC profile mode.
#
def self.enabled?: () -> bool

# <!--
# rdoc-file=gc.c
# - GC::Profiler.raw_data -> [Hash, ...]
# -->
# Returns an Array of individual raw profile data Hashes ordered from earliest
# to latest by `:GC_INVOKE_TIME`.
#
# For example:
#
# [
# {
# :GC_TIME=>1.3000000000000858e-05,
# :GC_INVOKE_TIME=>0.010634999999999999,
# :HEAP_USE_SIZE=>289640,
# :HEAP_TOTAL_SIZE=>588960,
# :HEAP_TOTAL_OBJECTS=>14724,
# :GC_IS_MARKED=>false
# },
# # ...
# ]
#
# The keys mean:
#
# `:GC_TIME`
# : Time elapsed in seconds for this GC run
# `:GC_INVOKE_TIME`
# : Time elapsed in seconds from startup to when the GC was invoked
# `:HEAP_USE_SIZE`
# : Total bytes of heap used
# `:HEAP_TOTAL_SIZE`
# : Total size of heap in bytes
# `:HEAP_TOTAL_OBJECTS`
# : Total number of objects
# `:GC_IS_MARKED`
# : Returns `true` if the GC is in mark phase
#
#
# If ruby was built with `GC_PROFILE_MORE_DETAIL`, you will also have access to
# the following hash keys:
#
# `:GC_MARK_TIME`
# `:GC_SWEEP_TIME`
# `:ALLOCATE_INCREASE`
# `:ALLOCATE_LIMIT`
# `:HEAP_USE_PAGES`
# `:HEAP_LIVE_OBJECTS`
# `:HEAP_FREE_OBJECTS`
# `:HAVE_FINALIZE`
# :
#
def self.raw_data: () -> Array[Hash[Symbol, untyped]]?

# <!--
# rdoc-file=gc.c
# - GC::Profiler.report
# - GC::Profiler.report(io)
# -->
# Writes the GC::Profiler.result to `$stdout` or the given IO object.
#
def self.report: (?_Writer io) -> nil

# <!--
# rdoc-file=gc.c
# - GC::Profiler.result -> String
# -->
# Returns a profile data report such as:
#
# GC 1 invokes.
# Index Invoke Time(sec) Use Size(byte) Total Size(byte) Total Object GC time(ms)
# 1 0.012 159240 212940 10647 0.00000000000001530000
#
def self.result: () -> String

# <!--
# rdoc-file=gc.c
# - GC::Profiler.total_time -> float
# -->
# The total time used for garbage collection in seconds
#
def self.total_time: () -> Float
end
end
Loading

0 comments on commit 6171416

Please sign in to comment.