duel 0.1.7 → 0.2.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.
Files changed (61) hide show
  1. checksums.yaml +4 -4
  2. data/AGENT_PROMPT.md +2 -2
  3. data/CHANGELOG.md +203 -1
  4. data/README.md +41 -1
  5. data/docs/ci.md +170 -76
  6. data/docs/configuration.md +38 -2
  7. data/docs/how-it-works.md +18 -9
  8. data/docs/plugins.md +23 -0
  9. data/lib/duel/across.rb +1 -6
  10. data/lib/duel/baseline.rb +8 -7
  11. data/lib/duel/cli.rb +96 -28
  12. data/lib/duel/comment.rb +296 -0
  13. data/lib/duel/config.rb +124 -4
  14. data/lib/duel/context.rb +33 -34
  15. data/lib/duel/control.rb +52 -0
  16. data/lib/duel/init.rb +255 -20
  17. data/lib/duel/lane.rb +734 -0
  18. data/lib/duel/lock.rb +34 -4
  19. data/lib/duel/memory.rb +14 -5
  20. data/lib/duel/metric.rb +97 -26
  21. data/lib/duel/native.rb +199 -32
  22. data/lib/duel/platform.rb +31 -0
  23. data/lib/duel/process_sample.rb +74 -49
  24. data/lib/duel/resource.rb +71 -42
  25. data/lib/duel/result.rb +165 -0
  26. data/lib/duel/rubies.rb +21 -3
  27. data/lib/duel/runner.rb +33 -1044
  28. data/lib/duel/spawn.rb +327 -0
  29. data/lib/duel/summary.rb +21 -15
  30. data/lib/duel/templates/duel.gitlab-ci.yml.erb +8 -19
  31. data/lib/duel/templates/perf-caller.yml.erb +43 -0
  32. data/lib/duel/templates/perf-comment-caller.yml.erb +42 -0
  33. data/lib/duel/templates/perf-comment.yml.erb +61 -44
  34. data/lib/duel/templates/perf.yml.erb +143 -7
  35. data/lib/duel/testing.rb +3 -0
  36. data/lib/duel/version.rb +1 -1
  37. data/lib/duel/worker.rb +13 -4
  38. data/lib/duel/worker_process.rb +142 -0
  39. data/lib/duel.rb +35 -3
  40. data/sig/duel/cli.rbs +19 -0
  41. data/sig/duel/comment.rbs +97 -0
  42. data/sig/duel/config.rbs +57 -2
  43. data/sig/duel/context.rbs +4 -31
  44. data/sig/duel/control.rbs +27 -0
  45. data/sig/duel/init.rbs +95 -1
  46. data/sig/duel/lane.rbs +202 -0
  47. data/sig/duel/lock.rbs +8 -1
  48. data/sig/duel/memory.rbs +1 -1
  49. data/sig/duel/metric.rbs +53 -10
  50. data/sig/duel/native.rbs +109 -9
  51. data/sig/duel/platform.rbs +13 -0
  52. data/sig/duel/process_sample.rbs +7 -9
  53. data/sig/duel/resource.rbs +28 -9
  54. data/sig/duel/result.rbs +164 -0
  55. data/sig/duel/rubies.rbs +4 -0
  56. data/sig/duel/runner.rbs +6 -460
  57. data/sig/duel/spawn.rbs +111 -0
  58. data/sig/duel/summary.rbs +6 -3
  59. data/sig/duel/worker_process.rbs +90 -0
  60. data/sig/duel.rbs +17 -3
  61. metadata +121 -105
data/lib/duel/lock.rb CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  require "fileutils"
4
4
  require_relative "../duel"
5
+ require_relative "platform"
5
6
 
6
7
  module Duel
7
8
  # One run at a time in a project: two would share its tmp/duel and its
@@ -10,15 +11,22 @@ module Duel
10
11
  # however that ends, so a run that crashed leaves nothing to clear. The
11
12
  # file says whose it is, for a run that finds it taken. A run that ends
12
13
  # removes it, and the directories that leaves empty: tmp/duel, and tmp
13
- # if Duel made it.
14
+ # if Duel made it. Windows locks the whole file, and removes none
15
+ # that's open: there, another run's pid can't be read while it holds
16
+ # the lock, and a run removes its lock once it has closed it (unless
17
+ # another has opened it meanwhile, which keeps it).
14
18
  # @api private
15
19
  module Lock
16
20
  # An exclusive lock, or none if another holds it.
17
21
  EXCLUSIVE = File::LOCK_EX | File::LOCK_NB
18
22
 
