From 6579c0f278adad0a0187f888d40baae5e0b5e060 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Mon, 2 Apr 2018 09:06:54 -0700 Subject: [PATCH] Fix channel layer spec. --- docs/channel_layer_spec.rst | 36 ++++++------------------------------ 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/docs/channel_layer_spec.rst b/docs/channel_layer_spec.rst index 7e6da4fce..a75dff5ac 100644 --- a/docs/channel_layer_spec.rst +++ b/docs/channel_layer_spec.rst @@ -50,8 +50,7 @@ a message more than once or to more than one reader, and must drop messages if this is necessary to achieve this restriction. In order to aid with scaling and network architecture, a distinction -is made between channels that have multiple readers, *single-reader channels* -that are read from a single unknown location, and +is made between channels that have multiple readers and *process-specific channels* that are read from a single known process. *Normal channel* names contain no type characters, and can be routed however @@ -61,15 +60,6 @@ so that a querying client only sees some portion of the messages. Calling ``receive`` on these channels does not guarantee that you will get the messages in order or that you will get anything if the channel is non-empty. -*Single-reader channel* names contain a question mark -(``?``) character in order to indicate to the channel layer that it must make -these channels appear globally consistent. The ``?`` is always preceded by -the main channel name and followed by a random portion -(e.g. ``mything.foo?S4Hr2d``).Channel layers may use the random portion to help -pin the channel to a server, but reads from this channel by a single process must -always be in-order and return messages if the channel is non-empty. These names -must be generated by the ``new_channel`` call. - *Process-specific channel* names contain an exclamation mark (``!``) that separates a remote and local part. These channels are received differently; only the name up to and including the ``!`` character is passed to the @@ -174,25 +164,11 @@ A *channel layer* must provide an object with these attributes channel to send on, as a unicode string, and the message to send, as a serializable ``dict``. -* ``coroutine receive(channels, block=False)``, that takes a list of channel - names as unicode strings, and returns with either ``(None, None)`` - or ``(channel, message)`` if a message is available. If ``block`` is True, then - it will not return a message arrives (or optionally, a built-in timeout, - but it is valid to block forever if there are no messages); if - ``block`` is false, it will always return immediately. It is perfectly - valid to ignore ``block`` and always return immediately, or after a delay; - ``block`` means that the call can take as long as it likes before returning - a message or nothing, not that it must block until it gets one. - -* ``coroutine new_channel(pattern)``, that takes a unicode string pattern, - and returns a new valid channel name that does not already exist, by - adding a unicode string after the ``!`` or ``?`` character in ``pattern``, - and checking for existence of that name in the channel layer. The ``pattern`` - must end with ``!`` or ``?`` or this function must error. If the character - is ``!``, making it a process-specific channel, ``new_channel`` must be - called on the same channel layer that intends to read the channel with - ``receive``; any other channel layer instance may not receive - messages on this channel due to client-routing portions of the appended string. +* ``coroutine receive(channel)``, that takes a single channel name and returns + the next received message on that channel. + +* ``coroutine new_channel()``, which returns a new process-specific channel + that can be used to give to a local coroutine or receiver. * ``MessageTooLarge``, the exception raised when a send operation fails because the encoded message is over the layer's size limit.