NAME

Jifty::Plugin::PubSub::Subscriptions - Manage browser event subscriptions

DESCRIPTION

This class is a global cache of the outstanding subscriptions of requests. When a page is rendered, it may choose to add subscriptions via "update_on" or "add":

    # Update the current region on an event
    Jifty->subs->update_on( topic => "some_event" );

or:

    # Send this topic of events to the browser
    Jifty->subs->add( topic => "some_event" );

These subscriptions are not done in the rendering request, but must be stored until the websocket connection occurs later; this class manages that storage.

The storage is currently an in-memory store which does not purge old subscriptions. This means that if a page with subscriptions is requested 1000 times, but the websocket for them is never established, those subscriptions will be stored until the server is restarted. In the future, these subscriptions may be stored on the session, and expired in conjunction.

The only expected interaction with this module is via "update_on" and "add".

METHODS

add topic => TOPIC [, ...]

Adds a subscription. If only the TOPIC is given, the event will be passed through to the web browser to interpret. Otherwise, the arguments are used similarly to Jifty::Web::Element to determine which region to update, and how.

update_on topic => TOPIC [, ...]

As "add", but defaults to refreshing the current region.

client_id

Returns the assigned CLIENT_ID of the current connection. This is undef if the client has not been assigned any subscriptions yet.

reset

Called internally once per request to reset for the next request.

retrieve CLIENT_ID

Returns the data structure of subscriptions for the given CLIENT_ID, and removes it such that it is not accessible to future requests.