[redis.git] / doc / PublishSubscribe.html


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
    <head>
        <link type="text/css" rel="stylesheet" href="style.css" />
    </head>
    <body>
        <div id="page">
        
            <div id='header'>
            <a href="index.html">
            <img style="border:none" alt="Redis Documentation" src="redis.png">
            </a>
            </div>
        
            <div id="pagecontent">
                <div class="index">
<!-- This is a (PRE) block.  Make sure it's left aligned or your toc title will be off. -->
<b>PublishSubscribe: Contents</b><br>&nbsp;&nbsp;<a href="#UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a><br>&nbsp;&nbsp;<a href="#UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a><br>&nbsp;&nbsp;<a href="#PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>&nbsp;&nbsp;<a href="#PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>&nbsp;&nbsp;<a href="#PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a><br>&nbsp;&nbsp;<a href="#PUBLISH channel message">PUBLISH channel message</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Format of pushed messages">Format of pushed messages</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Wire protocol example">Wire protocol example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#More details on the PUBLISH command">More details on the PUBLISH command</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Programming Example">Programming Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Client library implementations hints">Client library implementations hints</a>
                </div>
                
                <h1 class="wikiname">PublishSubscribe</h1>

                <div class="summary">
                    
                </div>

                <div class="narrow">
                    &iuml;&raquo;&iquest;=SUBSCRIBE channel_1 channel_2 ... channel_N=
