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 settings WS4REDIS_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_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.