Add a matches method to Receiver

This is an alternative for the `selected_from` method and could
eventually replace it.

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

src/frequenz/channels/_receiver.py

@@ -155,11 +155,14 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Callable
-from typing import Generic, Self
+from typing import TYPE_CHECKING, Any, Generic, Self, TypeGuard
 
 from ._exceptions import Error
 from ._generic import MappedMessageT_co, ReceiverMessageT_co
 
+if TYPE_CHECKING:
+    from ._select import Selected
+
 
 class Receiver(ABC, Generic[ReceiverMessageT_co]):
     """An endpoint to receive messages."""
@@ -284,6 +287,30 @@ def filter(
         """
         return _Filter(receiver=self, filter_function=filter_function)
 
+    def matches(
+        self, selected: Selected[Any]
+    ) -> TypeGuard[Selected[ReceiverMessageT_co]]:
+        """Check whether this receiver was selected by [`select()`][frequenz.channels.select].
+
+        This method is used in conjunction with the
+        [`Selected`][frequenz.channels.Selected] class to determine which receiver was
+        selected in `select()` iteration.
+
+        It also works as a [type guard][typing_extensions.TypeIs] to narrow the type of the
+        `Selected` instance to the type of the receiver.
+
+        Please see [`select()`][frequenz.channels.select] for an example.
+
+        Args:
+            selected: The result of a `select()` iteration.
+
+        Returns:
+            Whether this receiver was selected.
+        """
+        if handled := selected._recv is self:  # pylint: disable=protected-access
+            selected._handled = True  # pylint: disable=protected-access
+        return handled
+
 
 class ReceiverError(Error, Generic[ReceiverMessageT_co]):
     """An error that originated in a [Receiver][frequenz.channels.Receiver].
@@ -373,9 +400,7 @@ def consume(self) -> MappedMessageT_co:  # noqa: DOC502
             ReceiverStoppedError: If the receiver stopped producing messages.
             ReceiverError: If there is a problem with the receiver.
         """
-        return self._mapping_function(
-            self._receiver.consume()
-        )  # pylint: disable=protected-access
+        return self._mapping_function(self._receiver.consume())
 
     def __str__(self) -> str:
         """Return a string representation of the mapper."""