Application Programming Interface¶
This document describes how to interact with Websockets for Redis from the Django loop and how to adopt the Websocket loop for other purposes.
Use RedisPublisher
from inside Django views¶
For obvious architectural reasons, the code handling the websocket loop can not be accessed directly
from within Django. Therefore, all communication from Django to the websocket loop, must be passed
over to the Redis message queue and vice versa. To facility this, ws4redis offers a class named
RedisPublisher
. An instance of this class shall be used from inside Django views to push
messages via a websocket to the client, or to fetch persisted messages sent through the websocket.
Example view:
from django.views.generic.base import View
from ws4redis.publisher import RedisPublisher
class MyTypicalView(View):
facility = 'unique-named-facility'
audience = {'broadcast': True}
def __init__(self, *args, **kwargs):
super(MyTypicalView, self).init(*args, **kwargs)
self.redis_publisher = RedisPublisher(facility=self.facility, **self.audience)
def get(self, request)
message = 'A message passed to all browsers listening on the named facility'
self.redis_publisher.publish_message(message)
For further options, refer to the reference:
-
RedisStore.
publish_message
(message, expire=None)¶ Publish a
message
on the subscribed channel on the Redis datastore.expire
sets the time in seconds, on how long the message shall additionally of being published, also be persisted in the Redis datastore. If unset, it defaults to the configuration settingsWS4REDIS_EXPIRE
.
Replace RedisSubscriber
for the Websocket loop¶
Sometimes the predefined channels for subscribing and publishing messages might not be enough.
If there is a need to add additional channels to the message queue, it is possible to replace
the implemented class ws4redis.store.RedisSubscriber
by setting the configuration directive
WS4REDIS_SUBSCRIBER
to a class of your choice.
Use the class RedisSubscriber
as a starting point and overload the required methods with your
own implementation.
-
class
ws4redis.subscriber.
RedisSubscriber
(connection)¶ Subscriber class, used by the websocket code to listen for subscribed channels
-
get_file_descriptor
()¶ Returns the file descriptor used for passing to the select call when listening on the message queue.
-
parse_response
()¶ Parse a message response sent by the Redis datastore on a subscribed channel.
-
release
()¶ New implementation to free up Redis subscriptions when websockets close. This prevents memory sap when Redis Output Buffer and Output Lists build when websockets are abandoned.
-
send_persisted_messages
(websocket)¶ This method is called immediately after a websocket is openend by the client, so that persisted messages can be sent back to the client upon connection.
-
send_persited_messages
(websocket)¶ This method is called immediately after a websocket is openend by the client, so that persisted messages can be sent back to the client upon connection.
-
set_pubsub_channels
(request, channels)¶ Initialize the channels used for publishing and subscribing messages through the message queue.
-
Warning
If the overloaded class calls any blocking functions, such as sleep
, read
,
select
or similar, make sure that these functions are patched by the gevent library,
otherwise all connections will block simultaneously.