23
+ # What else says another process holds a lock: JRuby on Windows's
24
+ # NullPointerException.
25
+ HELD = %w[Java::JavaLang::NullPointerException].freeze
26
+
19
27
  # Runs the block holding +dir+'s lock. Fails, naming the run that
20
28
  # holds it, if another does.
21
- def self.hold(dir)
29
+ def self.hold(dir, windows: Platform::WINDOWS)
22
30
  made = missing(dir)
23
31
  FileUtils.mkdir_p(dir)
24
32
  path = File.join(dir, "lock")
@@ -33,6 +41,7 @@ module Duel
33
41
  # one. `duel --clean` may have removed it already.)
34
42
  FileUtils.rm_f(path)
35
43
  file.close
44
+ FileUtils.rm_f(path) if windows
36
45
  tidy(dir, made)
37
46
  end
38
47
  end
@@ -43,9 +52,9 @@ module Duel
43
52
  loop do
44
53
  # (Read from the start, and written at the end: there's no more.)
45
54
  file = File.new(path, "a+")
46
- unless file.flock(EXCLUSIVE)
55
+ unless lock(file)
47
56
  # (Empty for a moment, while its run writes its pid.)
48
- pid = file.read
57
+ pid = whose(file)
49
58
  file.close
50
59
  raise Error, "another duel run#{" (pid #{pid})" unless pid.empty?} is using #{dir}: wait for it to end, or stop it"
51
60
  end
@@ -55,6 +64,27 @@ module Duel
55
64
  end
56
65
  end
57
66
 
67
+ # Locks +file+ (flock's 0), or false if another process holds it, as
68
+ # JRuby on Windows says by raising a Java NullPointerException (an
69
+ # error of no errno's).
70
+ def self.lock(file)
71
+ file.flock(EXCLUSIVE)
72
+ # (By its name: the class is JRuby's alone.)
73
+ rescue => e
74
+ raise unless HELD.include?(e.class.name)
75
+
76
+ false
77
+ end
78
+
79
+ # The pid another run wrote in its lock, +file+, or "": none yet, or
80
+ # on Windows, which keeps a locked file from being read (EACCES, or
81
+ # on JRuby, a SystemCallError of no errno).
82
+ def self.whose(file)
83
+ file.read
84
+ rescue SystemCallError
85
+ ""
86
+ end
87
+
58
88
  # The directories, +dir+ and those it's in, that aren't there yet,
59
89
  # deepest first.
60
90
  def self.missing(dir)
data/lib/duel/memory.rb CHANGED
@@ -1,9 +1,13 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "native"
4
+ require_relative "spawn"
5
+
3
6
  module Duel
4
7
  # The memory a run's workers can take (see Runner#fit): what the
5
8
  # machine has available, or what its cgroup's limit leaves, if that's
6
- # less (a container's, say).
9
+ # less (a container's, say), or on Windows, what GlobalMemoryStatusEx
10
+ # says is available.
7
11
  # @api private
8
12
  module Memory
9
13
  # The kinds of pages macOS's vm_stat counts that a process can have
@@ -17,8 +21,11 @@ module Duel
17
21
  # The bytes available, or nil where Duel can't tell: Linux's
18
22
  # MemAvailable (in +root+'s proc/meminfo), at most what the cgroup
19
23
  # mounted at sys/fs/cgroup leaves, or else macOS's free and
20
- # inactive pages (in what +vm_stat+ prints).
21
- def available(root: ROOT, vm_stat: -> { command("vm_stat") }) = linux(root) || mac(vm_stat.call)
24
+ # inactive pages (in what +vm_stat+ prints), or else what +windows+
25
+ # says (see Native::Windows.available).
26
+ def available(root: ROOT, vm_stat: -> { command("vm_stat") }, windows: -> { Native::Windows.available })
27
+ linux(root) || mac(vm_stat.call) || windows.call
28
+ end
22
29
 
23
30
  # MemAvailable, at most what the cgroup leaves, or nil.
24
31
  def linux(root)
@@ -43,9 +50,11 @@ module Duel
43
50
  # A file's contents, or nil where there's none.
44
51
  def read(path) = (File.read(path) if File.file?(path))
45
52
 
46
- # What a command prints, or nil where there's no such command.
53
+ # What a command prints, or nil where there's no such command. (Its
54
+ # errors read, not shown: JRuby's IO.popen on Windows ignores err:,
55
+ # https://github.com/jruby/jruby/issues/10081.)
47
56
  def command(*args)
48
- IO.popen(args, err: File::NULL, &:read)
57
+ Spawn.open3(:capture3, *args).first
49
58
  rescue SystemCallError
50
59
  nil
51
60
  end
data/lib/duel/metric.rb CHANGED
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "native"
4
+ require_relative "platform"
4
5
 
5
6
  module Duel
6
7
  # Something measured around every sample of every benchmark. A subclass
@@ -151,20 +152,14 @@ module Duel
151
152
  tolerance: given.fetch(:tolerance, 0), allowance: given.fetch(:allowance, 0)}
