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/sig/duel/lane.rbs ADDED
@@ -0,0 +1,202 @@
1
+ module Duel
2
+ # Workers of both versions, taking turns.
3
+ # @api private
4
+ class Lane
5
+ TARGET_NS: Integer
6
+ RUNS: Integer
7
+ WARMUP: Integer
8
+ HEAP_CAP: Integer
9
+ STEP: Integer
10
+ MAX_PAIRS: Integer
11
+ # The round of a sample from every worker from which a benchmark
12
+ # judged by process is decided.
13
+ MIN_ROUNDS: Integer
14
+ PROCESS_PAIRS: Integer
15
+ COUNTS: Integer
16
+ JRUBY_COUNTS: Integer
17
+ # The rounds of a sample from every worker a count by process takes.
18
+ COUNT_ROUNDS: Integer
19
+ MEMORY_SAMPLES: Integer
20
+ PROFILE_SAMPLES: Integer
21
+ # A process benchmark's pairs before any are measured, and its runs a
22
+ # sample (unless it says), each sample the fastest of them, as many
23
+ # as take PROCESS_SAMPLE_NS of CPU time.
24
+ PROCESS_WARMUP: Integer
25
+ PROCESS_RUNS: Integer
26
+ PROCESS_SAMPLE_NS: Integer
27
+ # The longest TMPDIR a lane's directory goes in.
28
+ SHORT: Integer
29
+
30
+ self.@ids: Integer
31
+ self.@ids_lock: Thread::Mutex
32
+
33
+ # Its number (see .next_id).
34
+ @id: Integer
35
+ @dir: String
36
+ @resources: Array[Resource]
37
+ @workers: Array[WorkerProcess]
38
+ @lock: Thread::Mutex
39
+ @config: Config
40
+ @settings: Settings
41
+ @sides: Hash[String, Side]
42
+ # A process benchmark's peak memory samples, by version.
43
+ @peaks: Hash[String, Array[Integer?]]
44
+ @bases: Array[WorkerProcess]
45
+ @candidates: Array[WorkerProcess]
46
+ @profiler: bool
47
+ # The warm-up's seconds (see #warm).
48
+ @warm: Float
49
+
50
+ attr_reader profiler: bool
51
+
52
+ def initialize: (Config config, Settings settings, Hash[String, Side] sides, ?processes: Integer) -> void
53
+
54
+ # A number of its own for each lane, from 1.
55
+ def self.next_id: () -> Integer
56
+
57
+ # Whether +processes+ workers of each version are enough for a
58
+ # +confidence+ interval over them.
59
+ def self.by_process?: (Integer processes, Float confidence) -> bool
60
+
61
+ # A directory for a lane's sockets.
62
+ def self.tmpdir: () -> String
63
+
64
+ # Where lanes' directories go: TMPDIR if it's short, else /tmp.
65
+ def self.short_tmp: (?String tmpdir, ?windows: bool) -> String
66
+
67
+ # Opens a lane, yields it and always closes it.
68
+ def self.open: [T] (Config config, Settings settings, Hash[String, Side] sides, ?processes: Integer) { (Lane lane) -> T } -> T
69
+
70
+ def benchmarks: () -> Hash[String, Definition::summary]
71
+
72
+ # The Ruby each version runs on, by version.
73
+ def rubies: () -> Hash[String, String]
74
+
75
+ def stop: () -> void
76
+
77
+ # Measures one benchmark on both versions.
78
+ def compare: (String name) -> Result
79
+
80
+ # Profiles of the benchmark on each version, or nil without StackProf.
81
+ def profile: (String name, Integer n) -> Hash[String, Profile::profile]?
82
+
83
+ private
84
+
85
+ def spawn: (String side, Integer index) -> WorkerProcess
86
+
87
+ # Fails if a version's workers loaded a native extension that isn't a
88
+ # build of its own.
89
+ def check_builds: () -> void
90
+
91
+ # Whether +path+ (that +worker+ loaded) is in +side+'s tree, and not
92
+ # in an installed gem.
93
+ def inside?: (String path, String side, WorkerProcess worker) -> bool
94
+
95
+ def each_worker: () { (WorkerProcess worker) -> void } -> void
96
+
97
+ def set_up: (String name, Result result) -> void
98
+
99
+ def metrics: () -> Array[Metric::spec]
100
+
101
+ # What the block returns for each item, each on a thread of its own.
102
+ # Adds an item to a list, from a thread of its own.
103
+ def keep: [T] (Array[T] list, T item) -> void
104
+
105
+ # Whether workers start (and stop) at once.
106
+ PARALLEL: bool
107
+
108
+ # (Untyped: Steep loses a generic in a thread's block.)
109
+ def in_parallel: (Array[untyped] items) { (untyped item) -> untyped } -> Array[untyped]
110
+
111
+ def measure: (String name, Result result) -> void
112
+
113
+ # A process benchmark's samples.
114
+ def measure_process: (String name, Result result) -> void
115
+
116
+ # The runs a process benchmark's sample takes, by its warm-up's.
117
+ def process_runs: (Array[[WorkerProcess::reply, WorkerProcess::reply]] floors) -> Integer
118
+
119
+ def warm: (String name, Integer n) -> void
120
+
121
+ # The seconds of samples whose median, no faster by STEADY_GAIN than
122
+ # the last's, end a worker's warm-up, without --warm.
123
+ STEADY: Float
124
+ STEADY_GAIN: Float
125
+ STEADY_WINDOWS: Integer
126
+
127
+ # Samples a worker until it's steady, or it's +warm_until+.
128
+ def steady: (WorkerProcess worker, String name, Integer n, Float warm_until) -> void
129
+
130
+ # STEADY seconds of a worker's samples' CPU time, and when they ended.
131
+ def window: (WorkerProcess worker, String name, Integer n, Float warm_until) -> [Array[Metric::value], Float]
132
+
133
+ def judge: (String name, Integer n, Array[[WorkerProcess::reply, WorkerProcess::reply]] floors, Result result) -> void
134
+
135
+ # Whether a benchmark's timings are judged by process.
136
+ def by_process?: (String name) -> bool
137
+
138
+ # Judges each of +judged+ over workers, in rounds of a sample from
139
+ # every worker.
140
+ def judge_processes: (String name, Integer n, Array[Metric::spec] judged, Result result) -> void
141
+
142
+ # The most rounds of +k+ workers' pairs.
143
+ def rounds: (Integer k) -> Integer
144
+
145
+ # Each worker's median, by version.
146
+ def medians: (Hash[String, Array[Array[Metric::value]]] values) -> Hash[String, Array[Metric::value]]
147
+
148
+ # The baseline's medians, at least 1, and the candidate's.
149
+ def clamped: (Hash[String, Array[Metric::value]] each) -> [Array[Metric::value], Array[Metric::value]]
150
+
151
+ # What each worker's medians say against the spec's limit.
152
+ def process_verdict: (Hash[String, Array[Metric::value]] each, Metric::spec spec) -> Stats::verdict
153
+
154
+ # Whether both versions' CPU time is below its floor.
155
+ def below_cpu_floor?: (Array[[Worker::sampled, Worker::sampled]] floors) -> bool
156
+
157
+ # Whether one version's samples are above a spec's floors.
158
+ def above_floors?: (Array[Hash[String, Metric::value]] samples, Metric::spec spec) -> bool
159
+
160
+ def limit: (Metric::spec spec) -> Float
161
+
162
+ def verdict: (Array[Float] ratios, Metric::spec spec) -> Stats::verdict
163
+
164
+ # The verdicts that decide a measure at the end of a round, and after
165
+ # any other pair.
166
+ DECISIVE: Hash[bool, Array[Stats::verdict]]
167
+
168
+ # Whether +verdict+ decides a measure, at the end of a round or not.
169
+ def decided?: (Stats::verdict verdict, bool round) -> bool
170
+
171
+ def calibrate: (String name, Integer target, Integer n) -> Integer
172
+
173
+ # The most iterations whose allocations fit HEAP_CAP (infinite when it
174
+ # allocated nothing).
175
+ def most_iterations: (Integer n, Integer heap) -> (Integer | Float)
176
+
177
+ # The +index+th pair: [baseline's reply, candidate's].
178
+ def pair: (String name, Integer n, Integer index, ?runs: Integer, ?count: bool) -> [WorkerProcess::reply, WorkerProcess::reply]
179
+
180
+ # A sample from a baseline worker and from a candidate worker: [baseline's reply, candidate's].
181
+ def sampled: (String name, Integer n, WorkerProcess base, WorkerProcess candidate, base_first: bool, ?runs: Integer, ?count: bool) -> [WorkerProcess::reply, WorkerProcess::reply]
182
+
183
+ def count: (String name, Integer n, Result result) -> void
184
+
185
+ # The samples a count takes.
186
+ def counts: () -> Integer
187
+
188
+ # Each counted measure, by each worker's fewest, and how much more
189
+ # the candidate's are at least.
190
+ def count_by_process: (String name, Integer n, Result result) -> void
191
+
192
+ # Keeps each count of a worker's sample where it's that worker's
193
+ # fewest so far.
194
+ def fewest!: (Hash[String, Hash[String, Hash[Integer, Metric::value]]] fewest, String side, Integer worker, WorkerProcess::reply sample) -> void
195
+
196
+ def peak_memory: (String name, Integer n, Result result) -> void
197
+
198
+ def fresh: [T] (String side) { (WorkerProcess worker) -> T } -> T
199
+
200
+ def monotonic: () -> Float
201
+ end
202
+ end
data/sig/duel/lock.rbs CHANGED
@@ -7,13 +7,20 @@ module Duel
7
7
 
