duel 0.1.0

data/sig/duel/lock.rbs

@@ -0,0 +1,12 @@
+module Duel
+  # One run at a time in a project: an flock on tmp/duel/lock.
+  # @api private
+  module Lock
+    # An exclusive lock, or none if another holds it.
+    EXCLUSIVE: Integer
+
+    # Runs the block holding +dir+'s lock. Fails, naming the run that
+    # holds it, if another does.
+    def self.hold: [T] (String dir) { () -> T } -> T
+  end
+end

data/sig/duel/metric.rbs

@@ -0,0 +1,351 @@
+module Duel
+  # Something measured around every sample of every benchmark (see
+  # Config#metric). Subclasses name what they measure, and each one's
+  # settings, in +measures+, and say whether they can measure here with
+  # +available?+.
+  class Metric
+    # :ratio (noisy: judged on paired ratios with a confidence interval)
+    # or :counted (exact).
+    type kind = :ratio | :counted
+
+    # What a measure measures.
+    type value = Integer | Float
+
+    # What it's in: a symbol ("B", "ns"), or a word as [singular, plural].
+    type unit = String | [String, String]
+
+    # A measure's settings, as declared: any left out as by default. (+calibrate+:
+    # running totals' only, see Snapshot, and +skip+: Config#measure's only.)
+    type settings = { ?kind: kind, ?unit: unit?, ?floor: value, ?cpu_floor: value, ?limit: Float?, ?unit_ns: value,
+                      ?sizes_samples: bool, ?across: bool, ?tolerance: value, ?allowance: value, ?calibrate: bool, ?skip: bool }
+
+    # What #stop_sample returns: the measurement, a Hash of them (by name), or
+    # nil (none this time).
+    type measurement = value | Hash[String, value?] | nil
+
+    # A measure as the runner learns it.
+    # @api private
+    type spec = { "name" => String, "kind" => String, "unit" => String?, "plural" => String?, "floor" => value, "cpu_floor" => value, "limit" => Float?,
+                  "unit_ns" => value, "sizes_samples" => bool, "across" => bool, "tolerance" => value, "allowance" => value }
+
+    # A measure's settings, every one, resolved (see Metric.resolve).
+    type resolved = { kind: kind, unit: String?, plural: String?, floor: value, cpu_floor: value, limit: Float?, unit_ns: value,
+                      sizes_samples: bool, across: bool, tolerance: value, allowance: value }
+
+    # No measure's settings changed.
+    # @api private
+    UNCHANGED: Hash[String, Hash[Symbol, untyped]]
+
+    # No change to a measure's settings.
+    # @api private
+    NO_CHANGE: Hash[Symbol, untyped]
+
+    # Every setting there is.
+    # @api private
+    SETTINGS: Array[Symbol]
+
+    # A unit that's a word (or words), which needs its plural given.
+    # @api private
+    WORD: Regexp
+
+    # The units that are time, and the nanoseconds in each.
+    # @api private
+    TIME_UNITS: Hash[String, Integer]
+
+    @settings: Hash[String, resolved]?
+    @kinds: Hash[String, kind]?
+    @first_measure: String?
+    @only_measure: String?
+
+    # Whether it can measure here at all (false leaves it out).
+    def self.available?: () -> bool
+
+    # Whether reading it is costly (a round trip to a server, say), so it
+    # isn't paused around each iteration of a benchmark with an around
+    # block.
+    def self.costly?: () -> bool
+
+    # The metric's name in reports: by default, its class's, in snake case.
+    def self.metric_name: () -> String
+
+    # What it measures, by name.
+    def self.measures: () -> Hash[String, settings]
+
+    # Whether +more+ (what a count grew by, over +n+ iterations) is still
+    # within +tolerance+ an iteration and +allowance+ a sample.
+    def self.within?: (value more, Integer n, tolerance: value, allowance: value) -> bool
+
+    # Each measure's kind, by name.
+    # @api private
+    def self.kinds: () -> Hash[String, kind]
+
+    # Fails unless +settings+ (a measure's) are settings there are, with a
+    # kind there is.
+    # @api private
+    def self.check: (String name, Hash[Symbol, untyped] settings) -> void
+
+    # Each measure's settings, by name, every one filled in. (+overrides+:
+    # @api private.)
+    def self.settings: (?Hash[String, Hash[Symbol, untyped]] overrides) -> Hash[String, resolved]
+
+    # A measure's settings: those given, and the rest as by default.
+    # @api private
+    def self.resolve: (Hash[Symbol, untyped] given) -> resolved
+
+    # Its measures as the runner learns them, with +overrides+ by name.
+    # @api private
+    def self.specs: (?Hash[String, Hash[Symbol, untyped]] overrides) -> Array[spec]
+
+    # Each measure's settings, by name, with Config#measure's changes.
+    def settings: () -> Hash[String, resolved]
+
+    # @api private
+    def settings=: (Hash[String, resolved] settings) -> Hash[String, resolved]
+
+    # Each measure's kind, by name, as #settings has it.
+    # @api private
+    def kinds: () -> Hash[String, kind]
+
+    # The measure a measurement of one is: the first.
+    # @api private
+    def first_measure: () -> String
+
+    # A setting of +measure+: by default, of the one it measures.
+    def setting: (:kind key, ?String measure) -> kind
+               | (:unit | :plural key, ?String measure) -> String?
+               | (:floor | :cpu_floor | :unit_ns | :tolerance | :allowance key, ?String measure) -> value
+               | (:limit key, ?String measure) -> Float?
+               | (:sizes_samples | :across key, ?String measure) -> bool
+
+    # Whether +more+ (what +measure+'s count grew by, over +n+ iterations)
+    # is still within its tolerance and allowance.
+    def within?: (value more, Integer n, ?String measure) -> bool
+
+    # Sets up what it reads, once in each worker, before it measures
+    # anything.
+    def open: () -> void
+
+    # Begins measuring a sample (its benchmark, n).
+    def start_sample: (Sample sample) -> void
+
+    # Ends it, and returns the measurement, a Hash of them, or nil.
+    def stop_sample: () -> measurement
+
+    # Pauses it, for an untimed block, and returns what it measured so far.
+    def pause_sample: () -> measurement
+
+    # Resumes it after an untimed block.
+    def resume_sample: (Sample sample) -> void
+
+    # What it would say of the sample it last stopped: text, text by
+    # measure name, or nil.
+    def details: () -> (String | Hash[String, String] | nil)
+
+    # Lets go of what #open set up, when its worker ends.
+    def close: () -> void
+
+    private
+
+    # The one measure it measures. One that measures several (or none) fails.
+    def only_measure: () -> String
+  end
+
+  # A metric of running totals that its block reads (see Config#metric):
+  # a sample measures what they grew by, less what reading them adds to a
+  # counted one. Config#metric makes one, and it isn't made or subclassed
+  # otherwise.
+  class Snapshot < Metric
+    # Pairs of readings each worker takes to learn what reading costs.
+    # @api private
+    CALIBRATION: Integer
+
+    # Totals by name, each a T (Integer, say: see Config#metric). One it
+    # can't read this time is nil.
+    type totals[T] = Hash[String, T?]
+
+    # What a read block reads: the totals (a T, for one), or nil.
+    type read_totals[T] = T | totals[T] | nil
+
+    # What a read block returns: the totals, or them and what else was
+    # read with them (+C+: whatever its details block needs).
+    type read[T, C] = read_totals[T] | [read_totals[T], C]
+
+    # One reading: the totals, and what else was read with them (nil if
+    # nothing was).
+    class Reading[T, C] < Struct[untyped]
+      # The totals, by name.
+      attr_reader totals: totals[T]
+
+      # @api private
+      attr_writer totals: totals[T]
+
+      # What the block read with them, or nil.
+      attr_reader context: C
+
+      # @api private
+      attr_writer context: C
+
+      # @api private
+      def self.new: [T, C] (totals[T] totals, C context) -> Reading[T, C]
+
+      # The total named +name+ (it fails for one it couldn't read).
+      def total: (String name) -> T
+    end
+
+    # A sample's stretches: [started, stopped] readings.
+    type stretches[T, C] = Array[[Reading[T, C], Reading[T, C]]]
+
+    # What a sample's explained by: text, text by measure name, or nil.
+    type explained = String | Hash[String, String] | nil
+
+    # What explains a sample, given its stretches and the sample.
+    # @api private
+    type explainer[T, C] = ^(stretches[T, C] stretches, Sample sample) -> explained
+
+    # Running totals as Config#metric returns them: to explain them, typed
+    # by what their block read: the totals' T, and C with them.
+    interface _Explained[T, C]
+      # Explains each sample by the block, and returns the metric.
+      def details: () { (stretches[T, C] stretches, Sample sample) -> explained } -> _Explained[T, C]
+
+      # Runs the block in each worker as the metric is made, and returns
+      # the metric.
+      def open: () { () -> void } -> _Explained[T, C]
+
+      # Runs the block when each worker ends, and returns the metric.
+      def close: () { () -> void } -> _Explained[T, C]
+
+      # Says that reading it is costly, and returns the metric.
+      def costly: () -> _Explained[T, C]
+    end
+
+    # (Inside, the context is whatever the block gave: Config#metric types it.)
+    self.@measures: Hash[String, Metric::settings]
+    self.@read: ^() -> read[Metric::value, untyped]
+    self.@explainer: explainer[Metric::value, untyped]?
+    self.@opener: (^() -> void)?
+    self.@closer: (^() -> void)?
+    self.@costly: bool
+
+    @overhead: Hash[String, Metric::value]
+    @sample: Sample
+    @stretches: stretches[Metric::value, untyped]
+    @started: Reading[Metric::value, untyped]
+
+    attr_reader self.measures: Hash[String, Metric::settings]
+
+    # A Snapshot for +measures+, read by +read+.
+    # @api private
+    # (Its measures as Config#metric takes them: from keywords too.)
+    def self.define: (Hash[untyped, untyped] measures, (^() -> read[Metric::value, untyped])? read) -> singleton(Snapshot)
+
+    # Sets what it measures and how it reads them, and returns it.
+    # @api private
+    def self.reading: (Hash[untyped, untyped] measures, ^() -> read[Metric::value, untyped] read) -> singleton(Snapshot)
+
+    # Explains its samples by the block, and returns it.
+    def self.details: () { (stretches[Metric::value, untyped] stretches, Sample sample) -> explained } -> singleton(Snapshot)
+
+    # Runs the block in each worker as the metric is made, and returns it.
+    def self.open: () { () -> void } -> singleton(Snapshot)
+
+    # Runs the block when each worker ends, and returns it.
+    def self.close: () { () -> void } -> singleton(Snapshot)
+
+    # Whether reading it is costly.
+    def self.costly?: () -> bool
+
+    # Says that reading it is costly, and returns it.
+    def self.costly: () -> singleton(Snapshot)
+
+    # What explains a sample, or nil.
+    # @api private
+    def self.explainer: () -> explainer[Metric::value, untyped]?
+
+    # What opens it in a worker, or nil.
+    # @api private
+    def self.opener: () -> (^() -> void)?
+
+    # What closes it, or nil.
+    # @api private
+    def self.closer: () -> (^() -> void)?
+
+    # A Reading: the totals (those it measures, or it fails), and their
+    # context.
+    # @api private
+    def self.read: () -> Reading[Metric::value, untyped]
+
+    # Runs its open block, if it has one, then learns what reading its
+    # counted totals costs.
+    def open: () -> void
+
+    # A sample begins: its first stretch.
+    def start_sample: (Sample sample) -> void
+
+    # Another stretch of the same sample, after an untimed block.
+    def resume_sample: (Sample sample) -> void
+
+    def stop_sample: () -> totals[Metric::value]
+
+    # What its details block says of the sample it last stopped.
+    def details: () -> (String | Hash[String, String] | nil)
+
+    # Runs its close block, if it has one.
+    def close: () -> void
+
+    private
+
+    # What +name+'s total grew by in a reading after +before+.
+    def grew: (totals[Metric::value] before, String name) -> Metric::value
+  end
+
+  # CPU time in nanoseconds: the benchmark thread's, or the process's.
+  # @api private
+  module Clock
+    def self.thread: () -> Integer
+
+    def self.process: () -> Integer
+  end
+
+  # The built-in metrics: their measures are named ("cpu",
+  # "instructions", "allocations"), as Config#measure takes them.
+  # @api private
+  module Metrics
+    # CPU time, in nanoseconds.
+    class CPU < Metric
+      @clock: :thread | :process
+      @started: Integer
+
+      def start_sample: (Sample sample) -> void
+
+      def stop_sample: () -> Integer
+    end
+
+    # Instructions retired in user space, from the CPU's own counters.
+    class Instructions < Metric
+      self.@counter: Native::Counter?
+
+      @counter: Native::Counter
+      @counting: bool
+      @started: Integer
+
+      # This process's counter (see Native::Counter.open), or nil.
+      def self.counter: () -> Native::Counter?
+
+      def initialize: () -> void
+
+      def start_sample: (Sample sample) -> void
+
+      def stop_sample: () -> Integer?
+    end
+
+    # Ruby objects allocated (CRuby).
+    class Allocations < Metric
+      @started: Integer
+
+      def start_sample: (Sample _sample) -> void
+
+      def stop_sample: () -> Integer
+    end
+  end
+end

