Parent-Child Tracking

When a handler emits another event, AbxBus automatically records lineage so you can understand call chains instead of guessing what triggered what. Repository example files:

What gets tracked

event_parent_id: points from child -> parent event
event_children: aggregated list of child events emitted with event.emit(...) during handler execution
event_emitted_by_handler_id: which specific handler emitted the child

This tracking works across nested chains (parent -> child -> grandchild) and is surfaced in event helpers and tree logs.

Which emit style should I use?

Most handler code should use await event.emit(ChildEvent(...)) in Python or await event.emit(ChildEvent(...)).done() in TypeScript. That is the “owned child work” style: the child is linked to the parent, runs immediately from the caller’s point of view, and the parent cannot complete until the child completes. Use the other styles only when you explicitly want linked background work or a fully detached top-level event.

Style	`event_parent_id`	`event_blocks_parent_completion`	Blocks current handler?	Effect
`await event.emit(ChildEvent(...))` `await event.emit(ChildEvent(...)).done()`	Parent event id	`True` / `true`	Yes	Linked child work. The child can queue-jump, and parent completion waits for the child.
`event.emit(ChildEvent(...))` without awaiting	Parent event id	`False` / `false`	No	Linked background child. It appears in ancestry/tree logs, but the parent can complete before the child finishes.
`await bus.emit(TopLevelEvent(...))` `await bus.emit(TopLevelEvent(...)).done()`	`None` / `null`	`False` / `false` because there is no linked parent to block	Yes	Detached top-level event that the current handler waits for naturally because it is awaited. It is not a child in hierarchy tracking.
`bus.emit(TopLevelEvent(...))` without awaiting	`None` / `null`	`False` / `false`	No	True background event. It is queued for later processing and has no retained relationship to the event that emitted it.

In short: use event.emit(...) when you want parent-child lineage, and add await when that child work is part of the parent’s completion. Use bus.emit(...) when the event should be treated as a separate top-level event.

Works across forwarded buses too

Parent-child lineage is preserved even when the parent event has been forwarded between buses. If a forwarded event is handled on another bus and that handler emits a child:

the child still gets event_parent_id = <forwarded parent event_id>
the child is linked under the emitting handler’s event_children
forwarding that child onward keeps the same lineage metadata

Use event.emit(...) in handlers so the runtime can attach ancestry and ownership correctly. See also: Forwarding Between Buses

Queue-jumped vs normally queued linked children

Lineage tracking works in both execution styles:

Queue-jumped child events:
- emitted inside a handler and immediately awaited (await child / await child.done())
- child may execute right away (RPC-style), gets normal parent linkage metadata, and sets event_blocks_parent_completion=True
Normally queued child events:
- emitted inside a handler but not immediately awaited
- child runs later via normal queue scheduling, keeps the same event_parent_id ancestry link, and leaves event_blocks_parent_completion=False

In short: event.emit(...) records lineage. Awaiting the emitted event decides whether that lineage also blocks parent completion. See Immediate Execution (RPC-style) for queue-jump behavior details.

Full example: checkout -> reserve/charge/receipt (+ fraud grandchild)

Python
TypeScript

from abxbus import BaseEvent, EventBus

class CheckoutEvent(BaseEvent[str]):
    order_id: str

class ReserveInventoryEvent(BaseEvent[str]):
    order_id: str

class ChargeCardEvent(BaseEvent[str]):
    order_id: str

class FraudCheckEvent(BaseEvent[str]):
    order_id: str

class SendReceiptEvent(BaseEvent[str]):
    order_id: str

bus = EventBus('TreeBus')

async def on_checkout(event: CheckoutEvent) -> str:
    reserve = event.emit(ReserveInventoryEvent(order_id=event.order_id))
    await reserve
    reserve_id = await reserve.event_result()

    charge = event.emit(ChargeCardEvent(order_id=event.order_id))
    await charge
    charge_id = await charge.event_result()

    receipt = event.emit(SendReceiptEvent(order_id=event.order_id))
    await receipt
    receipt_id = await receipt.event_result()

    return f'{reserve_id}|{charge_id}|{receipt_id}'

async def on_reserve(event: ReserveInventoryEvent) -> str:
    return f'reserve:{event.order_id}'

async def on_charge(event: ChargeCardEvent) -> str:
    fraud = event.emit(FraudCheckEvent(order_id=event.order_id))
    await fraud
    fraud_status = await fraud.event_result()
    return f'charge:{event.order_id}:{fraud_status}'

async def on_fraud(event: FraudCheckEvent) -> str:
    return f'fraud-ok:{event.order_id}'

async def on_receipt(event: SendReceiptEvent) -> str:
    return f'receipt:{event.order_id}'

bus.on(CheckoutEvent, on_checkout)
bus.on(ReserveInventoryEvent, on_reserve)
bus.on(ChargeCardEvent, on_charge)
bus.on(FraudCheckEvent, on_fraud)
bus.on(SendReceiptEvent, on_receipt)