<h1><a name="UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a></h1>
<h1><a name="UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a></h1>
<h1><a name="PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
<h1><a name="PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
<h1><a name="PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a></h1>
<h1><a name="PUBLISH channel message">PUBLISH channel message</a></h1>Time complexity: subscribe is O(1), unsubscribe is O(N) where N is the number of clients already subscribed to a channel, publish is O(N+M) where N is the number of clients subscribed to the receiving channel, and M is the total number of subscribed patterns (by any client). Psubscribe is O(N) where N is the number of patterns the Psubscribing client is already subscribed to. Punsubscribe is O(N+M) where N is the number of patterns the Punsubscribing client is already subscribed and M is the number of total patterns subscribed in the system (by any client).<br/><br/><blockquote>SUBSCRIBE, UNSUBSCRIBE and PUBLISH commands implement the<a href="http://en.wikipedia.org/wiki/Publish/subscribe" target="_blank">Publish/Subscribe messaging paradigm</a> where (citing Wikipedia) senders (publishers) are not programmed to send their messages to specific receivers (subscribers). Rather, published messages are characterized into channels, without knowledge of what (if any) subscribers there may be. Subscribers express interest in one or more channels, and only receive messages that are of interest, without knowledge of what (if any) publishers there are. This decoupling of publishers and subscribers can allow for greater scalability and a more dynamic network topology.</blockquote>
<blockquote>For instance in order to subscribe to the channels foo and bar the clientwill issue the SUBSCRIBE command followed by the names of the channels.</blockquote><pre class="codeblock python" name="code">
SUBSCRIBE foo bar
</pre>
<blockquote>All the messages sent by other clients to this channels will be pushed bythe Redis server to all the subscribed clients, in the form of a threeelements bulk reply, where the first element is the message type, thesecond the originating channel, and the third argument the message payload.</blockquote>
<blockquote>A client subscribed to 1 or more channels should NOT issue other commandsother than SUBSCRIBE and UNSUBSCRIBE, but can subscribe or unsubscribeto other channels dynamically.</blockquote>
<blockquote>The reply of the SUBSCRIBE and UNSUBSCRIBE operations are sent in the formof messages, so that the client can just read a coherent stream of messageswhere the first element indicates the kind of message.</blockquote><h2><a name="Format of pushed messages">Format of pushed messages</a></h2>
<blockquote>Messages are in the form of multi bulk replies with three elements.The first element is the kind of message:</blockquote><ul><li> &quot;subscribe&quot;: means that we successfully subscribed to the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to.</li><li> &quot;unsubscribe&quot;: means that we successfully unsubscribed from the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to. If this latest argument is zero, we are no longer subscribed to any channel, and the client can issue any kind of Redis command as we are outside the Pub/sub state.</li><li> &quot;message&quot;: it is a message received as result of a PUBLISH command issued by another client. The second element is the name of the originating channel, and the third the actual message payload.</li></ul><h2><a name="Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a></h2>
If the UNSUBSCRIBE command is issued without additional arguments, it is equivalent to unsubscribing to all the channels we are currently subscribed. A message for every unsubscribed channel will be received.
<h2><a name="Wire protocol example">Wire protocol example</a></h2>
<pre class="codeblock python python" name="code">
SUBSCRIBE first second
*3
$9
subscribe
$5
first
:1
*3
$9
subscribe
$6
second
:2
</pre>
at this point from another client we issue a PUBLISH operation against the channel named &quot;second&quot;. This is what the first client receives:
<pre class="codeblock python python python" name="code">
*3
$7
message
$6
second
$5
Hello
</pre>
Now the client unsubscribes itself from all the channels using the UNSUBSCRIBE command without additional arguments:
<pre class="codeblock python python python python" name="code">
UNSUBSCRIBE
*3
$11
unsubscribe
$6
second
:1
*3
$11
unsubscribe
$5
first
:0
</pre>
<h2><a name="PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a></h2>
Redis Pub/Sub implementation supports pattern matching. Clients may subscribe to glob style patterns in order to receive all the messages sent to channel names matching a given pattern.<br/><br/>For instance the command:
<pre class="codeblock python python python python python" name="code">
PSUBSCRIBE news.*
</pre>
Will receive all the messages sent to the channel news.art.figurative and news.music.jazz and so forth. All the glob style patterns as valid, so multiple wild cards are supported.<br/><br/>Messages received as a result of pattern matching are sent in a different format:
<ul><li> The type of the message is &quot;pmessage&quot;: it is a message received as result of a PUBLISH command issued by another client, matching a pattern matching subscription. The second element is the original pattern matched, the third element is the name of the originating channel, and the last element the actual message payload.</li></ul>
Similarly to SUBSCRIBE and UNSUBSCRIBE, PSUBSCRIBE and PUNSUBSCRIBE commands are acknowledged by the system sending a message of type &quot;psubscribe&quot; and &quot;punsubscribe&quot; using the same format as the &quot;subscribe&quot; and &quot;unsubscribe&quot; message format.
<h2><a name="Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a></h2>
A client may receive a single message multiple time if it's subscribed to multiple patterns matching a published message, or it is subscribed to both patterns and channels matching the message. Like in the following example:
<pre class="codeblock python python python python python python" name="code">
SUBSCRIBE foo
PSUBSCRIBE f*
</pre>
In the above example, if a message is sent to the <b>foo</b> channel, the client will receive two messages, one of type &quot;message&quot; and one of type &quot;pmessage&quot;.
<h2><a name="The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a></h2>
In <b>subscribe</b>, <b>unsubscribe</b>, <b>psubscribe</b> and <b>punsubscribe</b> message types, the last argument is the count of subscriptions still active. This number is actually the total number of channels and patterns the client is still subscribed to. So the client will exit the Pub/Sub state only when this count will drop to zero as a result of unsubscription from all the channels and patterns.
<h2><a name="More details on the PUBLISH command">More details on the PUBLISH command</a></h2>
The Publish command is a bulk command where the first argument is the target class, and the second argument the data to send. It returns an Integer Reply representing the number of clients that received the message (that is, the number of clients that were listening for this class).
<h2><a name="Programming Example">Programming Example</a></h2>
Pieter Noordhuis provided a great example using Event-machine and Redis to create <a href="http://chat.redis-db.com" target="_blank">a multi user high performance web chat</a>, with source code included of course!
<h2><a name="Client library implementations hints">Client library implementations hints</a></h2>
Because all the messages received contain the original subscription causing the message delivery (the channel in the case of &quot;message&quot; type, and the original pattern in the case of &quot;pmessage&quot; type) clinet libraries may bind the original subscription to callbacks (that can be anonymous functions, blocks, function pointers, and so forth), using an hash table.<br/><br/>When a message is received an O(1) lookup can be done in order to deliver the message to the registered callback.

                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
