Message Queues
When a connection is open, it runs a background task that reads network data and
automatically handles certain types of events for you. For example, if the
background task receives a ping event, then it will automatically send back a
pong event. When the background task receives a message, it places that message
into an internal queue. When you call get_message()
, it returns the first
item from this queue.
If this internal message queue does not have any size limits, then a remote endpoint could rapidly send large messages and use up all of the memory on the local machine! In almost all situations, the message queue needs to have size limits, both in terms of the number of items and the size per message. These limits create an upper bound for the amount of memory that can be used by a single WebSocket connection. For example, if the queue size is 10 and the maximum message size is 1 megabyte, then the connection will use at most 10 megabytes of memory.
When the message queue is full, the background task pauses and waits for the
user to remove a message, i.e. call get_message()
. When the background task
is paused, it stops processing background events like replying to ping events.
If a message is received that is larger than the maximum message size, then the
connection is automatically closed with code 1009 and the message is discarded.
The library APIs each take arguments to configure the mesage buffer:
message_queue_size
and max_message_size
. By default the queue size is
one and the maximum message size is 1 MiB. If you set queue size to zero, then
the background task will block every time it receives a message until somebody
calls get_message()
. For an unbounded queue—which is strongly
discouraged—set the queue size to math.inf
. Likewise, the maximum message
size may also be disabled by setting it to math.inf
.