152
153
  end
153
154
 
154
- # Each measure's kind, :ratio or :counted, by name.
155
- # @api private
156
- def kinds = settings.transform_values { |settings| settings.fetch(:kind) }
157
-
158
155
  # Its measures as the runner learns them, with +overrides+ (see
159
156
  # Config#measure) by name.
160
157
  # @api private
161
158
  def specs(overrides = UNCHANGED)
162
159
  settings(overrides).map do |name, spec|
163
- {"name" => name, "kind" => spec.fetch(:kind).to_s, "unit" => spec.fetch(:unit), "plural" => spec.fetch(:plural),
164
- "floor" => spec.fetch(:floor),
165
- "cpu_floor" => spec.fetch(:cpu_floor), "limit" => spec.fetch(:limit), "unit_ns" => spec.fetch(:unit_ns),
166
- "sizes_samples" => spec.fetch(:sizes_samples), "across" => spec.fetch(:across), "tolerance" => spec.fetch(:tolerance),
167
- "allowance" => spec.fetch(:allowance)}
160
+ # (Its settings by their names as Strings: but calibrate, which
161
+ # is the worker's alone.)
162
+ {"name" => name, **spec.except(:calibrate).transform_keys(&:to_s), "kind" => spec.fetch(:kind).to_s} #: spec
168
163
  end
169
164
  end
170
165
  end
@@ -290,6 +285,16 @@ module Duel
290
285
  snapshot.reading(measures, read)
291
286
  end
292
287
 
288
+ # A measure's settings, as Metric.resolve has them, and whether what
289
+ # reading it costs is learned and taken away (calibrate: see
290
+ # Snapshot): by default, it is.
291
+ # @api private
292
+ def resolve(given)
293
+ resolved = super
294
+ resolved[:calibrate] = given.fetch(:calibrate, true)
295
+ resolved
296
+ end
297
+
293
298
  # Sets what it measures and how it reads them, and returns it.
294
299
  # @api private
295
300
  def reading(measures, read)
@@ -361,12 +366,11 @@ module Duel
361
366
  end
362
367
 
363
368
  # Runs its .open block, if it has one, then learns what reading its
364
- # counted totals costs.
369
+ # counted totals costs (as its settings have them, with
370
+ # Config#measure's changes).
365
371
  def open
366
372
  self.class.opener&.call
367
- calibrated = self.class.measures.filter_map do |name, settings|
368
- name if settings.fetch(:kind, :counted) == :counted && settings.fetch(:calibrate, true)
369
- end
373
+ calibrated = settings.filter_map { |name, settings| name if settings.fetch(:kind) == :counted && settings.fetch(:calibrate) }
370
374
  @overhead = calibrated.to_h { |name| [name, Array.new(CALIBRATION) { grew(self.class.read.totals, name) }.min] }
371
375
  end
372
376
 
@@ -416,15 +420,79 @@ module Duel
416
420
  def self.process = Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID, :nanosecond)
417
421
  end
418
422
 