aed57a31	1
	2	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
	3	<html>
	4	<head>
	5	<link type="text/css" rel="stylesheet" href="style.css" />
	6	</head>
	7	<body>
	8	<div id="page">
	9
	10	<div id='header'>
	11	<a href="index.html">
	12	<img style="border:none" alt="Redis Documentation" src="redis.png">
	13	</a>
	14	</div>
	15
	16	<div id="pagecontent">
	17	<div class="index">
	18	<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
	19	<b>PublishSubscribe: Contents</b><br>  <a href="#UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a><br>  <a href="#UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a><br>  <a href="#PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>  <a href="#PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>  <a href="#PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a><br>  <a href="#PUBLISH channel message">PUBLISH channel message</a><br>    <a href="#Format of pushed messages">Format of pushed messages</a><br>    <a href="#Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a><br>    <a href="#Wire protocol example">Wire protocol example</a><br>    <a href="#PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a><br>    <a href="#Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a><br>    <a href="#The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a><br>    <a href="#More details on the PUBLISH command">More details on the PUBLISH command</a><br>    <a href="#Programming Example">Programming Example</a><br>    <a href="#Client library implementations hints">Client library implementations hints</a>
	20	</div>
	21
	22	<h1 class="wikiname">PublishSubscribe</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
	29	ï»¿=SUBSCRIBE channel_1 channel_2 ... channel_N=
	30	<h1><a name="UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a></h1>
	31	<h1><a name="UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a></h1>
	32	<h1><a name="PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
	33	<h1><a name="PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
	34	<h1><a name="PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a></h1>
	35	<h1><a name="PUBLISH channel message">PUBLISH channel message</a></h1>Time complexity: subscribe is O(1), unsubscribe is O(N) where N is the number of clients already subscribed to a channel, publish is O(N+M) where N is the number of clients subscribed to the receiving channel, and M is the total number of subscribed patterns (by any client). Psubscribe is O(N) where N is the number of patterns the Psubscribing client is already subscribed to. Punsubscribe is O(N+M) where N is the number of patterns the Punsubscribing client is already subscribed and M is the number of total patterns subscribed in the system (by any client).<br/><br/><blockquote>SUBSCRIBE, UNSUBSCRIBE and PUBLISH commands implement the<a href="http://en.wikipedia.org/wiki/Publish/subscribe" target="_blank">Publish/Subscribe messaging paradigm</a> where (citing Wikipedia) senders (publishers) are not programmed to send their messages to specific receivers (subscribers). Rather, published messages are characterized into channels, without knowledge of what (if any) subscribers there may be. Subscribers express interest in one or more channels, and only receive messages that are of interest, without knowledge of what (if any) publishers there are. This decoupling of publishers and subscribers can allow for greater scalability and a more dynamic network topology.</blockquote>
	36	<blockquote>For instance in order to subscribe to the channels foo and bar the clientwill issue the SUBSCRIBE command followed by the names of the channels.</blockquote><pre class="codeblock python" name="code">
	37	SUBSCRIBE foo bar
	38	</pre>
	39	<blockquote>All the messages sent by other clients to this channels will be pushed bythe Redis server to all the subscribed clients, in the form of a threeelements bulk reply, where the first element is the message type, thesecond the originating channel, and the third argument the message payload.</blockquote>
	40	<blockquote>A client subscribed to 1 or more channels should NOT issue other commandsother than SUBSCRIBE and UNSUBSCRIBE, but can subscribe or unsubscribeto other channels dynamically.</blockquote>
	41	<blockquote>The reply of the SUBSCRIBE and UNSUBSCRIBE operations are sent in the formof messages, so that the client can just read a coherent stream of messageswhere the first element indicates the kind of message.</blockquote><h2><a name="Format of pushed messages">Format of pushed messages</a></h2>
	42	<blockquote>Messages are in the form of multi bulk replies with three elements.The first element is the kind of message:</blockquote><ul><li> "subscribe": means that we successfully subscribed to the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to.</li><li> "unsubscribe": means that we successfully unsubscribed from the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to. If this latest argument is zero, we are no longer subscribed to any channel, and the client can issue any kind of Redis command as we are outside the Pub/sub state.</li><li> "message": it is a message received as result of a PUBLISH command issued by another client. The second element is the name of the originating channel, and the third the actual message payload.</li></ul><h2><a name="Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a></h2>
	43	If the UNSUBSCRIBE command is issued without additional arguments, it is equivalent to unsubscribing to all the channels we are currently subscribed. A message for every unsubscribed channel will be received.
	44	<h2><a name="Wire protocol example">Wire protocol example</a></h2>
	45	<pre class="codeblock python python" name="code">
	46	SUBSCRIBE first second
	47	*3
	48	$9
	49	subscribe
	50	$5
	51	first
	52	:1
	53	*3
	54	$9
	55	subscribe
	56	$6
	57	second
	58	:2
	59	</pre>
	60	at this point from another client we issue a PUBLISH operation against the channel named "second". This is what the first client receives:
	61	<pre class="codeblock python python python" name="code">
	62	*3
	63	$7
	64	message
