Documentation Index
Fetch the complete documentation index at: https://abxbus.archivebox.io/llms.txt
Use this file to discover all available pages before exploring further.
first short-circuits event completion once the first successful non-None / non-undefined result is available.
Lifecycle impact
- The first successful result wins (
None/undefined and errors do not win).
- In
serial handler mode, remaining handlers are skipped once a winner appears.
- In
parallel handler mode, in-flight losers are cancelled or aborted.
- Event completion resolves as soon as a winner is found (or all handlers fail).
Execution order example
import asyncio
from abxbus import BaseEvent, EventBus
class CompletionEvent(BaseEvent[str]):
pass
bus = EventBus(
'CompletionFirstBus',
event_handler_concurrency='parallel',
event_handler_completion='first',
)
state = {'slow_started': False, 'slow_cancelled': False}
async def fast_handler(_: CompletionEvent) -> str:
await asyncio.sleep(0.01)
return 'winner'
async def slow_handler(_: CompletionEvent) -> str:
state['slow_started'] = True
try:
await asyncio.sleep(0.5)
return 'slow'
except asyncio.CancelledError:
state['slow_cancelled'] = True
raise
bus.on(CompletionEvent, slow_handler)
bus.on(CompletionEvent, fast_handler)
event = bus.emit(CompletionEvent())
await event
value = await event.event_result(raise_if_any=False, raise_if_none=False)
assert value == 'winner'
assert state['slow_started'] is True
assert state['slow_cancelled'] is True
import { BaseEvent, EventBus } from 'abxbus'
import { z } from 'zod'
const CompletionEvent = BaseEvent.extend('CompletionEvent', { event_result_type: z.string() })
const bus = new EventBus('CompletionFirstBus', {
event_handler_concurrency: 'parallel',
event_handler_completion: 'first',
})
let slowStarted = false
let slowCompleted = false
const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
bus.on(CompletionEvent, async () => {
slowStarted = true
await delay(500)
slowCompleted = true
return 'slow'
})
bus.on(CompletionEvent, async () => {
await delay(10)
return 'winner'
})
const event = bus.emit(CompletionEvent({}))
await event.done()
if (event.event_result !== 'winner') throw new Error('expected first winner result')
if (!slowStarted) throw new Error('expected slow handler to start')
if (slowCompleted) throw new Error('slow handler should not complete before event resolves')
Notes
- This mode is useful for fallback chains and race-to-first-response patterns.
await event.first() also forces this mode for that event at call time.