Polite Ping-Pong: The State Machine Pattern
============================================

Extends the basic ping-pong into a proper state machine with dispatch tables.
Alice and Bob have a polite exchange: ping, pong, thank you, you're welcome.
Found in ``examples/event-based/politePingPong/``.

This is still purely classical, but introduces the **state machine pattern**
that all subsequent quantum examples will use.

Alice's state diagram
---------------------

::

    (connect)
       │ send "ping"
       ▼
    WAITING_PONG
       │ recv "pong" → send "thank you"
       ▼
    WAITING_YOURE_WELCOME
       │ recv "you're welcome"
       ▼
      DONE

Alice's dispatch table
----------------------

::

    ALICE_DISPATCH = {
        (STATE_WAITING_PONG,          "pong"):           handle_pong,
        (STATE_WAITING_YOURE_WELCOME, "you're welcome"): handle_youre_welcome,
    }

Each handler is a focused function that performs one action and returns the next state::

    async def handle_pong(writer: StreamWriter) -> str:
        reply = "thank you"
        writer.write(reply.encode("utf-8"))
        await writer.drain()
        return STATE_WAITING_YOURE_WELCOME

The event loop
--------------

The event loop is generic — it works for any protocol by just changing the dispatch
table and initial state::

    async def run_alice(reader: StreamReader, writer: StreamWriter):
        # Initial action (before the loop)
        writer.write(b"ping")
        await writer.drain()

        state = STATE_WAITING_PONG

        while state != STATE_DONE:
            data = await reader.read(255)
            if not data:
                break
            msg = data.decode("utf-8")

            handler = ALICE_DISPATCH.get((state, msg))
            if handler is None:
                print(f"no transition for '{msg}' — ignoring.")
                continue

            state = await handler(writer)

Key concepts
------------

- **Dispatch table = state machine**: the ``(state, message) → handler`` mapping
  *is* the protocol definition.  Every valid transition is listed; anything not
  listed is automatically rejected.
- **Handlers are independent**: each handler only knows about its own transition,
  making the code modular and easy to extend.
- **The event loop is reusable**: the same loop structure works for every example
  that follows.

Bob's side
----------

Bob uses the same pattern with his own states (``WAITING_PING``, ``WAITING_THANKS``,
``DONE``) and dispatch table.  See ``politeBob.py`` for the full code.

Running
-------

::

    cd examples/event-based/politePingPong
    bash run.sh