8
8
  # Runs the block holding +dir+'s lock. Fails, naming the run that
9
9
  # holds it, if another does.
10
- def self.hold: [T] (String dir) { () -> T } -> T
10
+ def self.hold: [T] (String dir, ?windows: bool) { () -> T } -> T
11
11
 
12
12
  # The lock file at +path+, locked: the one there now.
13
13
  def self.acquire: (String path, String dir) -> File
14
14
 
15
15
  # The directories, +dir+ and those it's in, that aren't there yet,
16
16
  # deepest first.
17
+ # The pid another run wrote in its lock, or "".
18
+ HELD: Array[String]
19
+
20
+ def self.lock: (File file) -> (Integer | false)
21
+
22
+ def self.whose: (File file) -> String
23
+
17
24
  def self.missing: (String dir) -> Array[String]
18
25
 
19
26
  # Removes the empty directories in +dir+, then +dir+, then those of
data/sig/duel/memory.rbs CHANGED
@@ -10,7 +10,7 @@ module Duel
10
10
  ROOT: String
11
11
 
12
12
  # The bytes available, or nil where Duel can't tell.
13
- def self.available: (?root: String, ?vm_stat: ^() -> String?) -> Integer?
13
+ def self.available: (?root: String, ?vm_stat: ^() -> String?, ?windows: ^() -> Integer?) -> Integer?
14
14
 