data/sig/duel/native.rbs

@@ -0,0 +1,98 @@
+module Duel
+  # What the operating system can tell about this process, through Fiddle:
+  # instructions retired (hardware counters) and resident memory.
+  # @api private
+  module Native
+    # A C function (a Fiddle::Function) returning an integer.
+    interface _Function
+      def call: (*untyped args) -> Integer
+    end
+
+    FIDDLE: bool
+    OS: String
+    CPU: String
+    UINT64: Integer
+
+    # A C function of the process's own libraries, by name, taking and
+    # returning Fiddle types (:INT, :LONG, :VOIDP...).
+    def self.function: (String name, Array[Symbol] args, Symbol returns) -> _Function
+
+    # Instructions retired in user space, from the CPU's counters.
+    class Counter
+      @scope: "thread" | "process"
+
+      # The best counter here, or nil.
+      def self.open: (?fiddle: bool) -> Counter?
+
+      # Whose instructions it counts.
+      attr_reader scope: "thread" | "process"
+
+      def initialize: ("thread" | "process" scope) -> void
+
+      def read: () -> Integer
+    end
+
+    # Linux: perf_event_open(2), counting this thread's instructions in
+    # user space.
+    class Linux < Counter
+      SYSCALL: Hash[String, Integer]
+      PERF_TYPE_HARDWARE: Integer
+      PERF_COUNT_HW_INSTRUCTIONS: Integer
+      FLAGS: Integer
+      PERF_FLAG_FD_CLOEXEC: Integer
+      ATTR_SIZE: Integer
+
+      @io: IO
+
+      def self.open: (?platform: String, ?cpu: String, ?syscall: _Function?) -> Linux?
+
+      def initialize: (IO io) -> void
+
+      def read: () -> Integer
+    end
+
+    # macOS: proc_pid_rusage(RUSAGE_INFO_V4), the process's instructions
+    # and resident memory.
+    class MacOS < Counter
+      RUSAGE_INFO_V4: Integer
+      SIZE: Integer
+      RESIDENT: Integer
+      INSTRUCTIONS: Integer
+
+      @rusage: _Function
+      # The struct proc_pid_rusage fills in, in place.
+      @buffer: String
+
+      def self.open: (?platform: String, ?rusage: _Function?) -> MacOS?
+
+      def initialize: (_Function rusage) -> void
+
+      def read: () -> Integer
+
+      def resident: () -> Integer
+
+      private
+
+      def field: (Integer offset) -> Integer
+    end
+
+    # A child process of this one, waited for.
+    module Child
+      RUSAGE_SIZE: Integer
+      MAXRSS: Integer
+      EINTR: Integer
+
+      # Waits for the child +pid+: its exit status (or nil), the signal
+      # that killed it (or nil), and its peak memory in bytes (or nil).
+      def self.wait: (Integer pid, ?fiddle: bool, ?platform: String, ?wait4: _Function?) -> [Integer?, Integer?, Integer?]
+    end
+
+    # This process's resident memory in bytes, or nil where it can't tell.
+    module Memory
+      STATM: String
+      MACOS: MacOS?
+
+      def self.resident: (?statm: String, ?macos: MacOS?) -> Integer?
+    end
+  end
+end

