Event-Based Programming Overview

The event-based examples show how to structure quantum network protocols using a state machine pattern. This is the recommended approach for protocols that interleave classical negotiation with quantum operations.

Prerequisites: you should understand the New SDK Overview first.

The state machine pattern

Each node’s behaviour is defined by:

  1. States — string constants naming each phase of the protocol

  2. Handlers — async functions that execute when a specific message arrives in a specific state. Each handler performs an action and returns the next state.

  3. Dispatch table — a dictionary mapping (current_state, message) to handler. This is the state machine.

  4. Event loop — reads messages, looks up the transition, calls the handler.

Example structure:

# States
STATE_WAITING_ACCEPT = "WAITING_ACCEPT"
STATE_DONE           = "DONE"

# Handler
async def handle_yes(writer: StreamWriter) -> str:
    # ... do something ...
    return STATE_DONE

# Dispatch table
DISPATCH = {
    (STATE_WAITING_ACCEPT, "yes"): handle_yes,
}

# Event loop
async def run_alice(reader, writer):
    state = STATE_WAITING_ACCEPT
    while state != STATE_DONE:
        data = await reader.read(255)
        msg = data.decode("utf-8")
        handler = DISPATCH.get((state, msg))
        if handler is None:
            continue  # ignore unknown messages
        state = await handler(writer)

Why this pattern?

  • Clear protocol structure: the dispatch table maps directly to a state transition diagram, making the protocol easy to read and verify.

  • Extensible: adding a new state or message is just adding a handler and a dispatch entry — no changes to the event loop.

  • Quantum integration: handlers can create NetQASMConnection, perform quantum operations, and flush() — keeping quantum code isolated in focused handler functions.

Examples

The examples progress from purely classical to quantum:

Example

What it teaches

PingPong

Basic event loop with simple if/else message handling

PolitePingPong

Full state machine pattern with dispatch table

QuantumCorrRNG

Adding quantum operations (EPR + measure) to event handlers

QuantumCorrRNGVerified

Multi-state protocol: negotiate, quantum, then classical verification