65	$6
66	second
67	$5
68	Hello
69	</pre>
70	Now the client unsubscribes itself from all the channels using the UNSUBSCRIBE command without additional arguments:
71	<pre class="codeblock python python python python" name="code">
72	UNSUBSCRIBE
73	*3
74	$11
75	unsubscribe
76	$6
77	second
78	:1
79	*3
80	$11
81	unsubscribe
82	$5
83	first
84	:0
85	</pre>
86	<h2><a name="PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a></h2>
87	Redis Pub/Sub implementation supports pattern matching. Clients may subscribe to glob style patterns in order to receive all the messages sent to channel names matching a given pattern.<br/><br/>For instance the command:
88	<pre class="codeblock python python python python python" name="code">
89	PSUBSCRIBE news.*
90	</pre>
91	Will receive all the messages sent to the channel news.art.figurative and news.music.jazz and so forth. All the glob style patterns as valid, so multiple wild cards are supported.<br/><br/>Messages received as a result of pattern matching are sent in a different format:
92	<ul><li> The type of the message is "pmessage": it is a message received as result of a PUBLISH command issued by another client, matching a pattern matching subscription. The second element is the original pattern matched, the third element is the name of the originating channel, and the last element the actual message payload.</li></ul>
93	Similarly to SUBSCRIBE and UNSUBSCRIBE, PSUBSCRIBE and PUNSUBSCRIBE commands are acknowledged by the system sending a message of type "psubscribe" and "punsubscribe" using the same format as the "subscribe" and "unsubscribe" message format.
94	<h2><a name="Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a></h2>
95	A client may receive a single message multiple time if it's subscribed to multiple patterns matching a published message, or it is subscribed to both patterns and channels matching the message. Like in the following example:
96	<pre class="codeblock python python python python python python" name="code">
97	SUBSCRIBE foo
98	PSUBSCRIBE f*
99	</pre>
100	In the above example, if a message is sent to the <b>foo</b> channel, the client will receive two messages, one of type "message" and one of type "pmessage".
101	<h2><a name="The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a></h2>
102	In <b>subscribe</b>, <b>unsubscribe</b>, <b>psubscribe</b> and <b>punsubscribe</b> message types, the last argument is the count of subscriptions still active. This number is actually the total number of channels and patterns the client is still subscribed to. So the client will exit the Pub/Sub state only when this count will drop to zero as a result of unsubscription from all the channels and patterns.
103	<h2><a name="More details on the PUBLISH command">More details on the PUBLISH command</a></h2>
104	The Publish command is a bulk command where the first argument is the target class, and the second argument the data to send. It returns an Integer Reply representing the number of clients that received the message (that is, the number of clients that were listening for this class).
105	<h2><a name="Programming Example">Programming Example</a></h2>
106	Pieter Noordhuis provided a great example using Event-machine and Redis to create <a href="http://chat.redis-db.com" target="_blank">a multi user high performance web chat</a>, with source code included of course!
107	<h2><a name="Client library implementations hints">Client library implementations hints</a></h2>
108	Because all the messages received contain the original subscription causing the message delivery (the channel in the case of "message" type, and the original pattern in the case of "pmessage" type) clinet libraries may bind the original subscription to callbacks (that can be anonymous functions, blocks, function pointers, and so forth), using an hash table.<br/><br/>When a message is received an O(1) lookup can be done in order to deliver the message to the registered callback.
109
110	</div>
111
112	</div>
113	</div>
114	</body>
115	</html>
116