419
- # simplecov:disable JRuby has no thread CPU clock of Ruby's, but the JVM's (JRuby's
420
- # test run covers these).
421
- if RUBY_ENGINE == "jruby"
423
+ # CPU time on Windows, whose own CPU times (GetThreadTimes's, which
424
+ # Ruby's clocks read) move in ticks of 15.6 ms, more than a sample
425
+ # takes: the cycles charged to the thread or the process (see
426
+ # Native::Windows::Cycles), in nanoseconds at the run's rate. The
427
+ # runner measures the rate once, and its workers inherit it (as RATE,
428
+ # in their environment), so that every worker of both versions counts
429
+ # the same: a version's CPU time against the other's is its cycles'.
430
+ # Its readings are Floats, which Windows doesn't allocate, where it
431
+ # does an Integer past 2**30 (see Native::Windows::Cycles).
432
+ # @api private
433
+ module CycleClock
434
+ RATE = "DUEL_CYCLES_PER_NS"
435
+ # The nanoseconds of each of CALIBRATIONS spins the rate is measured
436
+ # over: the fastest is the rate (a spin the thread was taken off for
437
+ # a while counts fewer cycles).
438
+ CALIBRATION_NS = 50_000_000
439
+ CALIBRATIONS = 3
440
+
441
+ # mutant:disable -- kept only so as not to open them again: they're
442
+ # the same counters however often they're opened
443
+ def self.thread = (@thread ||= Native::Windows::Cycles.new(:thread)).read / rate
444
+
445
+ # mutant:disable -- as .thread
446
+ def self.process = (@process ||= Native::Windows::Cycles.new(:process)).read / rate
447
+
448
+ # +cycles+ (a child process's, say), in whole nanoseconds.
449
+ def self.ns(cycles) = (cycles / rate).round
450
+
451
+ # The cycles in a nanosecond: what +env+ (RATE) says, or else
452
+ # measured (see .calibrate), and set there, for the processes this
453
+ # one starts.
454
+ def self.rate(env: ENV) = @rate ||= Float(env[RATE] ||= calibrate.to_s)
455
+
456
+ # Measures the rate on Windows, once, before a run starts its
457
+ # workers, which inherit it.
458
+ def self.prepare(windows: Platform::WINDOWS) = (rate if windows)
459
+
460
+ # The most cycles +cycles+ (a counter: see Native::Windows::Cycles)
461
+ # counted in a nanosecond of +clock+'s (monotonic, in nanoseconds),
462
+ # spinning for CALIBRATION_NS, CALIBRATIONS times.
463
+ def self.calibrate(cycles: Native::Windows::Cycles.new(:thread), clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) })
464
+ Array.new(CALIBRATIONS) do
465
+ started = clock.call
466
+ counted = cycles.read
467
+ elapsed = clock.call - started
468
+ elapsed = clock.call - started while elapsed < CALIBRATION_NS
469
+ (cycles.read - counted).fdiv(elapsed)
470
+ end.max
471
+ end
472
+ end
473
+
474
+ # simplecov:disable Windows's clock is CycleClock, JRuby's too (Windows's
475
+ # test run covers this): the JVM's CPU times there are Windows's own, in
476
+ # ticks of 15.6 ms.
477
+ if Platform::WINDOWS
478
+ module Clock
479
+ def self.thread = CycleClock.thread
480
+
481
+ def self.process = CycleClock.process
482
+ end
483
+ # (JRuby has no thread CPU clock of Ruby's elsewhere, but the JVM's:
484
+ # JRuby's test run covers these.)
485
+ elsif Platform::JRUBY
422
486
  module Clock
423
487
  def self.thread = java.lang.management.ManagementFactory.getThreadMXBean.getCurrentThreadCpuTime
424
488
 
425
489
  def self.process = java.lang.management.ManagementFactory.getOperatingSystemMXBean.getProcessCpuTime
426
490
  end
491
+ end
492
+ # simplecov:enable
427
493
 
494
+ # simplecov:disable JRuby's (JRuby's test run covers it).
495
+ if Platform::JRUBY
428
496
  # Bytes allocated (JRuby: the JVM's count, as it has none of objects):
429
497
  # by the benchmark thread, or by every thread.
430
498
  # @api private
@@ -452,16 +520,19 @@ module Duel
452
520
  @started = Clock.public_send(@clock)
453
521
  end
454
522
 
455
- def stop_sample = Clock.public_send(@clock) - @started
523
+ # (Rounded: on Windows, the clock's readings are Floats. See
524
+ # CycleClock.)
525
+ def stop_sample = (Clock.public_send(@clock) - @started).round
456
526
  end
457
527
 
458
- # Instructions retired in user space, from the CPU's own counters:
459
- # nearly the same from run to run, so it catches slowdowns too small
460
- # for CPU time to settle (with a limit of its own, 1%). Where the
461
- # counters are: Linux (the benchmark thread's, unless a virtual
462
- # machine hides them, so not for benchmarks with threads of their
463
- # own) and macOS (the whole process's). It misses what instructions
464
- # don't show, like cache misses: CPU time is still judged.
528
+ # Instructions retired, from the CPU's own counters: nearly the same
529
+ # from run to run, so it catches slowdowns too small for CPU time to
530
+ # settle (with a limit of its own, 1%). Where the counters are: Linux
531
+ # (the benchmark thread's, in user space) and macOS (the thread's,
532
+ # the kernel's part too), so not for benchmarks with threads of their
533
+ # own, unless a virtual machine hides them, where macOS counts the
534
+ # whole process's, if it can. It misses what instructions don't show,
535
+ # like cache misses: CPU time is still judged.
465
536
  class Instructions < Metric
466
537
  def self.measures = {"instructions" => {kind: :ratio, floor: 100_000, sizes_samples: false, limit: 1.01}}
467
538
 
@@ -498,7 +569,7 @@ module Duel
498
569
  def self.measures = {"allocated_bytes" => {tolerance: 32, unit: %w[byte bytes]}}