root = bus.emit(CheckoutEvent(order_id='ord-123'))
result = await root.event_result()
await bus.wait_until_idle()

print(result)
print(bus.log_tree())

import { BaseEvent, EventBus } from 'abxbus'
import { z } from 'zod'

const CheckoutEvent = BaseEvent.extend('CheckoutEvent', {
  order_id: z.string(),
  event_result_type: z.string(),
})
const ReserveInventoryEvent = BaseEvent.extend('ReserveInventoryEvent', {
  order_id: z.string(),
  event_result_type: z.string(),
})
const ChargeCardEvent = BaseEvent.extend('ChargeCardEvent', {
  order_id: z.string(),
  event_result_type: z.string(),
})
const FraudCheckEvent = BaseEvent.extend('FraudCheckEvent', {
  order_id: z.string(),
  event_result_type: z.string(),
})
const SendReceiptEvent = BaseEvent.extend('SendReceiptEvent', {
  order_id: z.string(),
  event_result_type: z.string(),
})

const bus = new EventBus('TreeBus')

bus.on(CheckoutEvent, async (event) => {
  const reserve = event.emit(ReserveInventoryEvent({ order_id: event.order_id }))
  await reserve.done()

  const charge = event.emit(ChargeCardEvent({ order_id: event.order_id }))
  await charge.done()

  const receipt = event.emit(SendReceiptEvent({ order_id: event.order_id }))
  await receipt.done()

  return `${reserve.event_result}|${charge.event_result}|${receipt.event_result}`
})

bus.on(ReserveInventoryEvent, async (event) => `reserve:${event.order_id}`)
bus.on(ChargeCardEvent, async (event) => {
  const fraud = event.emit(FraudCheckEvent({ order_id: event.order_id }))
  await fraud.done()
  return `charge:${event.order_id}:${fraud.event_result}`
})

bus.on(FraudCheckEvent, async (event) => `fraud-ok:${event.order_id}`)
bus.on(SendReceiptEvent, async (event) => `receipt:${event.order_id}`)

const root = bus.emit(CheckoutEvent({ order_id: 'ord-123' }))
await root.done()
await bus.waitUntilIdle()

console.log(root.event_result)
console.log(bus.logTree())

Example tree output

Captured from running the Python example above with uv run (IDs/timestamps vary run-to-run):

└── CheckoutEvent#b7c7 [10:10:54.522 (0.003s)]
    └── ✅ TreeBus#ef2a.__main__.on_checkout#7a12 [10:10:54.522 (0.002s)] → 'reserve:ord-123|charge:ord-123:fraud-ok:ord-123|receipt:ord-123'
        ├── ReserveInventoryEvent#ca2f [10:10:54.522 (0.000s)]
        │   └── ✅ TreeBus#ef2a.__main__.on_reserve#1583 [10:10:54.522 (0.000s)] → 'reserve:ord-123'
        ├── ChargeCardEvent#b746 [10:10:54.523 (0.001s)]
        │   └── ✅ TreeBus#ef2a.__main__.on_charge#7d9c [10:10:54.523 (0.001s)] → 'charge:ord-123:fraud-ok:ord-123'
        │       └── FraudCheckEvent#31e0 [10:10:54.523 (0.000s)]
        │           └── ✅ TreeBus#ef2a.__main__.on_fraud#4c4e [10:10:54.523 (0.000s)] → 'fraud-ok:ord-123'
        └── SendReceiptEvent#c399 [10:10:54.524 (0.000s)]
            └── ✅ TreeBus#ef2a.__main__.on_receipt#de9f [10:10:54.524 (0.000s)] → 'receipt:ord-123'

Why this helps in practice

Debugging: quickly see causality chains instead of inspecting raw logs line-by-line.
Reliability: timeout/cancellation behavior can be reasoned about by ancestry.
Querying: combine lineage with find(..., child_of=...) to isolate event families.

Getting Started

Features

API Reference

Concurrency Control

Integrations

Further Reading

Parent-Child Tracking

What gets tracked

Which emit style should I use?

Works across forwarded buses too

Queue-jumped vs normally queued linked children

Full example: checkout -> reserve/charge/receipt (+ fraud grandchild)

Example tree output

Why this helps in practice

Getting Started

Features

API Reference

Concurrency Control

Integrations

Further Reading

Documentation Index

​What gets tracked

​Which emit style should I use?

​Works across forwarded buses too

​Queue-jumped vs normally queued linked children

​Full example: checkout -> reserve/charge/receipt (+ fraud grandchild)

​Example tree output

​Why this helps in practice

​Related pages

What gets tracked

Which emit style should I use?

Works across forwarded buses too

Queue-jumped vs normally queued linked children

Full example: checkout -> reserve/charge/receipt (+ fraud grandchild)

Example tree output

Why this helps in practice

Related pages