Timeout Enforcement

Timeout controls operate at three levels:

Bus defaults (resolved on each bus at processing time when event-level values are unset)
Per-event overrides (applies to one emitted event instance)
Per-handler overrides (applies to one handler registration)

Repository example files:

Timeout types

1) Event timeout (`event_timeout`)

The outer execution budget for an event. This also acts as an upper cap for each handler run for that event.

2) Handler timeout (`event_handler_timeout` / `handler_timeout`)

A handler-specific timeout budget. The effective handler timeout is resolved from handler -> event -> bus, then capped by event_timeout when both are set.

3) Slow-warning thresholds (`event_slow_timeout`, `event_handler_slow_timeout`, `handler_slow_timeout`)

These emit warnings when work is taking longer than expected:

event_slow_timeout: warns when event processing is still running past the threshold.
event_handler_slow_timeout / handler_slow_timeout: warns when a handler run is still running past the threshold.

Slow thresholds are warnings, not forced cancellation.

Where to set each value

Level	Execution timeout fields	Slow-warning fields
Bus	`event_timeout`	`event_slow_timeout`, `event_handler_slow_timeout`
Event	`event_timeout`, `event_handler_timeout`	`event_slow_timeout`, `event_handler_slow_timeout`
Handler	`handler_timeout`	`handler_slow_timeout`

Bus-level defaults

Set default budgets and warning thresholds once when creating a bus.

Python
TypeScript

from abxbus import EventBus

bus = EventBus(
    'TimeoutBus',
    event_timeout=30.0,
    event_slow_timeout=10.0,
    event_handler_slow_timeout=3.0,
)

import { EventBus } from 'abxbus'

const bus = new EventBus('TimeoutBus', {
  event_timeout: 30,
  event_slow_timeout: 10,
  event_handler_slow_timeout: 3,
})

Event-level overrides

Set per-event values when emitting an event instance.

Python
TypeScript

from abxbus import BaseEvent

class WorkEvent(BaseEvent):
    pass

event = bus.emit(
    WorkEvent(
        event_timeout=8.0,
        event_handler_timeout=2.0,
        event_slow_timeout=4.0,
        event_handler_slow_timeout=1.0,
    )
)

import { BaseEvent } from 'abxbus'

const WorkEvent = BaseEvent.extend('WorkEvent', {})

const event = bus.emit(
  WorkEvent({
    event_timeout: 8,
    event_handler_timeout: 2,
    event_slow_timeout: 4,
    event_handler_slow_timeout: 1,
  })
)

Handler-level overrides

Set per-handler timeout and slow-warning overrides at registration time (or by updating the returned handler metadata).

Python
TypeScript

entry = bus.on(WorkEvent, slow_handler)
entry.handler_timeout = 1.5
entry.handler_slow_timeout = 0.5

bus.on(WorkEvent, slowHandler, {
  handler_timeout: 1.5,
  handler_slow_timeout: 0.5,
})

Precedence rules

Effective handler timeout

Resolve handler timeout source:
- handler_timeout (handler level)
- else event_handler_timeout (event level)
- else bus event_timeout
Apply event cap:
- effective timeout is min(resolved_handler_timeout, event_timeout) when both are set
- if one is unset, the other value is used
- if both are unset, no timeout is enforced

Resolution happens at processing time on each bus. For forwarded events, an unset timeout/concurrency field uses the target bus defaults.

Effective handler slow-warning threshold

Resolved in this order:

handler_slow_timeout
event_handler_slow_timeout
event_slow_timeout
bus event_handler_slow_timeout
bus event_slow_timeout

Effective event slow-warning threshold

Resolved in this order:

event_slow_timeout
bus event_slow_timeout

Execution scope ordering

Timeout and slow-monitor behavior is implemented as stacked runtime scopes. The ordering matters:

Python
TypeScript

# EventBus.step(...)
async with self.locks._run_with_event_lock(self, event):
    await self._process_event(event, timeout=timeout)

# EventBus.process_event(...)
async with asyncio.timeout(resolved_event_timeout):
    async with with_slow_monitor(self._create_slow_event_warning_timer(event)):
        await event._run_handlers(eventbus=self, handlers=applicable_handlers, timeout=resolved_event_timeout)

# EventResult.run_handler(...)
async with eventbus.locks._run_with_handler_lock(eventbus, event, event_result):
    with eventbus._run_with_handler_dispatch_context(event, event_result.handler_id):
        async with event_result._run_with_timeout(event):
            async with with_slow_monitor(handler_slow_monitor):
                await event_result._call_handler(...)

// EventBus.processEvent(...)
await this.locks._runWithEventLock(event, () =>
  this._runHandlersWithTimeout(event, pending_entries, resolved_event_timeout, () =>
    _runWithSlowMonitor(event._createSlowEventWarningTimer(), () =>
      scoped_event._runHandlers(pending_entries)
    )
  )
)

// BaseEvent._runHandlers(...) + EventResult.runHandler(...)
await this.bus.locks._runWithHandlerLock(original, this.bus.event_handler_concurrency, async (handler_lock) => {
  await entry.runHandler(handler_lock)
})

await this.bus.locks._runWithHandlerDispatchContext(this, async () => {
  await _runWithAsyncContext(event._getDispatchContext() ?? null, async () => {
    await _runWithTimeout(this.handler_timeout, () => this._createHandlerTimeoutError(event), () =>
      _runWithSlowMonitor(slow_handler_warning_timer, () =>
        _runWithAbortMonitor(() => this.handler.handler(handler_event), abort_signal)
      )
    )
  })
})

Event-level timeout finalization keeps cancellation semantics explicit:

pending handlers -> cancelled
started handlers -> aborted

Note on retry

Bus/event timeouts are outer budgets. If you need per-attempt limits for retried handlers, use the retry decorator’s timeout option.

Getting Started

Features

API Reference

Concurrency Control

Integrations

Further Reading

Timeout Enforcement

Timeout types

1) Event timeout (`event_timeout`)

2) Handler timeout (`event_handler_timeout` / `handler_timeout`)

3) Slow-warning thresholds (`event_slow_timeout`, `event_handler_slow_timeout`, `handler_slow_timeout`)

Where to set each value

Bus-level defaults

Event-level overrides

Handler-level overrides

Precedence rules

Effective handler timeout

Effective handler slow-warning threshold

Effective event slow-warning threshold

Execution scope ordering

Note on retry

Getting Started

Features

API Reference

Concurrency Control

Integrations

Further Reading

​Timeout types

​1) Event timeout (event_timeout)

​2) Handler timeout (event_handler_timeout / handler_timeout)

​3) Slow-warning thresholds (event_slow_timeout, event_handler_slow_timeout, handler_slow_timeout)

​Where to set each value

​Bus-level defaults

​Event-level overrides

​Handler-level overrides

​Precedence rules

​Effective handler timeout

​Effective handler slow-warning threshold

​Effective event slow-warning threshold

​Execution scope ordering

​Note on retry

Timeout types

1) Event timeout (`event_timeout`)

2) Handler timeout (`event_handler_timeout` / `handler_timeout`)

3) Slow-warning thresholds (`event_slow_timeout`, `event_handler_slow_timeout`, `handler_slow_timeout`)

Where to set each value

Bus-level defaults

Event-level overrides

Handler-level overrides

Precedence rules

Effective handler timeout

Effective handler slow-warning threshold

Effective event slow-warning threshold

Execution scope ordering

Note on retry