perf(hds_protocol): 62% fewer allocations in encode (one shared buffer) - #552

TL;DR

• pyhap.hds_protocol.encode now writes every value into one shared bytearray.
• Before, each value built its own small bytes objects, and each container joined them again.
• Measured on the frames of one HKSV recording session: 22548.6 -> 8573.4 memory allocations, 62.0% fewer.
• A 256 KB dataSend data frame: 422.74 µs -> 230.70 µs, 45% faster.
• Tested with python3 -m pytest tests/test_hds_recording.py tests/test_hksv_transport.py tests/test_hksv_gating.py -q: 56 passed.

What & Why

Message.encode() runs for every HomeKit Data Stream frame the accessory sends. The old encode returned a new bytes object for each tag, number, string, key and container. Each list and dict then joined the parts of its items. A media chunk was copied one time for each container level around it.

The new private helper _encode_into(value, out) appends to one bytearray. _encode_int and _encode_length_prefixed append to the same buffer. struct.pack writes the tag together with the number. encode makes the buffer, fills it and returns bytes(out).

The tag values, the width limits, the 14-item inline rule and the TypeError text are the same. The public signature and the return type of encode do not change.

The last two rows get slower. A bare value outside a container now pays for the buffer and the final copy. For a bare 256 KB value, that is two large memory blocks for each call, not one. Every HDS frame is a header dict plus a message dict, so the library does not send bare values.

Why this is safe and easy to maintain

The change is in one file and touches three functions plus one new private helper. The branch order in the encoder is the same as before, so the diff reads line by line. The encoded bytes are identical for every input type. The existing tests in tests/test_hds_recording.py, tests/test_hksv_transport.py and tests/test_hksv_gating.py cover the encoder and all pass.

Validation

• Native tests on the patched tree: 56 passed in 1.04 s.
• ruff check and ruff format --check pass on pyhap/hds_protocol.py.
• Output check: every frame of five seeded recording sessions matches the old encoder byte for byte. The check also covers all integer widths, Int64, int subclasses, floats, str/bytes/bytearray at each length limit, 14- and 15-item containers, and the error cases.
• Allocation counts come from a hook on the CPython allocator (malloc, calloc, realloc) with the garbage collector off. Each count is for one call of the row, after five warm-up calls.
• Each table row ran in a new process, with the default allocator settings, on CPython 3.12.13, Linux x86-64. Each time is the median of three such processes.

The script below holds the message body of every row. Save it as bench_rows.py and run PYTHONPATH=. python3 bench_rows.py data-256k on dev and on this branch. Use a new process for each row name.

import os, sys, timeit
from pyhap import hds_protocol as hp

def data_event(size, count=1):
    packets = [{"data": os.urandom(size),
                "metadata": {"dataType": "mediaFragment", "dataSequenceNumber": i + 2,
                             "dataChunkSequenceNumber": 1, "isLastDataChunk": True,
                             "dataTotalSize": size}}
               for i in range(count)]
    return hp.event("dataSend", "data", {"streamId": 1, "packets": packets}).encode

def bare(value):
    return lambda: hp.encode(value)

rows = {
    "hello": lambda: hp.response("control", "hello", {}, 1).encode,
    "open": lambda: hp.response("dataSend", "open", {"status": 0}, 2).encode,
    "data-4k": lambda: data_event(0x1000),
    "data-256k": lambda: data_event(0x40000),
    "data-20x1500": lambda: data_event(1500, 20),
    "true": lambda: bare(True),
    "bytes-256k": lambda: bare(os.urandom(0x40000)),
}
fn = rows[sys.argv[1]]()
print(min(timeit.repeat(fn, number=200, repeat=15)) / 200 * 1e6, "µs")

AI assistance

This PR was prepared with AI assistance from Aiden. Candidates were tracked with Weco Observe. The tests, the lint checks and the measurements above ran on the patched tree. There was no human review before submission.

Weco share link: https://dashboard.weco.ai/share/nuxeMBqIu4e-ZZj7maqy9kQufrWB5dHe