Debian Codegraph @

closure-library/closure/goog/messaging/bufferedchannel.js

raw
1 // Copyright 2010 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview A wrapper for asynchronous message-passing channels that buffer
17 * their output until both ends of the channel are connected.
18 *
19 */
20
21 goog.provide('goog.messaging.BufferedChannel');
22
23 goog.require('goog.Disposable');
24 goog.require('goog.Timer');
25 goog.require('goog.events');
26 goog.require('goog.log');
27 goog.require('goog.messaging.MessageChannel');
28 goog.require('goog.messaging.MultiChannel');
29
30
31
32 /**
33 * Creates a new BufferedChannel, which operates like its underlying channel
34 * except that it buffers calls to send until it receives a message from its
35 * peer claiming that the peer is ready to receive. The peer is also expected
36 * to be a BufferedChannel, though this is not enforced.
37 *
38 * @param {!goog.messaging.MessageChannel} messageChannel The MessageChannel
39 * we're wrapping.
40 * @param {number=} opt_interval Polling interval for sending ready
41 * notifications to peer, in ms. Default is 50.
42 * @constructor
43 * @extends {goog.Disposable}
44 * @implements {goog.messaging.MessageChannel};
45 * @final
46 */
47 goog.messaging.BufferedChannel = function(messageChannel, opt_interval) {
48 goog.Disposable.call(this);
49
50 /**
51 * Buffer of messages to be sent when the channel's peer is ready.
52 *
53 * @type {Array<Object>}
54 * @private
55 */
56 this.buffer_ = [];
57
58 /**
59 * Channel dispatcher wrapping the underlying delegate channel.
60 *
61 * @type {!goog.messaging.MultiChannel}
62 * @private
63 */
64 this.multiChannel_ = new goog.messaging.MultiChannel(messageChannel);
65
66 /**
67 * Virtual channel for carrying the user's messages.
68 *
69 * @type {!goog.messaging.MessageChannel}
70 * @private
71 */
72 this.userChannel_ = this.multiChannel_.createVirtualChannel(
73 goog.messaging.BufferedChannel.USER_CHANNEL_NAME_);
74
75 /**
76 * Virtual channel for carrying control messages for BufferedChannel.
77 *
78 * @type {!goog.messaging.MessageChannel}
79 * @private
80 */
81 this.controlChannel_ = this.multiChannel_.createVirtualChannel(
82 goog.messaging.BufferedChannel.CONTROL_CHANNEL_NAME_);
83
84 /**
85 * Timer for the peer ready ping loop.
86 *
87 * @type {goog.Timer}
88 * @private
89 */
90 this.timer_ = new goog.Timer(
91 opt_interval || goog.messaging.BufferedChannel.DEFAULT_INTERVAL_MILLIS_);
92
93 this.timer_.start();
94 goog.events.listen(
95 this.timer_, goog.Timer.TICK, this.sendReadyPing_, false, this);
96
97 this.controlChannel_.registerService(
98 goog.messaging.BufferedChannel.PEER_READY_SERVICE_NAME_,
99 goog.bind(this.setPeerReady_, this));
100 };
101 goog.inherits(goog.messaging.BufferedChannel, goog.Disposable);
102
103
104 /**
105 * Default polling interval (in ms) for setPeerReady_ notifications.
106 *
107 * @type {number}
108 * @const
109 * @private
110 */
111 goog.messaging.BufferedChannel.DEFAULT_INTERVAL_MILLIS_ = 50;
112
113
114 /**
115 * The name of the private service which handles peer ready pings. The
116 * service registered with this name is bound to this.setPeerReady_, an internal
117 * part of BufferedChannel's implementation that clients should not send to
118 * directly.
119 *
120 * @type {string}
121 * @const
122 * @private
123 */
124 goog.messaging.BufferedChannel.PEER_READY_SERVICE_NAME_ = 'setPeerReady_';
125
126
127 /**
128 * The name of the virtual channel along which user messages are sent.
129 *
130 * @type {string}
131 * @const
132 * @private
133 */
134 goog.messaging.BufferedChannel.USER_CHANNEL_NAME_ = 'user';
135
136
137 /**
138 * The name of the virtual channel along which internal control messages are
139 * sent.
140 *
141 * @type {string}
142 * @const
143 * @private
144 */
145 goog.messaging.BufferedChannel.CONTROL_CHANNEL_NAME_ = 'control';
146
147
148 /** @override */
149 goog.messaging.BufferedChannel.prototype.connect = function(opt_connectCb) {
150 if (opt_connectCb) {
151 opt_connectCb();
152 }
153 };
154
155
156 /** @override */
157 goog.messaging.BufferedChannel.prototype.isConnected = function() {
158 return true;
159 };
160
161
162 /**
163 * @return {boolean} Whether the channel's peer is ready.
164 */
165 goog.messaging.BufferedChannel.prototype.isPeerReady = function() {
166 return this.peerReady_;
167 };
168
169
170 /**
171 * Logger.
172 *
173 * @type {goog.log.Logger}
174 * @const
175 * @private
176 */
177 goog.messaging.BufferedChannel.prototype.logger_ =
178 goog.log.getLogger('goog.messaging.bufferedchannel');
179
180
181 /**
182 * Handles one tick of our peer ready notification loop. This entails sending a
183 * ready ping to the peer and shutting down the loop if we've received a ping
184 * ourselves.
185 *
186 * @private
187 */
188 goog.messaging.BufferedChannel.prototype.sendReadyPing_ = function() {
189 try {
190 this.controlChannel_.send(
191 goog.messaging.BufferedChannel.PEER_READY_SERVICE_NAME_,
192 /* payload */ this.isPeerReady() ? '1' : '');
193 } catch (e) {
194 this.timer_.stop(); // So we don't keep calling send and re-throwing.
195 throw e;
196 }
197 };
198
199
200 /**
201 * Whether or not the peer channel is ready to receive messages.
202 *
203 * @type {boolean}
204 * @private
205 */
206 goog.messaging.BufferedChannel.prototype.peerReady_;
207
208
209 /** @override */
210 goog.messaging.BufferedChannel.prototype.registerService = function(
211 serviceName, callback, opt_objectPayload) {
212 this.userChannel_.registerService(serviceName, callback, opt_objectPayload);
213 };
214
215
216 /** @override */
217 goog.messaging.BufferedChannel.prototype.registerDefaultService = function(
218 callback) {
219 this.userChannel_.registerDefaultService(callback);
220 };
221
222
223 /**
224 * Send a message over the channel. If the peer is not ready, the message will
225 * be buffered and sent once we've received a ready message from our peer.
226 *
227 * @param {string} serviceName The name of the service this message should be
228 * delivered to.
229 * @param {string|!Object} payload The value of the message. If this is an
230 * Object, it is serialized to JSON before sending. It's the responsibility
231 * of implementors of this class to perform the serialization.
232 * @see goog.net.xpc.BufferedChannel.send
233 * @override
234 */
235 goog.messaging.BufferedChannel.prototype.send = function(serviceName, payload) {
236 if (this.isPeerReady()) {
237 this.userChannel_.send(serviceName, payload);
238 } else {
239 goog.log.fine(
240 goog.messaging.BufferedChannel.prototype.logger_,
241 'buffering message ' + serviceName);
242 this.buffer_.push({serviceName: serviceName, payload: payload});
243 }
244 };
245
246
247 /**
248 * Marks the channel's peer as ready, then sends buffered messages and nulls the
249 * buffer. Subsequent calls to setPeerReady_ have no effect.
250 *
251 * @param {(!Object|string)} peerKnowsWeKnowItsReady Passed by the peer to
252 * indicate whether it knows that we've received its ping and that it's
253 * ready. Non-empty if true, empty if false.
254 * @private
255 */
256 goog.messaging.BufferedChannel.prototype.setPeerReady_ = function(
257 peerKnowsWeKnowItsReady) {
258 if (peerKnowsWeKnowItsReady) {
259 this.timer_.stop();
260 } else {
261 // Our peer doesn't know we're ready, so restart (or continue) pinging.
262 // Restarting may be needed if the peer iframe was reloaded after the
263 // connection was first established.
264 this.timer_.start();
265 }
266
267 if (this.peerReady_) {
268 return;
269 }
270 this.peerReady_ = true;
271 // Send one last ping so that the peer knows we know it's ready.
272 this.sendReadyPing_();
273 for (var i = 0; i < this.buffer_.length; i++) {
274 var message = this.buffer_[i];
275 goog.log.fine(
276 goog.messaging.BufferedChannel.prototype.logger_,
277 'sending buffered message ' + message.serviceName);
278 this.userChannel_.send(message.serviceName, message.payload);
279 }
280 this.buffer_ = null;
281 };
282
283
284 /** @override */
285 goog.messaging.BufferedChannel.prototype.disposeInternal = function() {
286 goog.dispose(this.multiChannel_);
287 goog.dispose(this.timer_);
288 goog.messaging.BufferedChannel.base(this, 'disposeInternal');
289 };