data/sig/duel/process_sample.rbs

@@ -0,0 +1,54 @@
+module Duel
+  # The runs of a process benchmark for one worker: each a fresh process,
+  # run by a Ruby process of its own, kept for the worker's life.
+  # @api private
+  class ProcessSample
+    # A process's sample, as a worker's has it.
+    type sampled = { "timed" => Hash[String, Integer], "counted" => Hash[String, Integer], "heap" => Integer, "peak" => Integer? }
+
+    # What the process of its own reports of a run.
+    type ended = { "cpu" => Integer, "peak" => Integer?, "failed" => String? }
+
+    # The lines of its output a failure shows.
+    LOG_LINES: Integer
+
+    @label: String
+    @env: Hash[String, String?]
+    @chdir: String
+    @log: String
+    @timeout: Float
+    @pid: Integer?
+    @requests: IO
+    @replies: IO
+
+    def initialize: (String label, env: Hash[String, String?], chdir: String, log: String, timeout: Float) -> void
+
+    # The fastest of +samples+: the least CPU time and peak memory.
+    def self.fastest: (Array[sampled] samples) -> sampled
+
+    # Runs +command+ once, and returns its sample.
+    def run: (Array[String] command) -> sampled
+
+    # Ends the Ruby process of its own, if it started.
+    def stop: () -> void
+
+    # Runs a process for each line of +input+, and reports each on
+    # +output+.
+    def self.main: (String spec, ?input: IO, ?output: IO) -> void
+
+    # Runs +command+ once, and returns what it took.
+    def self.once: (Array[String] command, Hash[String, String?] env, String chdir, String log) -> ended
+
+    # The CPU time of the children waited for so far, in nanoseconds.
+    def self.cpu: () -> Integer
+
+    # How a process that failed ended.
+    def self.why: (Integer? code, Integer? signal) -> String
+
+    private
+
+    def start: () -> void
+
+    def kill: () -> void
+  end
+end

