Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions can/listener.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ def __init__(self) -> None:
def on_message_received(self, msg: Message) -> None:
"""Append a message to the buffer.

:raises: BufferError
:raises: RuntimeError
if the reader has already been stopped
"""
if self.is_stopped:
Expand All @@ -103,9 +103,12 @@ def get_message(self, timeout: float = 0.5) -> Message | None:
Attempts to retrieve the message that has been in the queue for the longest amount
of time (FIFO). If no message is available, it blocks for given timeout or until a
message is received (whichever is shorter), or else returns None. This method does
not block after :meth:`can.BufferedReader.stop` has been called.
not block after :meth:`can.BufferedReader.stop` has been called; queued
messages can still be retrieved until the queue is empty.

:param timeout: The number of seconds to wait for a new message.
Use ``0`` to return immediately with the oldest queued message,
or ``None`` if no message is available.
:return: the received :class:`can.Message` or `None`, if the queue is empty.
"""
try:
Expand Down
2 changes: 2 additions & 0 deletions doc/changelog.d/1919.changed.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Clarify non-blocking polling with BufferedReader.get_message(timeout=0),
and correct the documented exception when adding to a stopped reader.
9 changes: 9 additions & 0 deletions doc/notifier.rst
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,15 @@ readers are also documented here.
BufferedReader
--------------

Pass ``timeout=0`` to poll a buffered reader without waiting for a message::

message = reader.get_message(timeout=0)
if message is not None:
print(message)

This removes the oldest queued message, if any. An empty queue returns ``None``
without waiting. A stopped reader can still be drained in the same way.

.. autoclass:: can.BufferedReader
:members:

Expand Down
26 changes: 26 additions & 0 deletions test/listener_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,32 @@ def testBufferedListenerReceives(self):
self.assertIsNotNone(a_listener.get_message(0.1))


class BufferedReaderPollingTest(unittest.TestCase):
def test_zero_timeout_returns_none_when_empty(self):
reader = can.BufferedReader()
self.assertIsNone(reader.get_message(timeout=0))

def test_zero_timeout_drains_messages_in_order(self):
reader = can.BufferedReader()
first = can.Message(arbitration_id=1)
second = can.Message(arbitration_id=2)
reader(first)
reader(second)
self.assertIs(reader.get_message(timeout=0), first)
self.assertIs(reader.get_message(timeout=0), second)
self.assertIsNone(reader.get_message(timeout=0))

def test_stopped_reader_drains_without_waiting(self):
reader = can.BufferedReader()
message = can.Message(arbitration_id=1)
reader(message)
reader.stop()
self.assertIs(reader.get_message(timeout=0), message)
self.assertIsNone(reader.get_message(timeout=0))
with self.assertRaises(RuntimeError):
reader(message)


def test_deprecated_loop_arg(recwarn):
try:
loop = asyncio.get_running_loop()
Expand Down