15
15
  # MemAvailable, at most what the cgroup leaves, or nil.
16
16
  def self.linux: (String root) -> Integer?
data/sig/duel/metric.rbs CHANGED
@@ -30,7 +30,7 @@ module Duel
30
30
 
31
31
  # A measure's settings, every one, resolved (see Metric.resolve).
32
32
  type resolved = { kind: kind, unit: String?, plural: String?, floor: value, cpu_floor: value, limit: Float?, unit_ns: value,
33
- sizes_samples: bool, across: bool, tolerance: value, allowance: value }
33
+ sizes_samples: bool, across: bool, tolerance: value, allowance: value, ?calibrate: bool }
34
34
 
35
35
  # No measure's settings changed.
36
36
  # @api private
@@ -75,10 +75,6 @@ module Duel
75
75
  # within +tolerance+ an iteration and +allowance+ a sample.
76
76
  def self.within?: (value more, Integer n, tolerance: value, allowance: value) -> bool
77
77
 
78
- # Each measure's kind, by name.
79
- # @api private
80
- def self.kinds: () -> Hash[String, kind]
81
-
82
78
  # Fails unless +settings+ (a measure's) are settings there are, with a
83
79
  # kind there is.
84
80
  # @api private
@@ -90,7 +86,7 @@ module Duel
90
86
 
91
87
  # A measure's settings: those given, and the rest as by default.
92
88
  # @api private