data/sig/duel/profile.rbs

@@ -0,0 +1,64 @@
+module Duel
+  # Where a regression's time went: StackProf profiles of each version.
+  # @api private
+  class Profile
+    # A frame: its name, and its samples of its own and in total.
+    type frame = [String, Integer, Integer]
+
+    # A version's profile, as its worker reports it.
+    type profile = { "samples" => Integer, "frames" => Array[frame] }
+
+    # [frame, own, total]: what a frame gained, as a share of the
+    # baseline's samples.
+    type growth = [String, Float, Float]
+
+    # Its report: what grew, what garbage collection gained, and each
+    # version's profile (its top frames).
+    type report = { "grew" => Array[growth], "gc" => Float, "baseline" => profile, "candidate" => profile }
+
+    UNAVAILABLE: String
+    TOP: Integer
+    KEPT: Integer
+
+    # StackProf's frames for garbage collection.
+    GC: String
+    GC_FRAMES: Array[String]
+
+    @baseline: profile
+    @candidate: profile
+
+    # The frames that mark a benchmark's measured work: its iterations,
+    # what pauses them, and an iteration inside its around_iteration hooks.
+    ITERATE: String
+    PAUSE: String
+    ITERATION: String
+
+    # A version's profile, from StackProf's raw results: the benchmark's
+    # work, and garbage collection.
+    def self.of: (Hash[Symbol, untyped] results) -> profile
+
+    # Whether a sample, by its stack's frames' names, is kept.
+    def self.kept?: (Array[String] stack) -> bool
+
+    def initialize: (Hash[String, profile] profiles) -> void
+
+    # The TOP frames that gained the most samples of their own.
+    def grew: () -> Array[growth]
+
+    # What garbage collection gained, as a share of the baseline's samples.
+    def gc: () -> Float
+
+    def to_h: () -> report
+
+    private
+
+    def samples: () -> Float
+
+    # A profile's samples in garbage collection.
+    def collecting: (profile profile) -> Integer
+
+    def counts: (profile profile) -> Hash[String, [Integer, Integer]]
+
+    def trimmed: (profile profile) -> profile
+  end
+end

