Permalink
Browse files

docs and a simpler discard example

  • Loading branch information...
1 parent 7b72f9e commit 44c0aa5d07732de638ece52961cac49bf74e16e2 @substack committed Jan 14, 2012
Showing with 98 additions and 10 deletions.
  1. +77 −2 README.markdown
  2. +14 −0 example/discard.js
  3. +7 −8 example/http.js
View
@@ -1,7 +1,82 @@
toss
====
-Throw away asynchronous transactions.
+Discard groups of asynchronous transactions.
-It's like domains but without doing any core stuff, just as a function wrapper.
+This is a handy module for cancelling nested asynchronous logic when some
+external event comes along like a timeout that should abort an entire
+transaction.
+Toss is like domains in node but implemented as a function wrapper instead of a
+something in core.
+
+example
+=======
+
+``` js
+var toss = require('toss');
+var fs = require('fs');
+
+var t = toss(10, function (err) {
+ console.log('reads took to long');
+});
+
+fs.readFile(__filename, t(function (err, body) {
+ if (err) t.error(err)
+ else fs.readFile(__filename + '/no_such_file', t(function (err, body) {
+ if (err) t.error(err)
+ else t.end()
+ }))
+}));
+```
+
+methods
+=======
+
+var toss = require('toss')
+
+var t = toss(timeout=0, cb)
+---------------------------
+
+Create a toss function `t` with an optional `timeout` and an optional error
+callback `cb`.
+
+`cb` fires when a callback is attempted after `t.end()` is called
+or when `t.error()` is explicitly called.
+
+If `timeout` is specified and `t.end()` hasn't been called in `timeout`
+milliseconds, `t.end()` will be called automatically.
+
+t(timeout=0, cb)
+----------------
+
+Returns a function that calls `cb` with the arguments provided unless `t.end()`
+has been called, in which case the callback from `toss()` is called.
+
+Put this function around the callbacks that you want to group together.
+
+t.end()
+-------
+
+After this function is called, all calls to functions wrapped with `t()` will be
+ignored and the callback from `toss()` will fire.
+
+t.error(err)
+------------
+
+Executes `t.end()` then triggers the callback from `toss()` with the `err`
+object.
+
+install
+=======
+
+With [npm](http://npmjs.org) do:
+
+```
+npm install toss
+```
+
+license
+=======
+
+MIT/X11
View
@@ -0,0 +1,14 @@
+var toss = require('../');
+var fs = require('fs');
+
+var t = toss(10, function (err) {
+ console.log('reads took to long');
+});
+
+fs.readFile(__filename, t(function (err, body) {
+ if (err) t.error(err)
+ else fs.readFile(__filename + '/no_such_file', t(function (err, body) {
+ if (err) t.error(err)
+ else t.end()
+ }))
+}));
View
@@ -11,21 +11,20 @@ function get (cb) {
});
}
-function ready () {
+var server = http.createServer(function (req, res) {
+ setTimeout(function () {
+ res.end('beeeeeeeeeeeeeeeeeeeeeeeeep');
+ }, 600);
+});
+
+server.listen(8800, function () {
get(t(function () {
get(t(function () {
console.log('finished');
t.end();
}));
}));
-}
-
-var server = http.createServer(function (req, res) {
- setTimeout(function () {
- res.end('beeeeeeeeeeeeeeeeeeeeeeeeep');
- }, 600);
});
-server.listen(8800, ready);
setTimeout(function () {
server.close();

0 comments on commit 44c0aa5

Please sign in to comment.