duel-retained 0.1.8 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8b0e3f2333c501f18a1d4cce5eaee5d2ad0684ad0feb93d415bed0ad02d1b3ae
4
- data.tar.gz: ea72b25dc8376a06690a444bb872d806645d946b01f6c918005457cf9ff116fb
3
+ metadata.gz: 4ce7ca0ddab16196946303dda0fa93c5da732fa4819575e1da5a52d51aa39799
4
+ data.tar.gz: 9eedcbb943fdd1d74f2484d18608c6d5fd93f5e49db4d4d9bc7dc183cbd92415
5
5
  SHA512:
6
- metadata.gz: fd6f229ee2f501eaa51f3c47d2e934baa3d1f4111d271b0edd47553253caccb983f4af6a8d4c6809144e4c547fd04ae8b1570075d005ec143209dc474b4e0d83
7
- data.tar.gz: 6e57968aebda36683620065659b36a163ab117495b989a47957af19adb6d49c4b7a5af7e2069745840b991b55b2333b0e36ae8912e04f637a59b821c1a5991ca
6
+ metadata.gz: 84e3b8ece4fab02ce721a888e431a06421cfc3da71e267a4638591e4769b2c94f0ec788dfaa642e279759d26983d0c525f82c8dd7a88f5201412002a9e1f6057
7
+ data.tar.gz: 861cf3f68b462fb1993fa9248ab5e5c12c46da13a484366f008e0fbfc355602804529881d26daa7687ee868f679869d265eb68e2b4ffbab9e70aeb7161ee5495
data/CHANGELOG.md CHANGED
@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.3.0] - 2026-11-20
11
+
12
+ ### Changed
13
+
14
+ - `retained_objects`' slack is `per_sample:` (16 objects a sample) and
15
+ `per_iteration:` (one per two iterations), as Duel 0.3.0 names them,
16
+ in place of `allowance:` and `tolerance:`:
17
+ `c.measure("retained_objects", per_sample: 32)`.
18
+ - It requires Duel 0.3.0 or later (`~> 0.3.0`), the release it's
19
+ tested with, as Duel 0.3.0 changes what plugins and benchmarks call.
20
+
21
+ ## [0.2.0] - 2026-11-16
22
+
23
+ ### Changed
24
+
25
+ - The kinds of object a regression shows are separated by `; `, as
26
+ other plugins' statements are, rather than `, `: "an iteration: 3
27
+ Array (lib/a.rb:1); 2 String (lib/b.rb:2)".
28
+
10
29
  ## [0.1.8] - 2026-11-12
11
30
 
12
31
  No changes of its own: released in step with the other Duel gems.
@@ -64,7 +83,9 @@ on CRuby alone (on JRuby and TruffleRuby it leaves itself out).
64
83
  CI.
65
84
  - RBS signatures in sig/, checked with Steep.
66
85
 
