add comments

Author: cmather

async/main.js

@@ -1,10 +1,18 @@
 #!/usr/local/bin/node
 
+// Import other code modules
 var mongo = require('./mongo_sim');
 var Fiber = require('fibers');
 var Future = require('fibers/future');
 
 /*
+ * "Callback hell" is when we have to nest callback functions in order to
+ *  control the order of execution. It can get very difficult to read!
+ */
+
+/*
+Example of callback hell:
+
 mongo.getCollection('items', function (err, collection) {
   collection.findOne({_id: 5}, function (err, result) {
     console.log("Few! Finally got a result");
@@ -13,7 +21,11 @@ mongo.getCollection('items', function (err, collection) {
 });
 */
 
-
+/**
+ * We can use the Fibers library to turn asynchronous code into synchronous
+ * code. It makes it easier to read. You can "yield" a fiber which only blocks
+ * the code within it, and not the entire event loop.
+ */
 var tryUsingFibers = function () {
   Fiber(function () {
     var fiber = Fiber.current;
@@ -29,6 +41,12 @@ var tryUsingFibers = function () {
   }).run();
 };
 
+/**
+ * Futures is a nice api on top of Fibers and is the preferred way to work with
+ * Fibers. Notice the future can "wait" which will yield the current fiber.
+ * It can also "return" which will resume execution where we left off with
+ * the "wait()" call.
+ */
 var tryUsingFutures = function () {
   var myFunc = function () {
     var future = new Future;
@@ -44,6 +62,11 @@ var tryUsingFutures = function () {
   Fiber(myFunc).run();
 };
 
+/**
+ * Here's where we create a fiber and run it. Notice we pass in a function.
+ * This is the code that will be executed inside the fiber and can be "paused"
+ * by "yielding" the fiber.
+ */
 Fiber(function () {
   var collection = mongo.getCollection('items');
   var doc = collection.findOne({_id: 5});

async/mongo_sim.js

@@ -1,11 +1,23 @@
 var Future = require('fibers/future');
 
 var findOne = function (sel, callback) {
+  // create a new future
   var future = new Future;
+
+  // put this callback function back on the event loop (queue) in 2 seconds.
+  // It will execute when it makes its way to the front of the line. This code
+  // is called "asynchronous" because it executes at a *later time* on the
+  // event loop.
   setTimeout(function () {
+
+    // return a value at the point where we called "wait"
     future.return({title: "My great title!"});
   }, 2000);
 
+  // pause execution of the fiber here. When we return the future, execution
+  // will resume at this point, and the value returned from future.wait() will
+  // be the parameter passed into future.return. In this case the value will
+  // be the object: {title: "My great title"}
   return future.wait();
 };
 
@@ -18,6 +30,9 @@ getCollection = function (name, callback) {
   return future.wait();
 };
 
+/**
+ * Export an object we can use in other files that import this one.
+ */
 module.exports = {
   getCollection: getCollection
 };

pubsub/pubsub.js

@@ -5,12 +5,68 @@ if (Meteor.isClient) {
     }
   });
 
-  Meteor.subscribe('allItems');
+  Meteor.subscribe('one');
+  Meteor.subscribe('two');
 }
 
 if (Meteor.isServer) {
+  var Future = Npm.require('fibers/future');
+
+  Meteor.publish('one', function () {
+    var future = new Future;
+
+    // send an "added" ddp message
+    this.added('items', Random.id(), {title: 'one'});
+
+    // send a "ready" ddp message
+    this.ready();
+
+    setTimeout(function () {
+      future.return();
+    }, 5000);
+
+    // Careful! This will block. Try not to block publish functions by yielding
+    // the fiber. For example, don't make external API calls. You can, however,
+    // put that code in a setTimeout to make it run outside this current fiber.
+    // That will result in not blocking downstream publish functions from
+    // running.
+    return future.wait();
+  });
+
+  Meteor.publish('two', function () {
+    this.added('items', Random.id(), {title: 'two'});
+    this.ready();
+  });
+
+
   Meteor.publish('allItems', function () {
-    return Items.find({},{sort: {order: 1}});
+    var subscription = this;
+    var cursor = Items.find({parentId: 4},{sort: {order: 1}});
+
+    // observeChanges is what hooks DDP up to the Mongo database for real time
+    // updates. Every time a document that affects this cursor is added, changed
+    // or removed, the corresponding callbacks here will be called. Then
+    // the appropriate ddp messages are published to the client. The DDP server
+    // takes care of making sure a client doesn't get duplicate messages.
+    var handle = cursor.observeChanges({
+      added: function (id, doc) {
+        subscription.added('items', id, doc);
+      },
+
+      changed: function (id, doc) {
+        subscription.changed('items', id, doc);
+      },
+
+      removed: function (id) {
+        subscription.removed(id);
+      }
+    });
+
+    subscription.ready();
+
+    subscription.onStop(function () {
+      handle.stop();
+    });
   });
 
   Meteor.publish('item', function (id) {