93
- def self.resolve: (Hash[Symbol, untyped] given) -> resolved
89
+ def self.resolve: (Hash[Symbol, untyped] given) -> Metric::resolved
94
90
 
95
91
  # Its measures as the runner learns them, with +overrides+ by name.
96
92
  # @api private
@@ -239,6 +235,11 @@ module Duel
239
235
  # (Its measures as Config#metric takes them: from keywords too.)
240
236
  def self.define: (Hash[untyped, untyped] measures, (^() -> read[Metric::value, untyped])? read) -> singleton(Snapshot)
241
237
 
238
+ # A measure's settings, resolved, and whether its reading's cost is
239
+ # learned and taken away (calibrate).
240
+ # @api private
241
+ def self.resolve: (Hash[Symbol, untyped] given) -> Metric::resolved
242
+
242
243
  # Sets what it measures and how it reads them, and returns it.
243
244
  # @api private
244
245
  def self.reading: (Hash[untyped, untyped] measures, ^() -> read[Metric::value, untyped] read) -> singleton(Snapshot)
@@ -299,12 +300,54 @@ module Duel
299
300
  def grew: (totals[Metric::value] before, String name) -> Metric::value
300
301
  end
301
302
 
302
- # CPU time in nanoseconds: the benchmark thread's, or the process's.
303
+ # CPU time in nanoseconds: the benchmark thread's, or the process's
304
+ # (on Windows, a Float: see CycleClock).
303
305
  # @api private
304
306
  module Clock
305
- def self.thread: () -> Integer
307
+ def self.thread: () -> (Integer | Float)
306
308
 
307
- def self.process: () -> Integer
309
+ def self.process: () -> (Integer | Float)
310
+ end
311
+
312
+ # CPU time on Windows: the cycles charged to the thread or the
313
+ # process, in nanoseconds at the run's rate.
314
+ # @api private
315
+ module CycleClock
316
+ RATE: String
317
+ CALIBRATION_NS: Integer
318
+ CALIBRATIONS: Integer
319
+
320
+ interface _Counter
321
+ def read: () -> Float
322
+ end
323
+
324
+ # The environment (ENV, or a Hash in its place).
325
+ interface _Env
326
+ def []: (String name) -> String?
327
+
328
+ def []=: (String name, String? value) -> String?
329
+ end
330
+
331
+ self.@thread: Native::Windows::Cycles
332
+ self.@process: Native::Windows::Cycles
333
+ self.@rate: Float
334
+
335
+ def self.thread: () -> Float
336
+
337
+ def self.process: () -> Float
338
+
339
+ # +cycles+, in whole nanoseconds.
340
+ def self.ns: (Float cycles) -> Integer
341
+
342
+ # The cycles in a nanosecond: +env+'s, or else measured, and set
343
+ # there.
344
+ def self.rate: (?env: _Env) -> Float
345
+
346
+ # Measures the rate on Windows, before a run starts its workers.
347
+ def self.prepare: (?windows: bool) -> Float?
348
+
349
+ # The most cycles +cycles+ counted in a nanosecond of +clock+'s.
350
+ def self.calibrate: (?cycles: _Counter, ?clock: ^() -> Integer) -> Float
308
351
  end
309
352
 
310
353
  # Bytes allocated, by the benchmark thread or by every thread (JRuby).
@@ -322,7 +365,7 @@ module Duel
322
365
  # CPU time, in nanoseconds.
323
366
  class CPU < Metric
324
367
  @clock: :thread | :process
325
- @started: Integer
368
+ @started: Integer | Float
326
369
 
327
370
  def start_sample: (Sample sample) -> void
328
371
 
data/sig/duel/native.rbs CHANGED
@@ -9,16 +9,14 @@ module Duel
9
9
  end
10
10
 
11
11
  FIDDLE: bool
12
- OS: String
13
- CPU: String
14
12
  UINT64: Integer
15
13
 
16
- # A C function of the process's own libraries, by name, taking and
17
- # returning Fiddle types (:INT, :LONG, :VOIDP...).
18
14
  # Loads Fiddle, as the first C function is made.
19
15
  def self.require_fiddle: () -> bool
20
16
 
