Fair Share

Fair Share: two tenants, one upstream. The global ceiling is fair to REQUESTS - first come, first served - but tenant A brings 6 workers and tenant B brings 2, so "fair to requests" quietly means "A gets triple". Per-tenant ceilings under the global door restore fairness to TENANTS; resize keeps the idle tenant's share from stranding.

source on github

a real captured run

FAIR SHARE (global ceiling 4; A brings 6 workers, B brings 2)

  no shares, one door for all          A: 76   B: 24   (shares -/-)
  2/2 shares, same greedy A            A: 50   B: 48   (shares 2/2)
  B idle, static 2/2 shares            A: 50   B: 0    (shares 2/2)
  B idle, shares rebalanced 4/1        A: 94   B: 0    (shares 4/1)
  B returns, shares back to 2/2        A: 52   B: 47   (shares 2/2)

  phase 1 is the quiet outage: nothing errored, nothing paged - B
  simply got half its lanes because the door counts requests, not
  tenants. phase 2 buys tenant-fairness by composition: own share
  first, then the door. phase 3 is the tax static shares charge -
  B's idle lanes served nobody - and phases 4-5 are the round-9
  payoff: resize lends the idle share and takes it back, live,
  while the composition never changes shape. fairness is a policy;
  make it an object and it becomes an adjustable one.

source

# frozen_string_literal: true

# Fair Share: two tenants, one upstream. The global ceiling is fair to
# REQUESTS - first come, first served - but tenant A brings 6 workers
# and tenant B brings 2, so "fair to requests" quietly means "A gets
# triple". Per-tenant ceilings under the global door restore fairness
# to TENANTS; resize keeps the idle tenant's share from stranding.
#
#   bundle exec ruby examples/fair_share.rb
#
# Runs offline; watch B's number - it tells the whole story.

require class="s">"bundler/setup"
require class="s">"agentic"
require class="s">"async"

GLOBAL = 4
JOB = 0.01
PHASE = 0.24
WORKERS = {a: 6, b: 2}.freeze # A is greedy; B just wants its two lanes

global = Agentic:class="y">:RateLimit.new(GLOBAL)
share_a = Agentic:class="y">:RateLimit.new(2)
share_b = Agentic:class="y">:RateLimit.new(2)
tenant_a = share_a.and(global) # own share first, then the shared door
tenant_b = share_b.and(global)

served = Hash.new(0)

# A tenant is N worker fibers, each pushing as hard as its limiter allows
def run_tenants(served, plan)
  Sync do
    plan.flat_map { |key, (limit, workers)|
      workers.times.map {
        Async do
          deadline = Process.clock_gettime(Process:class="y">:CLOCK_MONOTONIC) + PHASE
          while Process.clock_gettime(Process:class="y">:CLOCK_MONOTONIC) < deadline
            limit.acquire {
              sleep(JOB)
              served[key] += 1
            }
          end
        end
      }
    }.each(&class="y">:wait)
  end
end

def phase(title, served, shares)
  before = served.dup
  yield
  puts format(class="s">"  %-36s A: %-4d B: %-4d (shares %s)",
    title, served[class="y">:a] - before[class="y">:a], served[class="y">:b] - before[class="y">:b], shares)
end

puts class="s">"FAIR SHARE (global ceiling #{GLOBAL}; A brings #{WORKERS[class="y">:a]} workers, B brings #{WORKERS[class="y">:b]})"
puts

# Phase 1 - no shares: the door is fair to requests, so the tenant
# with more workers takes proportionally more. B wants 2 lanes' worth
# and gets half of it.
phase(class="s">"no shares, one door for all", served, class="s">"-/-") do
  run_tenants(served, {a: [global, WORKERS[class="y">:a]], b: [global, WORKERS[class="y">:b]]})
end

# Phase 2 - 2/2 shares under the door: B reaches its full demand no
# matter how many workers A hires
phase(class="s">"2/2 shares, same greedy A", served, class="s">"2/2") do
  run_tenants(served, {a: [tenant_a, WORKERS[class="y">:a]], b: [tenant_b, WORKERS[class="y">:b]]})
end

# Phase 3 - B goes idle; static shares strand B's lanes
phase(class="s">"B idle, static 2/2 shares", served, class="s">"2/2") do
  run_tenants(served, {a: [tenant_a, WORKERS[class="y">:a]], b: [tenant_b, 0]})
end

# Phase 4 - same idle B, but the spare share is lent to A, live
share_a.resize(4)
share_b.resize(1)
phase(class="s">"B idle, shares rebalanced 4/1", served, class="s">"4/1") do
  run_tenants(served, {a: [tenant_a, WORKERS[class="y">:a]], b: [tenant_b, 0]})
end

# Phase 5 - B returns; the share comes back, live
share_a.resize(2)
share_b.resize(2)
phase(class="s">"B returns, shares back to 2/2", served, class="s">"2/2") do
  run_tenants(served, {a: [tenant_a, WORKERS[class="y">:a]], b: [tenant_b, WORKERS[class="y">:b]]})
end

puts
puts class="s">"  phase 1 is the quiet outage: nothing errored, nothing paged - B"
puts class="s">"  simply got half its lanes because the door counts requests, not"
puts class="s">"  tenants. phase 2 buys tenant-fairness by composition: own share"
puts class="s">"  first, then the door. phase 3 is the tax static shares charge -"
puts class="s">"  B's idle lanes served nobody - and phases 4-5 are the round-9"
puts class="s">"  payoff: resize lends the idle share and takes it back, live,"
puts class="s">"  while the composition never changes shape. fairness is a policy;"
puts class="s">"  make it an object and it becomes an adjustable one."