Add discussion of channels allowing simultaneous send/receive

trio/_abc.py

@@ -567,6 +567,10 @@ async def send(self, value: SendType) -> None:
           trio.ClosedResourceError: if you previously closed this
               :class:`SendChannel` object, or if another task closes it while
               :meth:`send` is running.
+          trio.BusyResourceError: some channels allow multiple tasks to call
+              `send` at the same time, but others don't. If you try to call
+              `send` simultaneously from multiple tasks on a channel that
+              doesn't support it, then you can get `~trio.BusyResourceError`.
 
         """
 
@@ -607,6 +611,10 @@ async def receive(self) -> ReceiveType:
               :class:`ReceiveChannel` object.
           trio.BrokenResourceError: if something has gone wrong, and the
               channel is broken.
+          trio.BusyResourceError: some channels allow multiple tasks to call
+              `receive` at the same time, but others don't. If you try to call
+              `receive` simultaneously from multiple tasks on a channel that
+              doesn't support it, then you can get `~trio.BusyResourceError`.
 
         """
 

trio/_channel.py

@@ -147,7 +147,9 @@ def send_nowait(self, value):
 
     @enable_ki_protection
     async def send(self, value):
-        """See `~trio.abc.SendChannel.send`.
+        """See `SendChannel.send <trio.abc.SendChannel.send>`.
+
+        Memory channels allow multiple tasks to call `send` at the same time.
 
         """
         await trio.hazmat.checkpoint_if_cancelled()
@@ -259,7 +261,11 @@ def receive_nowait(self):
 
     @enable_ki_protection
     async def receive(self):
-        """See `~trio.abc.ReceiveChannel.receive`.
+        """See `ReceiveChannel.receive <trio.abc.ReceiveChannel.receive>`.
+
+        Memory channels allow multiple tasks to call `receive` at the same
+        time. The first task will get the first item sent, the second task
+        will get the second item sent, and so on.
 
         """
         await trio.hazmat.checkpoint_if_cancelled()