67
- [Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.1.8...HEAD
86
+ [Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.3.0...HEAD
87
+ [0.3.0]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.2.0...duel-retained-v0.3.0
88
+ [0.2.0]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.1.8...duel-retained-v0.2.0
68
89
  [0.1.8]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.1.7...duel-retained-v0.1.8
69
90
  [0.1.7]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.1.6...duel-retained-v0.1.7
70
91
  [0.1.6]: https://github.com/sferik/duel-ruby/compare/duel-retained-v0.1.5...duel-retained-v0.1.6
data/README.md CHANGED
@@ -63,17 +63,18 @@ it was made (the three most): see [What it retained](#what-it-retained).
63
63
 
64
64
  Install it after any other plugin's metrics: those added after it are
65
65
  read inside its measurement, and what they keep of their readings counts
66
- toward its allowance.
66
+ toward what it lets a sample keep (its `per_sample:`).
67
67
 
68
68
  A sample may leave 16 objects alive before any counts against it (its
69
- allowance), and beyond that it's one more per two iterations (its
70
- tolerance) that's a regression: see [below](#what-it-cant-help-counting).
69
+ `per_sample:`), and beyond that it's one more per two iterations (its
70
+ `per_iteration:`) that's a regression: see
71
+ [below](#what-it-cant-help-counting).
71
72
  Duel's `c.measure` changes either, or leaves the metric out:
72
73
 
73
74
  ```ruby
74
75
  Duel.configure do |c|
75
76
  c.use :retained
76
- c.measure("retained_objects", allowance: 32, tolerance: 1) # or skip: true
77
+ c.measure("retained_objects", per_sample: 32, per_iteration: 1) # or skip: true
77
78
  end
78
79
  ```
79
80
 
@@ -98,7 +99,8 @@ benchmark, for even a large application.
98
99
  What's measured is the count itself, every object more after the sample
99
100
  than before it (or fewer, for one that let go of more than it kept), and
100
101
  Duel judges it: a candidate that leaves more alive than the baseline, by
101
- more than the allowance a sample and the tolerance an iteration, fails.
102
+ more than its `per_sample:` a sample and its `per_iteration:` an
103
+ iteration, fails.
102
104
 
103
105
  ### What it can't help counting
104
106
 
@@ -115,14 +117,14 @@ always to the object, so a sample is allowed 16 before any is counted.
115
117
  On top of that, it's one more per two iterations, not one more, that's a
116
118
  regression. So for a benchmark that runs thousands of iterations a
117
119
  sample, as most do, one object kept an iteration fails. For one that
118
- runs a few (a slow one, or one with `only: :count`, which runs four),
120
+ runs a few (a slow one, or one with `judge: :counted`, which runs four),
119
121
  it takes more an iteration.
120
122
 
121
123
  What a benchmark makes the first time and keeps (a constant it
122
124
  memoizes, a method cache) isn't a leak: Duel runs each benchmark many
123
125
  times before it counts, and none of that is counted.
124
126
 
125
- Benchmarks with `only: :timing` aren't counted at all, so they aren't
127
+ Benchmarks with `judge: :timed` aren't counted at all, so they aren't
126
128
  judged on this either.
127
129
 
128
130
  ### Untimed blocks
@@ -136,8 +138,9 @@ What it usually makes, the input a benchmark works on, isn't.
136
138
 
137
139
  ## What it retained
138
140
 
139
- Where a sample retained more than Duel lets through (its allowance, and
140
- its tolerance for its iterations, as `c.measure` leaves them), the
141
+ Where a sample retained more than Duel lets through (its `per_sample:`,
142
+ and its `per_iteration:` for its iterations, as `c.measure` leaves
143
+ them), the
141
144
  plugin says what, under the regression: the objects' classes, and where
142
145
  they were made, the three most, an iteration (`1 String
143
146
  (lib/my_formatter.rb:3)`), of the sample whose count was judged, on
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Duel
4
4
  module Retained
5
- VERSION = "0.1.8"
5
+ VERSION = "0.3.0"
6
6
  end
7
7
  end
data/lib/duel/retained.rb CHANGED
@@ -9,7 +9,7 @@ module Duel
9
9
  # a full garbage collection that weren't before it (CRuby).
10
10
  #
11
11
  # - retained_objects: the objects a sample's iterations left alive
12
- # (counted; beyond ALLOWANCE a sample, one more per two iterations is
12
+ # (counted; beyond PER_SAMPLE a sample, one more per two iterations is
13
13
  # a regression)
14
14
  #
15
15
  # # .duel.rb
@@ -31,19 +31,19 @@ module Duel
31
31
  module Retained
32
32
  Duel.plugin(:retained, self)
33
33
 
34
- # The retained objects a sample is allowed (Duel's allowance) before
34
+ # The retained objects a sample is allowed (Duel's per_sample) before
35
35
  # any is counted against it: Duel's own record of the metrics inside
36
36
  # this one, and what's still on the machine stack when the sample
37
37
  # stops (the last iteration's result, or the block's, given n),
38
38
  # which are the same few from sample to sample, but not always to the
39
39
  # object.
40
- ALLOWANCE = 16
40
+ PER_SAMPLE = 16
41
41
 
42
42
  # Retained objects per iteration that still aren't a regression.
43
- TOLERANCE = 0.5
43
+ PER_ITERATION = 0.5
44
44
 
45
45
  # The kinds of object (by class, and where they were made) a sample
46
- # that retained more than its allowance shows, most first.
46
+ # that retained more than it's allowed shows, most first.
47
47
  SHOWN = 3
48
48
 
49
49
  # Configures Duel for the plugin (c.use :retained): the metric
@@ -65,7 +65,7 @@ module Duel
65
65
  end
66
66
 
67
67
  # Where Duel's own files are: what it makes during a sample (its
68
- # record of the metrics inside this one) is in the allowance, and
68
+ # record of the metrics inside this one) is in what it's allowed, and
69
69
  # isn't shown.
70
70
  # (Duel's metric.rb, written in Ruby: it has a source location.)
71
71
  metric_rb, = Metric.instance_method(:details).source_location #: [String, Integer]
@@ -97,9 +97,9 @@ module Duel
97
97
 
98
98
  # The metric: the objects alive after the sample less those before
99
99
  # it (fewer, when the sample let go of more than it kept). Duel takes
100
- # the allowance and the tolerance into account when it compares them.
100
+ # its per_sample and per_iteration into account when it compares them.
101
101
  class Objects < Metric
102
- def self.measures = {"retained_objects" => {unit: %w[object objects], allowance: ALLOWANCE, tolerance: TOLERANCE}}
102
+ def self.measures = {"retained_objects" => {unit: %w[object objects], per_sample: PER_SAMPLE, per_iteration: PER_ITERATION}}
103
103
 
104
104
  # mutant:disable -- mutant runs on CRuby, where this is always true
105
105
  def self.available? = RUBY_ENGINE == "ruby"
@@ -133,7 +133,7 @@ module Duel
133
133
 
134
134
  # What the sample retained, an iteration, by class and where it was
135
135
  # made (the SHOWN most), when it retained more than Duel lets through
136
- # (its allowance a sample, and its tolerance an iteration, as
136
+ # (its per_sample a sample, and its per_iteration an iteration, as
137
137
  # configured): only then is it worth walking every live object for
138
138
  # (Retained.traced). Nothing for one that retained less. Duel asks
139
139
  # once, after the sample: the trace is cleared either way.
@@ -141,7 +141,7 @@ module Duel
141
141
  return if within?(@retained, @n)
142
142
 
143
143
  kinds = Retained.traced.first(SHOWN).map { |(klass, site), count| format("%.4g %s (%s)", count.fdiv(@n), klass, site) }
144
- "an iteration: #{kinds.join(", ")}" unless kinds.empty? # (none it can see: internal objects, or a trace cleared)
144
+ "an iteration: #{kinds.join("; ")}" unless kinds.empty? # (none it can see: internal objects, or a trace cleared)
145
145
  ensure
146
146
  ObjectSpace.trace_object_allocations_clear
147
147
  end
@@ -4,14 +4,14 @@ module Duel
4
4
  module Retained
5
5
  VERSION: String
6
6
 
7
- # The retained objects a sample is allowed (Duel's allowance) before
7
+ # The retained objects a sample is allowed (Duel's per_sample) before
8
8
  # any is counted against it.
9
- ALLOWANCE: Integer
9
+ PER_SAMPLE: Integer
10
10
 
11
11
  # Retained objects per iteration that still aren't a regression.
12
- TOLERANCE: Float
12
+ PER_ITERATION: Float
13
13
 
14
- # The kinds of object a sample that retained more than its allowance
14
+ # The kinds of object a sample that retained more than it's allowed
15
15
  # shows, most first.
16
16
  SHOWN: Integer
17
17
 
@@ -54,8 +54,8 @@ module Duel
54
54
  def resume_sample: (Sample _sample) -> nil
55
55
 
56
56
  # What the sample retained, an iteration, by class and where it was
57
- # made, when it retained more than its allowance and tolerance let
58
- # through.
57
+ # made, when it retained more than its per_sample and per_iteration
58
+ # let through.
59
59
  def details: () -> String?
60
60
  end
61
61
  end
metadata CHANGED
@@ -1,67 +1,68 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: duel-retained
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.8
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
- - Erik Berlin
7
+ - Erik Berlin
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
12
- - !ruby/object:Gem::Dependency
13
- name: duel
14
- requirement: !ruby/object:Gem::Requirement
15
- requirements:
16
- - - "~>"
17
- - !ruby/object:Gem::Version
18
- version: '0.1'
19
- type: :runtime
20
- prerelease: false
21
- version_requirements: !ruby/object:Gem::Requirement
22
- requirements:
23
- - - "~>"
24
- - !ruby/object:Gem::Version
25
- version: '0.1'
26
- description: 'A Duel plugin: every benchmark is judged on the Ruby objects its iterations
27
- leave alive after a full garbage collection, so a leak, or a cache that grows with
28
- every call, fails.'
12
+ - !ruby/object:Gem::Dependency
13
+ name: duel
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ -
17
+ - ~>
18
+ - !ruby/object:Gem::Version
19
+ version: 0.3.0
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ -
25
+ - ~>
26
+ - !ruby/object:Gem::Version
27
+ version: 0.3.0
28
+ description: "A Duel plugin: every benchmark is judged on the Ruby objects its iterations leave alive after a full garbage collection, so a leak, or a cache that grows with every call, fails."
29
29
  email:
30
- - sferik@gmail.com
30
+ - sferik@gmail.com
31
31
  executables: []
32
32
  extensions: []
33
33
  extra_rdoc_files: []
34
34
  files:
35
- - CHANGELOG.md
36
- - LICENSE
37
- - README.md
38
- - lib/duel/retained.rb
39
- - lib/duel/retained/version.rb
40
- - sig/duel/retained.rbs
41
- homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/retained
35
+ - CHANGELOG.md
36
+ - LICENSE
37
+ - README.md
38
+ - lib/duel/retained.rb
39
+ - lib/duel/retained/version.rb
40
+ - sig/duel/retained.rbs
41
+ homepage: "https://github.com/sferik/duel-ruby/tree/main/plugins/retained"
42
42
  licenses:
43
- - MIT
43
+ - MIT
44
44
  metadata:
45
- source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/retained
46
- changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/retained/CHANGELOG.md
47
- bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
48
- rubygems_mfa_required: 'true'
45
+ source_code_uri: "https://github.com/sferik/duel-ruby/tree/main/plugins/retained"
46
+ changelog_uri: "https://github.com/sferik/duel-ruby/blob/main/plugins/retained/CHANGELOG.md"
47
+ bug_tracker_uri: "https://github.com/sferik/duel-ruby/issues"
48
+ rubygems_mfa_required: "true"
49
49
  rdoc_options: []
50
50
  require_paths:
51
- - lib
51
+ - lib
52
52
  required_ruby_version: !ruby/object:Gem::Requirement
53
53
  requirements:
54
- - - ">="
55
- - !ruby/object:Gem::Version
56
- version: '3.4'
54
+ -
55
+ - ">="
56
+ - !ruby/object:Gem::Version
57
+ version: "3.4"
57
58
  required_rubygems_version: !ruby/object:Gem::Requirement
58
59
  requirements:
59
- - - ">="
60
- - !ruby/object:Gem::Version
61
- version: '0'
60
+ -
61
+ - ">="
62
+ - !ruby/object:Gem::Version
63
+ version: "0"
62
64
  requirements: []
63
- rubygems_version: 4.0.24
65
+ rubygems_version: 4.1.0
64
66
  specification_version: 4
65
- summary: 'What each Duel benchmark leaves alive: objects that outlive the garbage
66
- collector'
67
+ summary: "What each Duel benchmark leaves alive: objects that outlive the garbage collector"
67
68
  test_files: []