Add comment to makeAsync().

nodejs · Aug 23, 2011 · 528cd4a · bnoordhuis · Aug 23, 2011 · koichik
1 parent 1aed45e
commit 528cd4a
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 2 deletions.
diff --git a/lib/dns_legacy.js b/lib/dns_legacy.js
@@ -91,7 +91,22 @@ var channel = new dns.Channel({SOCK_STATE_CB: function(socket, read, write) {
   updateTimer();
 }});
 
-// Make sure that the callback is invoked asynchronously.
+// c-ares invokes a callback both synchronously and asynchronously,
+// but the dns API should always invoke a callback asynchronously.
+// 
+// This function makes sure that the callback is invoked asynchronously.
+// It returns a function that invokes the callback within nextTick().
+// 
+// To avoid invoking unnecessary nextTick(), `immediately` property of
+// returned function should be set to true after c-ares returned.
+// 
+// Usage:
+// 
+// function someAPI(callback) {
+//   callback = makeAsync(callback);
+//   channel.someAPI(..., callback);
+//   callback.immediately = true;
+// }
 function makeAsync(callback) {
   if (typeof callback !== 'function') {
     return callback;

diff --git a/lib/dns_uv.js b/lib/dns_uv.js
@@ -52,7 +52,22 @@ function symToFamily(family) {
   }
 }
 
-// Make sure that the callback is invoked asynchronously.
+// c-ares invokes a callback both synchronously and asynchronously,
+// but the dns API should always invoke a callback asynchronously.
+// 
+// This function makes sure that the callback is invoked asynchronously.
+// It returns a function that invokes the callback within nextTick().
+//  
+// To avoid invoking unnecessary nextTick(), `immediately` property of
+// returned function should be set to true after c-ares returned.
+//  
+// Usage: 
+//    
+// function someAPI(callback) {
+//   callback = makeAsync(callback);
+//   channel.someAPI(..., callback);
+//   callback.immediately = true;
+// }
 function makeAsync(callback) {
   if (typeof callback !== 'function') {
     return callback;