499
570
 
500
571
  # mutant:disable -- mutant runs on CRuby, where this is always false
501
- def self.available? = RUBY_ENGINE == "jruby"
572
+ def self.available? = Platform::JRUBY
502
573
 
503
574
  def start_sample(sample)
504
575
  @scope = sample.benchmark.cpu
@@ -515,7 +586,7 @@ module Duel
515
586
  def self.measures = {"allocations" => {tolerance: 0.5}}
516
587
 
517
588
  # mutant:disable -- mutant runs on CRuby, where this is always true
518
- def self.available? = RUBY_ENGINE == "ruby"
589
+ def self.available? = Platform::CRUBY
519
590
 
520
591
  def start_sample(_sample)
521
592
  @started = GC.stat(:total_allocated_objects)
data/lib/duel/native.rb CHANGED
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "rbconfig"
3
+ require_relative "platform"
4
4
 
5
5
  module Duel
6
6
  # What the operating system can tell about this process, through Fiddle:
@@ -9,9 +9,7 @@ module Duel
9
9
  # bring the JVM down.
10
10
  # @api private
11
11
  module Native
12
- FIDDLE = RUBY_ENGINE == "ruby"
13
- OS = RbConfig::CONFIG["host_os"]
14
- CPU = RbConfig::CONFIG["host_cpu"]
12
+ FIDDLE = Platform::CRUBY
15
13
  UINT64 = 8 # bytes, the size of every count read
16
14
 
17
15
  # Loads Fiddle, as the first C function is made (see .function): not
@@ -23,19 +21,21 @@ module Duel
23
21
  # a process of its own
24
22
  def self.require_fiddle = require("fiddle")
25
23
 
26
- # A C function of the process's own libraries, by name, taking and
27
- # returning Fiddle types (:INT, :LONG, :VOIDP...).
28
- def self.function(name, args, returns)
24
+ # A C function of the process's own libraries (or of +library+, a
25
+ # DLL: on Windows, the process's own are only its program's), by
26
+ # name, taking and returning Fiddle types (:INT, :LONG, :VOIDP...).
27
+ def self.function(name, args, returns, library: nil)
29
28
  require_fiddle