21
- def self.function: (String name, Array[Symbol] args, Symbol returns) -> _Function
17
+ # A C function of the process's own libraries (or of +library+), by
18
+ # name, taking and returning Fiddle types (:INT, :LONG, :VOIDP...).
19
+ def self.function: (String name, Array[Symbol] args, Symbol returns, ?library: String?) -> _Function
22
20
 
23
21
  # Instructions retired in user space, from the CPU's counters.
24
22
  class Counter
@@ -68,6 +66,9 @@ module Duel
68
66
 
69
67
  def self.open: (?platform: String, ?rusage: _Function?) -> MacOS?
70
68
 
69
+ # The same call, for resident memory alone.
70
+ def self.memory: (?platform: String, ?rusage: _Function?) -> MacOS?
71
+
71
72
  def initialize: (_Function rusage) -> void
72
73
 
73
74
  def read: () -> Integer
@@ -79,6 +80,101 @@ module Duel
79
80
  def field: (Integer offset) -> Integer
80
81
  end
81
82
 
83
+ # Windows: this process's working set, and the memory available, from
84
+ # kernel32.
85
+ class Windows
86
+ KERNEL32: String
87
+ CURRENT_PROCESS: Integer
88
+ COUNTERS: Integer
89
+ PEAK_WORKING_SET: Integer
90
+ WORKING_SET: Integer
91
+ STATUS: Integer
92
+ AVAILABLE: Integer
93
+
94
+ @memory_info: _Function
95
+ @handle: Integer
96
+ # The struct K32GetProcessMemoryInfo fills in, in place.
97
+ @buffer: String
98
+
99
+ def self.open: (?platform: String, ?memory_info: _Function?) -> Windows?
100
+
101
+ # The bytes of physical memory available, or nil.
102
+ def self.available: (?platform: String, ?status: _Function?) -> Integer?
103
+
104
+ def initialize: (_Function memory_info, ?handle: Integer) -> void
105
+
106
+ # The bytes in its working set, or nil.
107
+ def resident: () -> Integer?
108
+
109
+ # The most bytes its working set has held, or nil.
110
+ def peak: () -> Integer?
111
+
112
+ # The CPU cycles charged to this thread or this process, read
113
+ # without allocating.
114
+ class Cycles
115
+ CURRENT_THREAD: Integer
116
+ QUERIES: Hash[:thread | :process, [String, Integer]]
117
+
118
+ @handle: Integer
119
+ @query: _Function
120
+ # Where the call writes the count.
121
+ @count: Fiddle::Pointer
122
+ @address: Integer
123
+
124
+ def initialize: (:thread | :process scope, ?query: _Function?, ?handle: Integer?) -> void
125
+
126
+ # The count, as a Float.
127
+ def read: () -> Float
128
+ end
129
+
130
+ # A child process, by a handle of its own: what it took, once it
131
+ # has ended.
132
+ class Spawned
133
+ QUERY: Integer
134
+
135
+ @handle: Integer
136
+ @cycles: Cycles | _Reader
137
+ @memory: Windows
138
+ @close: _Function
139
+
140
+ interface _Reader
141
+ def read: () -> Float
142
+ end
143
+
144
+ # +pid+'s, or nil where it can't be opened.
145
+ def self.open: (Integer pid, ?open_process: _Function?) -> Spawned?
146
+
147
+ def initialize: (Integer handle, ?cycles: (Cycles | _Reader)?, ?memory_info: _Function?, ?close: _Function?) -> void
148
+
149
+ def cycles: () -> Float
150
+
151
+ def peak: () -> Integer?
152
+
153
+ def close: () -> Integer
154
+ end
155
+
156
+ private
157
+
158
+ def counter: (Integer offset) -> Integer?
159
+ end
160
+
161
+ # macOS: the calling thread's instructions, from thread_selfcounts.
162
+ class MacOSThread < Counter
163
+ THSC_CPI: Integer
164
+ SIZE: Integer
165
+
166
+ @selfcounts: _Function
167
+ # The struct thread_selfcounts fills in, in place.
168
+ @buffer: String
169
+
170
+ def self.open: (?platform: String, ?selfcounts: _Function?) -> MacOSThread?
171
+
172
+ def initialize: (_Function selfcounts) -> void
173
+
174
+ # The count, or nil where the call fails.
175
+ def read: () -> Integer?
176
+ end
177
+
82
178
  # A child process of this one, waited for.
