Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

REMASTERPIECE

  • Loading branch information...
commit fbaa92c607f1d64845b1897114e76d209bf0cecc 1 parent 1ff06b2
@dominictarr authored
Showing with 88 additions and 21 deletions.
  1. +88 −21 states.markdown
View
109 states.markdown
@@ -1,35 +1,69 @@
+# Stream state diagrams.
+
+interperetation of these diagrams:
+boxes are states. arrows are transitions.
+transitions are labled with the events which cause those
+transitions. if an event is mentioned on the diagram,
+but is not on a transition from a particular state,
+it means that event is forbidden in that state.
+
+if an event is not mentioned in a diagram, then
+that event is not forbidden, just irrelevant.
+
+where events are listed next to a transition, it
+means that any of those events may cause that transition.
+
+combining diagrams: I have represented stream behaviour
+across multiple diagrams for simplicity.
+Stream implementations must satisify all relevant diagrams.
## write / pause
```
-write()===false write()==false
- .--. .--.
- | | | |
- | v | v
- .----------. write()===false .----------.
- | |----------------->| |
- | !paused, | | paused, |
- | writable |<-----------------| writable |
- | | 'drain' | |
- `----------` `----------`
+write()===false write()==false
+ .--. .--.
+ | | | |
+ | v | v
+ .---------. write()===false .--------.
+ | |----------------->| |
+ | !paused | | paused |
+ | |<-----------------| |
+ `---------` 'drain' `--------`
```
+A `WritableStream` must emit `'drain'` to leave the paused state.
+A `WritableStream` may only return `false` from `write()` when paused.
+
## writable/!writable
```
-write(), 'drain'
+ write(), 'drain'
.--.
| |
| v
- .----------. .-----------. .--------.
- | |--------------->| |-------->| |
- | writable | end(), | !writable | 'close' | closed |
- | | 'error', | | | |
- `----------` destroy() `-----------` `--------`
+ .----------. .-----------.
+ | |--------------->| |
+ | writable | end(), | !writable |
+ | | destroy() | |
+ `----------` `-----------`
+ | |
+ | | 'error', 'close'
+ | v
+ | .-----------.
+ | 'error' | |
+ `-------------------- | closed, |
+ | !writable |
+ | |
+ `-----------`
```
+
+A `WritableStream` may not emit 'drain' or permit `write()` after `end()`, `'error'`
+or `destroy()` have occured.
+A `WritableStream` must eventually emit `'close'`, unless there is an 'error'.
+
## read / pause (strict)
```
@@ -45,6 +79,28 @@ write(), 'drain'
```
+A strict `ReadableStream` must not emit 'data' or 'end' when in the paused state.
+In `0.8` most core node streams are now strict.
+
+## read / pause (loose)
+
+```
+'data', 'end',
+pause(), resume()
+ .--.
+ | |
+ | v
+ .---------.
+ | |
+ | paused, |
+ | !paused |
+ `---------`
+
+```
+
+A unstrict `ReadableStream` should _try_ not to emit 'data' or 'end' when paused.
+In `0.8` most core node streams are now strict.
+
## readable / !readable
```
@@ -52,12 +108,23 @@ write(), 'drain'
.--.
| |
| v
- .----------. .-----------. .--------.
- | |--------------->| |-------->| |
- | readable | 'end', | !readable | 'close' | closed |
- | | 'error', | | | |
- `----------` destroy() `-----------` `--------`
+ .----------. .-----------.
+ | |--------------->| |
+ | readable | 'end', | !readable |
+ | | destroy() | |
+ `----------` `-----------`
+ | |
+ | | 'error', 'close'
+ | v
+ | .-----------.
+ | 'error' | |
+ `-------------------- | closed, |
+ | !readable |
+ | |
+ `-----------`
```
+A `ReadableStream` must not emit 'data' after 'end', 'error', or destroy().
+A `ReadableStream` must then eventually emit `'close'`, unless there was an 'error'.
Please sign in to comment.
Something went wrong with that request. Please try again.