Commit 86d9dd15612f0d13322babe402aae1518e6b0396
Merge pull request #34 from dominictarr/abort-docs
document stream endingDominic Tarr committed on 9/13/2015, 10:33:30 AM
Parent: 9df8c564ee036bded7aa2f235668ef3cb87db11d
Parent: 66cac3c056c184eb58ccbdd628cb74b1917bb4ab
Files changed
| README.md | changed |
| README.md | ||
|---|---|---|
| @@ -260,7 +260,53 @@ | ||
| 260 | 260 | are not there. |
| 261 | 261 | |
| 262 | 262 | This makes laziness work right. |
| 263 | 263 | |
| 264 | +### handling end, error, and abort. | |
| 265 | + | |
| 266 | +in pull streams, any part of the stream (source, sink, or through) | |
| 267 | +may terminate the stream. (this is the case with node streams too, | |
| 268 | +but it's not handled well). | |
| 269 | + | |
| 270 | +#### source: end, error | |
| 271 | + | |
| 272 | +A source may end (`cb(true)` after read) or error (`cb(error)` after read) | |
| 273 | +After ending, the source *must* never `cb(null, data)` | |
| 274 | + | |
| 275 | +#### sink: abort | |
| 276 | + | |
| 277 | +Sinks do not normally end the stream, but if they decide they do | |
| 278 | +not need any more data they may "abort" the source by calling `read(true, cb)`. | |
| 279 | +A abort (`read(true, cb)`) may be called before a preceding read call | |
| 280 | +has called back. | |
| 281 | + | |
| 282 | +### handling end/abort/error in through streams | |
| 283 | + | |
| 284 | +Rules for implementing `read` in a through stream: | |
| 285 | +1) Sink wants to stop. sink aborts the through | |
| 286 | + | |
| 287 | + just forward the exact read() call to your source, | |
| 288 | + any future read calls should cb(true). | |
| 289 | + | |
| 290 | +2) We want to stop. (abort from the middle of the stream) | |
| 291 | + | |
| 292 | + abort your source, and then cb(true) to tell the sink we have ended. | |
| 293 | + If the source errored during abort, end the sink by cb read with `cb(err)`. | |
| 294 | + (this will be an ordinary end/error for the sink) | |
| 295 | + | |
| 296 | +3) Source wants to stop. (`read(null, cb) -> cb(err||true)`) | |
| 297 | + | |
| 298 | + forward that exact callback towards the sink chain, | |
| 299 | + we must respond to any future read calls with `cb(err||true)`. | |
| 300 | + | |
| 301 | +In none of the above cases data is flowing! | |
| 302 | +4) If data is flowing (normal operation: `read(null, cb) -> cb(null, data)` | |
| 303 | + | |
| 304 | + forward data downstream (towards the Sink) | |
| 305 | + do none of the above! | |
| 306 | + | |
| 307 | +There either is data flowing (4) OR you have the error/abort cases (1-3), never both. | |
| 308 | + | |
| 309 | + | |
| 264 | 310 | ## License |
| 265 | 311 | |
| 266 | 312 | MIT |
Built with git-ssb-web