83
179
  module Child
84
180
  RUSAGE_SIZE: Integer
@@ -88,17 +184,21 @@ module Duel
88
184
  # Waits for the child +pid+: its exit status (or nil), the signal
89
185
  # that killed it (or nil), and its peak memory in bytes (or nil).
90
186
  def self.wait: (Integer pid, ?fiddle: bool, ?platform: String, ?wait4: _Function?) -> [Integer?, Integer?, Integer?]
187
+
188
+ # How a child that was waited for ended, from its +status+.
189
+ def self.ended: (Process::Status status) -> [Integer?, Integer?, nil]
91
190
  end
92
191
 
93
192
  # This process's resident memory in bytes, or nil where it can't tell.
94
193
  module Memory
95
194
  STATUS: String
96
- self.@macos: MacOS?
195
+ self.@reader: (MacOS | Windows)?
97
196
 
98
- # macOS's counter, opened as resident memory is first read, or nil.
99
- def self.macos_counter: () -> MacOS?
197
+ # macOS's counter, or Windows's reader, opened as resident memory is
198
+ # first read, or nil.
199
+ def self.opened_reader: () -> (MacOS | Windows)?
100
200
 
101
- def self.resident: (?status: String, ?macos: MacOS?) -> Integer?
201
+ def self.resident: (?status: String, ?reader: (MacOS | Windows)?) -> Integer?
102
202
 
103
203
  def self.used: () -> Integer?
104
204
 
@@ -0,0 +1,13 @@
1
+ module Duel
2
+ # What this process runs on, for what differs by it.
3
+ # @api private
4
+ module Platform
5
+ OS: String
6
+ CPU: String
7
+ WINDOWS_OS: Regexp
8
+ WINDOWS: bool
9
+ CRUBY: bool
10
+ JRUBY: bool
11
+ JRUBY_ON_WINDOWS: bool
12
+ end
13
+ end
@@ -9,19 +9,18 @@ module Duel
9
9
  # What the process of its own reports of a run.
10
10
  type ended = { "cpu" => Integer, "peak" => Integer?, "failed" => String? }
11
11
 
12
- # The lines of its output a failure shows.
13
- LOG_LINES: Integer
14
12
 
15
13
  @label: String
16
14
  @env: Hash[String, String?]
17
15
  @chdir: String
18
16
  @log: String
19
17
  @timeout: Float
20
- @pid: Integer?
18
+ @child: Spawn::Child?
21
19
  @requests: IO
22
20
  @replies: IO
21
+ @starter: Spawn::starter
23
22
 
24
- def initialize: (String label, env: Hash[String, String?], chdir: String, log: String, timeout: Float) -> void
23
+ def initialize: (String label, env: Hash[String, String?], chdir: String, log: String, timeout: Float, ?starter: Spawn::starter) -> void
25
24
 
26
25
  # The fastest of +samples+: the least CPU time and peak memory.
27
26
  def self.fastest: (Array[sampled] samples) -> sampled
@@ -30,20 +29,19 @@ module Duel
30
29
  def run: (Array[String] command) -> sampled
31
30
 
32
31
  # Ends the Ruby process of its own, if it started.
33
- def stop: () -> void
32
+ def stop: (?wait: Numeric) -> void
34
33
 
35
34
  # Runs a process for each line of +input+, and reports each on
36
35
  # +output+.
37
- def self.main: (String spec, ?input: IO, ?output: IO) -> void
36
+ def self.main: (?input: IO, ?output: IO) -> void
38
37
 
39
38
  # Runs +command+ once, and returns what it took.
40
- def self.once: (Array[String] command, Hash[String, String?] env, String chdir, String log) -> ended
39
+ def self.once: (Array[String] command, Hash[String, String?] env, String chdir, String log, ?windows: bool, ?starter: Spawn::starter) -> ended
41
40
 
42
41
  # The CPU time of the children waited for so far, in nanoseconds.
43
42
  def self.cpu: () -> Integer
44
43
 