data/sig/duel/rake_task.rbs

@@ -0,0 +1,9 @@
+module Duel
+  # A rake task running `duel` with +args+:
+  #
+  #   Duel::RakeTask.new(:perf)
+  #   Duel::RakeTask.new(:perf_since_release, "--base", "last-release")
+  class RakeTask
+    def initialize: (?Symbol | String name, *String args) -> void
+  end
+end

data/sig/duel/resource.rbs

@@ -0,0 +1,106 @@
+module Duel
+  # What a prepare block (see Config#prepare) gets: a worker's, or a
+  # version's, own directory, and help running commands and starting a
+  # server there, and stopping it.
+  class Resource
+    # Seconds between looks while waiting.
+    # @api private
+    POLL: Float
+
+    # Seconds a process gets to end after its stop signal before it's
+    # killed.
+    # @api private
+    STOP_WAIT: Integer
+
+    # The lines of its log a failure shows.
+    # @api private
+    LOG_LINES: Integer
+
+    # What a cache key may be.
+    # @api private
+    KEY: Regexp
+
+    # The lock on building a cache.
+    # @api private
+    CACHE: Thread::Mutex
+
+    @name: String
+    @dir: String
+    @root: String
+    @ruby: String
+    @env: Hash[String, String?]
+    @timeout: Float
+    @cache: String
+    # Each process's program, log and stop signal, by pid.
+    @processes: Hash[Integer, [String, String, String]]
+    @stops: Array[^() -> void]
+
+    # +env+ with +vars+ too: two prepare blocks that set a variable differently
+    # fail.
+    # @api private
+    def self.environment: (String name, Hash[String, String?] env, Hash[String, String?] vars) -> Hash[String, String?]
+
+    # The worker it's for ("baseline-1", say).
+    attr_reader name: String
+
+    # The directory it has of its own.
+    attr_reader dir: String
+
+    # The tree of the version its worker runs.
+    attr_reader root: String
+
+    # The Ruby its version runs on.
+    attr_reader ruby: String
+
+    # What its commands get in their environment, under their own.
+    attr_reader env: Hash[String, String?]
+
+    # @api private
+    def initialize: (String dir, String name, String root, timeout: Float, cache: String, ?ruby: String,
+                     ?env: Hash[String, String?]) -> void
+
+    # A path in its directory.
+    def path: (String file) -> String
+
+    # A directory built once, by the block, for every worker of this run
+    # and later ones. The first that asks for +key+ builds it.
+    def cached: (String key) { (String dir) -> void } -> String
+
+    # Starts a process (as Process.spawn takes it), its output added to a
+    # log in the directory (+log+.log: by default, its program's name), and
+    # stopped with the resource by +stop_signal+. Returns its pid.
+    def spawn: (*untyped command, ?log: String?, ?stop_signal: String, **untyped options) -> Integer
+
+    # Runs a command to its end, logged as #spawn's is. Fails, showing its
+    # log, unless it succeeds.
+    def run: (*untyped command, ?log: String?, **untyped options) -> void
+
+    # Waits until the block is true: fails if a process spawned dies first,
+    # or the run's timeout passes.
+    def wait_until: () { () -> boolish } -> void
+
+    # Runs the block when the resource stops, before its processes do.
+    def at_stop: () { () -> void } -> void
+
+    # Fails, saying it's this resource that did, with the end of +log+.
+    def failed: (String message, ?log: String?) -> bot
+
+    # Stops it.
+    # @api private
+    def stop: () -> void
+
+    private
+
+    # Builds +dir+ in a directory of its own, then renames it into place.
+    def build: (String dir) { (String building) -> void } -> void
+
+    # The log a command's output goes to.
+    def log_path: (Array[untyped] command, String? name) -> String
+
+    def start: (Array[untyped] command, String log, Hash[Symbol, untyped] options) -> Integer
+
+    def end_process: (Integer pid, String signal) -> void
+
+    def monotonic: () -> Float
+  end
+end