From f09d0cd93c3458717b274d4e480861ce1cde1186 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Geisend=C3=B6rfer?= <felix@debuggable.com>
Date: Mon, 12 Oct 2009 17:03:16 +0200
Subject: [PATCH] Documentation for Promise.timeout() and Promise.cancel()

---
 doc/api.txt | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/api.txt b/doc/api.txt
index ba27d91fdc5..b06a3b78a88 100644
--- a/doc/api.txt
+++ b/doc/api.txt
@@ -205,6 +205,7 @@ emit anymore events.
 | Event       | Parameters       | Notes
 | +"success"+ | (depends)        |
 | +"error"+   | (depends)        |
+| +"cancel"+  | (depends)        |
 |=========================================================
 
 +promise.addCallback(listener)+ ::
@@ -213,6 +214,9 @@ Adds a listener for the +"success"+ event. Returns the same promise object.
 +promise.addErrback(listener)+ ::
 Adds a listener for the +"error"+ event. Returns the same promise object.
 
++promise.addCancelback(listener)+ ::
+Adds a listener for the +"cancel"+ event. Returns the same promise object.
+
 +promise.emitSuccess(arg1, arg2, ...)+ ::
 If you created the promise (by doing +new node.Promise()+) then call
 +emitSuccess+ to emit the +"success"+ event with the given arguments. 
@@ -223,6 +227,37 @@ the moment due to a bug; use +emitSuccess+ instead.)
 +promise.emitError(arg1, arg2, ...)+ ::
 Emits the +"error"+ event.
 
++promise.emitCancel(arg1, arg2, ...)+ ::
+Emits the +"cancel"+ event. You may still get a +"success"+ or +"error"+
+callback if the promise giver does not handle the cancel event. Use
++promise.cancel()+ to ignore any later events.
+
++promise.cancel()+ ::
+Clears all +"success"+ and +"error"+ event listeners from the promise, then
+emits the +"cancel"+ event. Whether or not the promise is actually canceled
+or not depends on the promise giver.
+
++promise.timeout(timeout = undefined)+ ::
+If the +timeout+ parameter is provided, the promise will emit an +"error"+
+event after the given amount of millseconds. The timeout is canceled by any
++"success"+, +"error"+ or +"cancel"+ event being emitted by the Promise.
++
+To tell apart a timeout from a regular "error" event, use the following test:
++
+----------------------------------------
+promise.addErrback(function(e) {
+  if (e instanceof Error && e.message === 'timeout') {
+    // handle timeout
+  } else {
+    // handle regular error
+  }
+});
+----------------------------------------
++
+If the +timeout+ parameter is not provided, the current timeout value, if any,
+is returned.
++
+
 +promise.wait()+ ::
 Blocks futher execution until the promise emits a success or error event.
 Events setup before the call to +promise.wait()+ was made may still be