45
- # How a process that failed ended.
46
- def self.why: (Integer? code, Integer? signal) -> String
44
+ STOP_WAIT: Integer
47
45
 
48
46
  private
49
47
 
@@ -12,9 +12,17 @@ module Duel
12
12
  # @api private
13
13
  STOP_WAIT: Integer
14
14
 
15
- # The lines of its log a failure shows.
15
+ # A process #spawn started: its program, its log, the signal that
16
+ # stops it, and its Spawn::Child.
16
17
  # @api private
17
- LOG_LINES: Integer
18
+ class Spawned < Data
19
+ attr_reader program: String
20
+ attr_reader log: String
21
+ attr_reader stop_signal: String
22
+ attr_reader child: Spawn::Child
23
+
24
+ def self.new: (program: String, log: String, stop_signal: String, child: Spawn::Child) -> instance
25
+ end
18
26
 
19
27
  # What a cache key may be.
20
28
  # @api private
@@ -31,12 +39,19 @@ module Duel
31
39
  @env: Hash[String, String?]
32
40
  @timeout: Float
33
41
  @cache: String
34
- # Each process's program, log and stop signal, by pid.
35
- @processes: Hash[Integer, [String, String, String]]
42
+ # The processes #spawn started.
43
+ @processes: Array[Spawned]
44
+ @starter: Spawn::starter
36
45
  @stops: Array[^() -> void]
37
46
 
38
47
  # +env+ with +vars+ too: two prepare blocks that set a variable differently
39
48
  # fail.
49
+ # Runs each prepare block, given a Resource of its own (kept by the
50
+ # block given), and returns +env+ with what each returned.
51
+ # @api private
52
+ def self.prepare: (Array[Config::prepare] blocks, String dir, String name, String root, env: Hash[String, String?],
53
+ ruby: String, timeout: Float, cache: String, ?so_far: bool) { (Resource) -> void } -> Hash[String, String?]
54
+
40
55
  # @api private
41
56
  def self.environment: (String name, Hash[String, String?] env, Hash[String, String?] vars) -> Hash[String, String?]
42
57
 
@@ -66,18 +81,23 @@ module Duel
66
81
 
67
82
  # @api private
68
83
  def initialize: (String dir, String name, String root, timeout: Float, cache: String, ?ruby: String,
69
- ?env: Hash[String, String?]) -> void
84
+ ?env: Hash[String, String?], ?starter: Spawn::starter) -> void
70
85
 
71
86
  # A path in its directory.
72
87
  def path: (String file) -> String
73
88
 
89
+ # A port of 127.0.0.1's that's free, for a server of its own to listen
90
+ # on.
91
+ def port: () -> Integer
92
+
74
93
  # A directory built once, by the block, for every worker of this run
75
94
  # and later ones. The first that asks for +key+ builds it.
76
95
  def cached: (String key) { (String dir) -> void } -> String
77
96
 
78
97
  # Starts a process (as Process.spawn takes it), its output added to a
79
98
  # log in the directory (+log+.log: by default, its program's name), and
80
- # stopped with the resource by +stop_signal+. Returns its pid.
99
+ # stopped with the resource by +stop_signal+ (on Windows, killed).
100
+ # Returns its pid.
81
101
  def spawn: (*untyped command, ?log: String?, ?stop_signal: String, **untyped options) -> Integer
82
102
 
83
103
  # Runs a command to its end, logged as #spawn's is. Fails, showing its
@@ -98,6 +118,7 @@ module Duel
98
118
  # @api private
99
119
  def stop: () -> void
100
120
 
121
+
101
122
  private
102
123
 
103
124
  # Builds +dir+ in a directory of its own, then renames it into place.
@@ -106,9 +127,7 @@ module Duel
106
127
  # The log a command's output goes to.
107
128
  def log_path: (Array[untyped] command, String? name) -> String
108
129
 
109
- def start: (Array[untyped] command, String log, Hash[Symbol, untyped] options) -> Integer
110
-
111
- def end_process: (Integer pid, String signal) -> void
130
+ def start: (Array[untyped] command, String log, Hash[Symbol, untyped] options) -> Spawn::Child
112
131
 
113
132
  def monotonic: () -> Float
114
133
  end