30
- Fiddle::Function.new(Fiddle.dlopen(nil)[name], args.map { |type| Fiddle.const_get(:"TYPE_#{type}") },
29
+ Fiddle::Function.new(Fiddle.dlopen(library)[name], args.map { |type| Fiddle.const_get(:"TYPE_#{type}") },
31
30
  Fiddle.const_get(:"TYPE_#{returns}"))
32
31
  end
33
32
 
34
33
  # Instructions retired in user space, from the CPU's counters.
35
34
  class Counter
36
- # The best counter here: the benchmark thread's (Linux), the
37
- # process's (macOS), or nil.
38
- def self.open(fiddle: FIDDLE) = (Linux.open || MacOS.open if fiddle)
35
+ # The best counter here: the benchmark thread's (Linux's, or
36
+ # macOS's), the process's (macOS's, where the thread's counts
37
+ # nothing: in a virtual machine, say), or nil.
38
+ def self.open(fiddle: FIDDLE) = (Linux.open || MacOSThread.open || MacOS.open if fiddle)
39
39
 
40
40
  # "thread" or "process": whose instructions it counts.
41
41
  attr_reader :scope
@@ -58,7 +58,7 @@ module Duel
58
58
  PERF_FLAG_FD_CLOEXEC = 8
59
59
  ATTR_SIZE = 64 # PERF_ATTR_SIZE_VER0
60
60
 
61
- def self.open(platform: OS, cpu: CPU, syscall: nil)
61
+ def self.open(platform: Platform::OS, cpu: Platform::CPU, syscall: nil)
62
62
  number = SYSCALL[cpu]
63
63
  return unless platform.include?("linux") && number
64
64
 
@@ -86,12 +86,19 @@ module Duel
86
86
  RESIDENT = 64 # offsetof(ri_resident_size)
87
87
  INSTRUCTIONS = 248 # offsetof(ri_instructions)
88
88
 
89
- def self.open(platform: OS, rusage: nil)
89
+ def self.open(platform: Platform::OS, rusage: nil)
90
+ counter = memory(platform: platform, rusage: rusage)
91
+ counter if counter&.read&.positive?
92
+ end
93
+
94
+ # The same call, for resident memory alone: where the instructions
95
+ # aren't counted (a virtual machine's, say), the memory is.
96
+ def self.memory(platform: Platform::OS, rusage: nil)
90
97
  return unless platform.include?("darwin")
91
98
 
92
99
  rusage ||= Native.function("proc_pid_rusage", %i[INT INT VOIDP], :INT)
93
- counter = new(rusage)
94
- counter if counter.read.positive?
100
+ reader = new(rusage)
101
+ reader if reader.resident.positive?
95
102
  rescue Fiddle::DLError # no such function
96
103
  nil
97
104
  end
@@ -116,6 +123,163 @@ module Duel
116
123
  end
117
124
  end
118
125
 
126
+ # macOS: the calling thread's instructions, from thread_selfcounts
127
+ # (THSC_CPI: its instructions, then its cycles), no privileges
128
+ # needed. It's libSystem's, but not documented: where it fails, or
129
+ # counts nothing, there's none (see Counter.open). It counts the
130
+ # thread's instructions in the kernel too, where Linux's counts user
131
+ # space only.
132
+ class MacOSThread < Counter
133
+ THSC_CPI = 1
134
+ SIZE = 16 # sizeof(struct thsc_cpi)
135
+
136
+ def self.open(platform: Platform::OS, selfcounts: nil)
137
+ return unless platform.include?("darwin")
138
+
139
+ selfcounts ||= Native.function("thread_selfcounts", %i[INT VOIDP SIZE_T], :INT)
140
+ counter = new(selfcounts)
141
+ counter if counter.read&.positive?
142
+ rescue Fiddle::DLError # no such function
143
+ nil
144
+ end
145
+
146
+ def initialize(selfcounts)
147
+ super("thread")
148
+ @selfcounts = selfcounts
149
+ @buffer = "\0".b * SIZE
150
+ end
151
+
152
+ # The count, or nil where the call fails.
153
+ def read = (@buffer.unpack1("Q") if @selfcounts.call(THSC_CPI, @buffer, SIZE).zero?)
154
+ end
155
+
156
+ # Windows: this process's working set (its resident memory), from
157
+ # K32GetProcessMemoryInfo, and the memory available, from
158
+ # GlobalMemoryStatusEx, both kernel32's, needing no privileges. (No
159
+ # instructions: it counts none a process can read.)
160
+ class Windows
161
+ KERNEL32 = "kernel32"
162
+ # GetCurrentProcess()'s handle, which needs no closing.
163
+ CURRENT_PROCESS = -1
164
+ COUNTERS = 72 # sizeof(PROCESS_MEMORY_COUNTERS), 64-bit
165
+ PEAK_WORKING_SET = 8 # offsetof(PeakWorkingSetSize)
166
+ WORKING_SET = 16 # offsetof(WorkingSetSize)
167
+ STATUS = 64 # sizeof(MEMORYSTATUSEX)
168
+ AVAILABLE = 16 # offsetof(ullAvailPhys)
169
+
170
+ def self.open(platform: Platform::OS, memory_info: nil)
171
+ return unless platform.match?(Platform::WINDOWS_OS)
172
+
173
+ memory_info ||= Native.function("K32GetProcessMemoryInfo", %i[VOIDP VOIDP INT], :INT, library: KERNEL32)
174
+ windows = new(memory_info)
175
+ windows if windows.resident
176
+ rescue Fiddle::DLError # no such function
177
+ nil
178
+ end
179
+
180
+ # The bytes of physical memory available, or nil where it can't
181
+ # tell.
182
+ def self.available(platform: Platform::OS, status: nil)
183
+ return unless platform.match?(Platform::WINDOWS_OS)
184
+
185
+ status ||= Native.function("GlobalMemoryStatusEx", %i[VOIDP], :INT, library: KERNEL32)
186
+ # (Each struct says its size first, as the call checks.)
187
+ buffer = [STATUS].pack("L").ljust(STATUS, "\0")
188
+ buffer.unpack1("Q", offset: AVAILABLE) unless status.call(buffer).zero?
189
+ rescue Fiddle::DLError # no such function
190
+ nil
191
+ end
192
+
193
+ # +handle+: the process's whose memory it reads (this one's, by
194
+ # default).
195
+ def initialize(memory_info, handle: CURRENT_PROCESS)
196
+ @memory_info = memory_info
197
+ @handle = handle
198
+ @buffer = [COUNTERS].pack("L").ljust(COUNTERS, "\0")
199
+ end
200
+
201
+ # The bytes in its working set, or nil where the call fails.
202
+ def resident = counter(WORKING_SET)
203
+
204
+ # The most bytes its working set has held, or nil where the call
205
+ # fails.
206
+ def peak = counter(PEAK_WORKING_SET)
207
+
208
+ # The CPU cycles charged to this thread (QueryThreadCycleTime) or
209
+ # this process (QueryProcessCycleTime), counted as they run: CPU
210
+ # time at full resolution, where Windows's own CPU times move in
211
+ # ticks of 15.6 ms. Read without allocating, as the CPU metric's
212
+ # readings are inside the count of allocations: the call takes the
213
+ # count's address as an integer (a pointer Fiddle would wrap), and
214
+ # the count is read back a byte at a time, as a Float. (On Windows,
215
+ # an Integer past 2**30 is a Bignum, allocated, as a C long is 32
216
+ # bits there, but a Float isn't, and a double holds a count exactly
217
+ # to 2**53.)
218
+ class Cycles
219
+ # GetCurrentThread()'s handle, which needs no closing.
220
+ CURRENT_THREAD = -2
221
+ QUERIES = {thread: ["QueryThreadCycleTime", CURRENT_THREAD], process: ["QueryProcessCycleTime", CURRENT_PROCESS]}.freeze #: Hash[:thread | :process, [String, Integer]]
222
+
223
+ # +handle+: the thread's or process's (by default, this one).
224
+ # mutant:disable -- Integer(), #to_int and #to_i are a Pointer's
225
+ # address alike, and how its memory is freed (test_windows_cycles
226
+ # checks it is) can't show in what's read
227
+ def initialize(scope, query: nil, handle: nil)
228
+ name, current = QUERIES.fetch(scope)
229
+ @handle = handle || current
230
+ @query = query || Native.function(name, %i[INTPTR_T INTPTR_T], :INT, library: KERNEL32)
231
+ @count = Fiddle::Pointer.malloc(UINT64, Fiddle::RUBY_FREE)
232
+ @address = @count.to_i
233
+ end
234
+
235
+ def read
236
+ @query.call(@handle, @address)
237
+ count = 0.0
238
+ byte = UINT64
239
+ count = (count * 256) + (@count[byte -= 1] & 0xff) while byte.positive?
240
+ count
241
+ end
242
+ end
243
+
244
+ # A child process, by a handle of its own (OpenProcess's), opened as
245
+ # it starts: what it took, once it has ended, as Windows keeps no
246
+ # account of a child's CPU time for its parent (Process.times has
247
+ # none): its CPU cycles, and its peak working set. (Not those of the
248
+ # processes it started, which Unix counts in.)
249
+ class Spawned
250
+ QUERY = 0x1000 # PROCESS_QUERY_LIMITED_INFORMATION
251
+
252
+ # +pid+'s, or nil where it can't be opened. (Ruby holds a handle of
253
+ # its own until it's waited for, so one that ended already can.)
254
+ def self.open(pid, open_process: nil)
255
+ open_process ||= Native.function("OpenProcess", %i[INT INT INT], :INTPTR_T, library: KERNEL32)
256
+ handle = open_process.call(QUERY, 0, pid)
257
+ new(handle) unless handle.zero?
258
+ rescue Fiddle::DLError # no such function
259
+ nil
260
+ end
261
+
262
+ def initialize(handle, cycles: nil, memory_info: nil, close: nil)
263
+ @handle = handle
264
+ @cycles = cycles || Cycles.new(:process, handle: handle)
265
+ @memory = Windows.new(memory_info || Native.function("K32GetProcessMemoryInfo", %i[VOIDP VOIDP INT], :INT, library: KERNEL32),
266
+ handle: handle)
267
+ @close = close || Native.function("CloseHandle", %i[INTPTR_T], :INT, library: KERNEL32)
268
+ end
269
+
270
+ def cycles = @cycles.read
271
+
272
+ # Its peak working set, in bytes, or nil.
273
+ def peak = @memory.peak
274
+
275
+ def close = @close.call(@handle)
276
+ end
277
+
278
+ private
279
+
280
+ def counter(offset) = (@buffer.unpack1("Q", offset: offset) unless @memory_info.call(@handle, @buffer, COUNTERS).zero?)
281
+ end
282
+
119
283
  # A child process of this one, waited for.
120
284
  module Child
121
285
  # wait4(2)'s struct rusage: its size, and where its ru_maxrss is (on
@@ -128,12 +292,10 @@ module Duel
128
292
  # Waits for the child +pid+, and returns how it ended (its exit
129
293
  # status, or nil, and the signal that killed it, or nil) and the most
130
294
  # resident memory it reached (its children's too), in bytes, or nil
131
- # where that can't be told (without Fiddle).
132
- def self.wait(pid, fiddle: FIDDLE, platform: OS, wait4: nil)
133
- unless fiddle
134
- status = Process.wait2(pid).last
135
- return [status.exitstatus, status.termsig, nil]
136
- end
295
+ # where that can't be told (without Fiddle, or on Windows, which has
296
+ # no wait4).
297
+ def self.wait(pid, fiddle: FIDDLE, platform: Platform::OS, wait4: nil)
298
+ return ended(Process.wait2(pid).last) if !fiddle || platform.match?(Platform::WINDOWS_OS)
137
299
 
138
300
  wait4 ||= Native.function("wait4", %i[INT VOIDP INT VOIDP], :INT)
139
301
  status = "\0".b * 4
@@ -149,6 +311,10 @@ module Duel
149
311
  [(raw >> 8 if signal.zero?), (signal unless signal.zero?),
150
312
  rusage.unpack1("q", offset: MAXRSS) * (platform.include?("darwin") ? 1 : 1024)]
151
313
  end
314
+
315
+ # How a child that was waited for ended, as .wait says, from its
316
+ # +status+: its peak memory not told.
317
+ def self.ended(status) = [status.exitstatus, status.termsig, nil]
152
318
  end
153
319
 
154
320
  # This process's resident memory in bytes, or nil where it can't tell.
@@ -157,20 +323,21 @@ module Duel
157
323
  # pages need, which would take Etc, a gem a worker would load before
158
324
  # its version.)
159
325
  STATUS = "/proc/self/status"
160
- # macOS's counter, which reads resident memory there, or nil: opened
161
- # as resident memory is first read, as opening it loads Fiddle.
326
+ # What reads resident memory where there's no /proc: macOS's
327
+ # counter, or Windows's, or nil. Opened as resident memory is first
328
+ # read, as opening it loads Fiddle.
162
329
  # mutant:disable -- kept only so as not to open it again: it's the
163
- # same counter however often it's opened
164
- def self.macos_counter
165
- return @macos if defined?(@macos)
330
+ # same reader however often it's opened
331
+ def self.opened_reader
332
+ return @reader if defined?(@reader)
166
333
 
167
- # (Never false: Steep doesn't see that false || nil is nil.)
168
- @macos = (FIDDLE && MacOS.open) || nil #: MacOS?
334
+ @reader = (MacOS.memory || Windows.open if FIDDLE)
169
335
  end
170
336
 
171
- # From /proc (Linux), else from macOS's counter, else nil.
172
- def self.resident(status: STATUS, macos: macos_counter)
173
- return macos&.resident unless File.readable?(status)
337
+ # From /proc (Linux), else from macOS's or Windows's reader, else
338
+ # nil.
339
+ def self.resident(status: STATUS, reader: opened_reader)
340
+ return reader&.resident unless File.readable?(status)
174
341
 
175
342
  kb = File.read(status)[/^VmRSS:\s+(\d+) kB$/, 1] #: String
176
343
  Integer(kb) * 1024
@@ -188,7 +355,7 @@ module Duel
188
355
 
189
356
  # simplecov:disable JRuby's heap is the JVM's (JRuby's test run covers
190
357
  # this).
191
- if RUBY_ENGINE == "jruby"
358
+ if Platform::JRUBY
192
359
  module Memory
193
360
  # The JVM takes memory for its heap ahead of time, and keeps what it
194
361
  # used while it started, so resident memory barely moves as a
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "rbconfig"
4
+
5
+ module Duel
6
+ # What this process runs on, for what differs by it: the host's system
7
+ # (not RUBY_PLATFORM, which is "java" on JRuby) and its CPU, and the
8
+ # Ruby. What differs by one takes it as an option, for its tests to
9
+ # give it another: a yes or no (windows: Platform::WINDOWS, say), but
10
+ # in Native, whose readers tell three systems apart, the system's name
11
+ # (platform: Platform::OS). A plugin asks Duel.windows? instead.
12
+ # @api private
13
+ module Platform
14
+ OS = RbConfig::CONFIG["host_os"]
15
+ CPU = RbConfig::CONFIG["host_cpu"]
16
+
17
+ # What host_os is on Windows: mingw's ("mingw32", "mingw-ucrt") or
18
+ # mswin's ("mswin64_140").
19
+ WINDOWS_OS = /mingw|mswin/
20
+ WINDOWS = OS.match?(WINDOWS_OS)
21
+
22
+ CRUBY = RUBY_ENGINE == "ruby"
23
+ JRUBY = RUBY_ENGINE == "jruby"
24
+
25
+ # JRuby on Windows, whose spawn and Open3 start a process through
26
+ # Java's: spawn redirects nothing, and Process.wait doesn't wait (see
27
+ # Spawn). CONTRIBUTING.md's "JRuby on Windows" lists every way it
28
+ # differs, and where Duel deals with each.
29
+ JRUBY_ON_WINDOWS = JRUBY && WINDOWS
30
+ end
31
+ end