diff options
| -rw-r--r-- | docs/api.md | 15 | ||||
| -rw-r--r-- | lib/torrent.js | 13 |
2 files changed, 22 insertions, 6 deletions
diff --git a/docs/api.md b/docs/api.md index eca7144..2ea80d0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -152,6 +152,13 @@ client.seed(buf, cb) Emitted when a torrent is ready to be used (i.e. metadata is available and store is ready). See the torrent section for more info on what methods a `torrent` has. +## `client.on('error', function (err) {})` + +Emitted when the client encounters a fatal error. The client is automatically +destroyed and all torrents are removed and cleaned up when this occurs. + +Always listen for the 'error' event. + ## `client.remove(torrentId, [function callback (err) {}])` Remove a torrent from the client. Destroy all connections to peers and delete all saved @@ -371,6 +378,14 @@ listen to this event, but it may aid in debugging. Emitted when the torrent encounters a fatal error. The torrent is automatically destroyed and removed from the client when this occurs. +**Note:** Torrent errors are emitted at `torrent.on('error')`. If there are no +'error' event handlers on the torrent instance, then the error will be emitted at +`client.on('error')`. This prevents throwing an uncaught exception (unhandled +'error' event), but it makes it impossible to distinguish client errors versus +torrent errors. Torrent errors are not fatal, and the client is still usable +afterwards. Therefore, always listen for errors in both places +(`client.on('error')` and `torrent.on('error')`). + ## `torrent.on('done', function () {})` Emitted when all the torrent files have been downloaded. diff --git a/lib/torrent.js b/lib/torrent.js index e4bedef..5d2150b 100644 --- a/lib/torrent.js +++ b/lib/torrent.js @@ -677,12 +677,13 @@ Torrent.prototype._destroy = function (err, cb) { parallel(tasks, cb) if (err) { - // Torrent errors are emitted at `torrent.on('error')`. If there are no 'error' event - // handlers on the torrent instance, the error will be emitted at - // `client.on('error')`. This prevents crashing the user's program, but it makes it - // impossible to determine a client error versus a torrent error (where the client - // is still usable afterwards). Users are recommended for errors in both places - // to distinguish between the error types. + // Torrent errors are emitted at `torrent.on('error')`. If there are no 'error' + // event handlers on the torrent instance, then the error will be emitted at + // `client.on('error')`. This prevents throwing an uncaught exception + // (unhandled 'error' event), but it makes it impossible to distinguish client + // errors versus torrent errors. Torrent errors are not fatal, and the client + // is still usable afterwards. Therefore, always listen for errors in both + // places (`client.on('error')` and `torrent.on('error')`). if (self.listenerCount('error') === 0) { self.client.emit('error', err) } else { |