[TheTrueAI]

Summary of Changes

capture_message runs once per received frame, and two lines in it cost more than
the rest of the decode combined. This removes both. No API or behaviour change.

• Hoist socket.MSG_DONTROUTE to a module-level plain int. It is an
  enum.IntFlag member, so msg_flags & socket.MSG_DONTROUTE constructed a
  MsgFlag instance on every frame.
• Build Message positionally instead of with twelve keyword arguments;
  binding them per frame is measurable.
• Add test_capture_message to SocketCANTest, which runs frames through
  capture_message via a mocked socket and checks every Message field. The cases
  are chosen so that swapping any two of the positional arguments fails the test.

Net effect on a live 500 kbit/s bus: 107.8 -> 73.3 us of CPU per frame, a ~32%
reduction. Full A/B and correctness evidence under Additional Notes.

Related Issues / Pull Requests

Related to #1135

At the ~10k f/s of a busy 1 Mbit bus, stock capture_message needs 1057 ms of CPU
per second of bus time — more than a whole core just to decode, before any user code
runs. That is a concrete mechanism behind the "python can't keep up" reports in
#1135. This brings it to 733 ms/s. It does not close that issue, but it is a real
part of it.

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring
• Other (please describe): Performance optimisation of the socketcan receive
  hot path. Behaviour-preserving; verified field-for-field against the previous
  implementation (see below).

Checklist

• I have followed the contribution guide.
• I have added or updated tests as appropriate.
• I have added or updated documentation as appropriate.
• I have added a news fragment for towncrier.
• All checks and tests pass (tox).

Additional Notes

Measurements

Live 500 kbit/s bus at 1444 frames/s, aarch64 (Cortex-A53) / CPython 3.13.15 /
python-can 4.6.1. CPU time via time.process_time so blocking recvmsg waits are
excluded. 2500 frames x 3 rounds, median. Each row changes exactly one thing against
a verbatim copy of the current implementation:

variant	us/frame	saves
stock capture_message	105.7	—
MSG_DONTROUTE hoisted to int	79.4	26.3 (25%)
positional Message()	95.5	10.2 (10%)
both	70.6	35.1 (33%)

End to end with this branch applied, same bus: 107.8 -> 73.3 us/frame.

For scale, the bare recvmsg syscall is 31 us/frame, so this removes ~45% of the
Python-side work above the syscall. At 1444 f/s capture_message drops from 15.3%
to 10.4% of one core.

A tight-loop microbenchmark of the & alone reports only 12.8 us
(13.2 us IntFlag vs 0.5 us int), i.e. it understates the in-situ saving of
26.3 us. A cache-thrash variant widens the microbenchmark gap (13.2 -> 15.8 us),
so the enum machinery's cold per-frame working set appears to be part of it. I could
not fully account for the remainder; the in-situ A/B is the number I would trust.

Correctness

Compared against the current implementation on identical inputs, all twelve Message
fields plus their types:

• 3000 frames captured from a live bus, replayed through both, with
  get_channel both False and True — 0 mismatches.
• 1995 synthetic frames covering MSG_DONTROUTE set (798 cases, i.e. is_rx=False)
  and clear, standard and extended IDs, remote and error frames, classic and FD MTU,
  BRS/ESI, every valid DLC and the len8_dlc 9..15 range — 0 mismatches.

The live bus only produces standard non-FD is_rx=True frames, so the synthetic set
is what actually exercises the changed line.

Things I measured and deliberately did not include

• CAN_FD_DLC as a frozenset for the data_len not in can.util.CAN_FD_DLC
  test in dissect_can_frame. Looks like a 0.68 us win in isolation (1.03 -> 0.35 us)
  but measured -0.41 us, i.e. nothing, in situ: classic-CAN data_len is 0..8 and
  hits within the first nine list entries.
• Dropping the two per-frame asserts on the ancillary data: worth only 1.0 us,
  not enough to justify the behaviour discussion.
• recvmsg_into with a preallocated buffer: 2.9 us/frame slower.
• memoryview-based payload slice to avoid the bytes -> bytearray copy:
  4.6 us/frame slower.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[TheTrueAI]

@zariiii9003 thanks for merging #2114. I updated this branch on top of it and the full matrix is green now. The change is small (socketcan.py plus a test that pins the Message argument order) and doesn't change behaviour. Happy to adjust anything.

[zariiii9003]

The change itself looks okay, but fix the tests please.

[TheTrueAI]

Only Python 3.10 fails. Since 3.10 is anyways EOL, is it planned to be dropped anyways soon? Then I would just park this PR till after the drop.

[zariiii9003]

Thank you!