:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { Counter, register } from 'prom-client'
import {
configureEventLoopYield,
getEventLoopYieldThresholdMs,
yieldEach,
yieldEventLoopIfNeeded,
} from './event-loop-yield'
function busyWaitMs(ms: number): void {
const start = performance.now()
while (performance.now() - start < ms) {
// spin — the whole point is to block the event loop
}
}
async function getYieldCount(caller: string, waited: 'true' | 'false'): Promise<number> {
const metric = register.getSingleMetric('event_loop_yield_total') as Counter | undefined
if (!metric) {
return 0
}
const data = await metric.get()
const sample = data.values.find((v) => v.labels.caller === caller && v.labels.waited === waited)
return sample?.value ?? 0
}
describe('event-loop-yield', () => {
let originalThreshold: number
beforeEach(() => {
jest.useRealTimers()
originalThreshold = getEventLoopYieldThresholdMs()
})
afterEach(async () => {
configureEventLoopYield(originalThreshold)
// Drain the singleton state — any in-flight setTimeout(0) needs to fire
// so the next test starts with a fresh state.
await new Promise((resolve) => setTimeout(resolve, 0))
})
describe('configuration', () => {
it('uses the configured default threshold', () => {
configureEventLoopYield(123)
expect(getEventLoopYieldThresholdMs()).toBe(123)
})
})
describe('yieldEventLoopIfNeeded', () => {
it('returns the wrapped function result', async () => {
const result = await yieldEventLoopIfNeeded('test', () => 42)
expect(result).toBe(42)
})
it('awaits an async wrapped function', async () => {
const result = await yieldEventLoopIfNeeded('test', async () => {
await new Promise((resolve) => setTimeout(resolve, 0))
return 'ok'
})
expect(result).toBe('ok')
})
it('still yields if the wrapped function throws', async () => {
configureEventLoopYield(20)
// Prime accumulated state so the next call's after-yield trips the threshold.
await yieldEventLoopIfNeeded('test', () => busyWaitMs(40))
const before = await getYieldCount('test', 'true')
await expect(
yieldEventLoopIfNeeded('test', () => {
busyWaitMs(40)
throw new Error('boom')
})
).rejects.toThrow('boom')
const after = await getYieldCount('test', 'true')
// The wrapper should have yielded at least once even though fn threw.
expect(after).toBeGreaterThan(before)
})
it('does not actually yield when accumulated work is below the threshold', async () => {
configureEventLoopYield(10_000)
const before = await getYieldCount('test', 'true')
await yieldEventLoopIfNeeded('test', () => busyWaitMs(20))
const after = await getYieldCount('test', 'true')
expect(after - before).toBe(0)
})
it('actually yields when accumulated work crosses the threshold', async () => {
configureEventLoopYield(20)
const before = await getYieldCount('test', 'true')
await yieldEventLoopIfNeeded('test', () => busyWaitMs(40))
const after = await getYieldCount('test', 'true')
// Either the before- or after-yield should have crossed the threshold.
expect(after - before).toBeGreaterThan(0)
})
it('does not block the loop across many CPU-bound calls', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] })
let elapsed = 0
const now = jest.spyOn(performance, 'now').mockImplementation(() => elapsed)
configureEventLoopYield(20)
let longestDelay = 0
let completed = 0
let lastTick = performance.now()
const interval = setInterval(() => {
const now = performance.now()
longestDelay = Math.max(longestDelay, now - lastTick)
lastTick = now
}, 1)
try {
const blockMs = 30
for (let i = 0; i < 10; i++) {
const call = yieldEventLoopIfNeeded('test', () => {
elapsed += blockMs
}).then(() => {
completed += 1
})
await new Promise((resolve) => setImmediate(resolve))
expect(completed).toBe(i)
await jest.advanceTimersByTimeAsync(1)
await call
expect(completed).toBe(i + 1)
}
// 10 * 30 = 300ms total blocking. With yielding, longestDelay
// should be close to one block + scheduling jitter. (If yielding
// were broken, this would be ~300ms.)
expect(longestDelay).toBe(blockMs)
} finally {
clearInterval(interval)
await jest.runAllTimersAsync()
now.mockRestore()
jest.useRealTimers()
}
})
})
describe('parallel callers', () => {
it('keeps a setInterval making progress while two parallel workers are busy', async () => {
// Two parallel producers in tight async loops. Without yielding, the
// setInterval observer would be starved for the full duration.
configureEventLoopYield(30)
const blockMs = 40
const iterations = 5
const workers = 2
const totalBlockingWork = blockMs * iterations * workers // = 400ms
let longestDelay = 0
let intervalTickCount = 0
let lastTick = performance.now()
const interval = setInterval(() => {
const now = performance.now()
longestDelay = Math.max(longestDelay, now - lastTick)
lastTick = now
intervalTickCount += 1
}, 0)
try {
const worker = async (id: string) => {
for (let i = 0; i < iterations; i++) {
await yieldEventLoopIfNeeded(id, () => busyWaitMs(blockMs))
}
}
await Promise.all([worker('worker-a'), worker('worker-b')])
} finally {
clearInterval(interval)
}
expect(longestDelay).toBeLessThan(totalBlockingWork / 2)
// We should have observed at least one interval tick fire while the
// workers were busy (otherwise we don't know yielding actually happened).
expect(intervalTickCount).toBeGreaterThan(1)
})
it('serialized callers via promise chain keep the loop unblocked', async () => {
// To prove the helper actually protects the loop end-to-end (matching
// hog-exec.test.ts's longestDelay bound), callers must be serialized
// so the setTimeout(0) macrotask can fire between them.
const blockMs = 100
const numberOfCallers = 10
configureEventLoopYield(blockMs)
let longestDelay = 0
let lastTick = performance.now()
const interval = setInterval(() => {
const now = performance.now()
longestDelay = Math.max(longestDelay, now - lastTick)
lastTick = now
}, 0)
try {
let chain: Promise<void> = Promise.resolve()
for (let i = 0; i < numberOfCallers; i++) {
chain = chain.then(() => yieldEventLoopIfNeeded(`caller-${i}`, () => busyWaitMs(blockMs)))
}
await chain
await new Promise((resolve) => setTimeout(resolve, 1))
// With serialization, the setTimeout fires between each block,
// so longestDelay should be ~ one block + scheduling jitter.
expect(longestDelay).toBeLessThan(blockMs * 2.5)
} finally {
clearInterval(interval)
}
})
it('does not unconditionally yield — fast callers below the threshold do not yield', async () => {
// A caller that does no sync work should not yield (most of the
// time). Even when sharing state with a slow caller that does yield,
// fast callers should mostly count as "not waited".
configureEventLoopYield(20)
const slowCaller = async (): Promise<void> => {
for (let i = 0; i < 3; i++) {
await yieldEventLoopIfNeeded('slow', () => busyWaitMs(40))
}
}
const fastCaller = async (): Promise<void> => {
for (let i = 0; i < 6; i++) {
await yieldEventLoopIfNeeded('fast', () => {})
}
}
const beforeSlowWaited = await getYieldCount('slow', 'true')
const beforeFastNot = await getYieldCount('fast', 'false')
await Promise.all([slowCaller(), fastCaller()])
const afterSlowWaited = await getYieldCount('slow', 'true')
const afterFastNot = await getYieldCount('fast', 'false')
// At least one slow call must have yielded.
expect(afterSlowWaited - beforeSlowWaited).toBeGreaterThan(0)
// At least one fast call must NOT have yielded.
expect(afterFastNot - beforeFastNot).toBeGreaterThan(0)
})
})
describe('yieldEach', () => {
it('calls fn for every item in order with the right index', async () => {
const items = ['a', 'b', 'c', 'd']
const seen: Array<[string, number]> = []
await yieldEach('test', items, (item, i) => {
seen.push([item, i])
})
expect(seen).toEqual([
['a', 0],
['b', 1],
['c', 2],
['d', 3],
])
})
it('awaits async fn before moving on', async () => {
const order: string[] = []
await yieldEach('test', [1, 2, 3], async (item) => {
order.push(`start-${item}`)
await new Promise((resolve) => setTimeout(resolve, 0))
order.push(`end-${item}`)
})
expect(order).toEqual(['start-1', 'end-1', 'start-2', 'end-2', 'start-3', 'end-3'])
})
it('actually yields the event loop during a CPU-bound batch', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] })
let elapsed = 0
const now = jest.spyOn(performance, 'now').mockImplementation(() => elapsed)
configureEventLoopYield(20)
const seen: number[] = []
try {
const batch = yieldEach('test', [0, 1], (item) => {
seen.push(item)
elapsed += 30
})
await new Promise((resolve) => setImmediate(resolve))
expect(seen).toEqual([0])
await jest.advanceTimersByTimeAsync(1)
await batch
expect(seen).toEqual([0, 1])
} finally {
await jest.runAllTimersAsync()
now.mockRestore()
jest.useRealTimers()
}
})
it('works on ArrayLike values, not just real arrays', async () => {
const arrayLike: ArrayLike<string> = { 0: 'x', 1: 'y', 2: 'z', length: 3 }
const seen: string[] = []
await yieldEach('test', arrayLike, (item) => {
seen.push(item)
})
expect(seen).toEqual(['x', 'y', 'z'])
})
it('handles empty arrays gracefully', async () => {
const seen: string[] = []
await yieldEach('test', [], (item) => {
seen.push(item as string)
})
expect(seen).toEqual([])
})
})
})