Changeset 14654 for trunk/FACT++/scripts/doc

Timestamp:

11/18/12 22:46:36 (12 years ago)

Author:

tbretz

Message:

Updated

File:

• trunk/FACT++/scripts/doc/Subscription.js (modified) (2 diffs)

trunk/FACT++/scripts/doc/Subscription.js

@@ -7 +7 @@
  * @class
  *
- * Creates a handle to a new thread. The handle can be used to
- * kill the thread or be ignored. The function provided is
- * executed after an initial timeout. Note that although this
- * looks similar to the setTimeout in web-browsers, after started,
- * the thread will not run until completion but run in parallel to
- * the executed script.<P>
+ * Subscription to a DIM service.
  *
- * Note that although the object is created with 'new' and there
- * is a 'delete' is JavaScript, it will not call any kind of
- * destructor. To close a Subscription you have to explicitly call
- * the close() member function. 'delete' in JavaScript is only
- * to remove a property from an Object.
+ * This class represents the subscription to a DIM service. Received
+ * events are first copied to an even queue internally, to avoid
+ * any processing blocking the DIM thread (which could block the
+ * whole network as a result). Then the events are processed.
+ * If a callback is installed, the processing will take place in
+ * another JavaScript thread. Physically it will run synchronously
+ * with the other JavaScript threads. However, the processing blocks
+ * event processing. Consequetly, processing should on average be
+ * faster than the frequency with which events arrive to ensure they
+ * will not fill up the memory and possible reactions to there
+ * contents will happen within a reasonable time and not delayed
+ * too much.
  *
- * @param {Integer} timeout
- *    A positive integer given the initial delay in milliseconds before
- *    the thread is executed.
+ * @param {String} service
+ *    Name of the DIM service to which a subscription should be made.
+ *    Usully of the form SERVER/SUBSCRIPTION.
  *
- * @param {Function} function
- *    A function which is executed aftr the initial timeout.
+ * @param {Function} [callback]
+ *    An optional function which is set as 'onchange' property.
+ *    This can avoid to loose th first event after the subscription
+ *    before the callback is set by the 'onchange' property (which
+ *    is very unlikely).
  *
  * @throws
- *    <li> If number or type of arguments is wrong
+ *    <li>If number or type of arguments is wrong
+ *    <li>If an open subscription to the same service already exists.
  *
  * @example
- *    var handle = new Thread(100, function() { dim.out("Hello world!"); });
- *    handle.kill();
+ *    var handle1 = new Subscription("MAGIC_WEATHER/DATA");
+ *    var handle2 = new Subscription("TNG_WEATHER/DATA", function(evt) { dim.out(JSON.stringify(evt)); });
+ *    ...
+ *    handle2.close();
+ *    handle1.close();
  */
-function Subscription(service)
+function Subscription(service, callback)
 {
     /**
@@ -68 +77 @@
      *
      * @example
-     *     subscription.onchange = function(event) { dim.out(JSON.stringify(event); };
+     *     handle.onchange = function(event) { dim.out(JSON.stringify(event); };
      *
      */
-    this.onchange = func;
+    this.onchange = callback;
 
     /**