{"action":"created","comment":{"url":"https://api.github.com/repos/nodejs/node/pulls/comments/64421161","id":64421161,"diff_hunk":"@@ -90,60 +97,224 @@ server.listen(1337);\n // error: Unexpected token o\n ```\n \n-### Class: stream.Duplex\n+[Writable][] streams (such as `res` in the example) expose methods such as\n+`write()` and `end()` that are used to write data onto the stream.\n \n-Duplex streams are streams that implement both the [Readable][] and\n-[Writable][] interfaces.\n+[Readable][] streams use the [`EventEmitter`] API for notifying application\n+code when data is available to be read, or has been read, off the stream.\n \n-Examples of Duplex streams include:\n+[Duplex][] and [Transform][] streams are both [Writable][] and [Readable][].\n \n-* [TCP sockets][]\n+Applications that are either writing data to or consuming data from a stream\n+are not required to implement the stream interfaces directly and will generally\n+have no reason to call `require('stream')`.\n+\n+Developers wishing to implement new types of streams should refer to the\n+section [API for Stream Implementors][].\n+\n+### Writable Streams\n+\n+Writable streams are an abstraction for a *destination* to which data is\n+written.\n+\n+Examples of [Writable][] streams include:\n+\n+* [HTTP requests, on the client][]\n+* [HTTP responses, on the server][]\n+* [fs write streams][]\n * [zlib streams][zlib]\n * [crypto streams][crypto]\n+* [TCP sockets][]\n+* [child process stdin][]\n+* [`process.stdout`][], [`process.stderr`][]\n \n-### Class: stream.Readable\n+All [Writable][] streams implement the interface defined by the\n+`stream.Writable` class.\n+\n+While specific instances of [Writable][] streams may differ in various ways,\n+all Writable streams follow the same fundamental usage pattern as illustrated\n+in the example below:\n+\n+```js\n+const myStream = getWritableStreamSomehow();\n+myStream.write('some data');\n+myStream.write('some more data');\n+myStream.end('done writing data');\n+```\n+\n+#### Class: stream.Writable\n \n <!--type=class-->\n \n-The Readable stream interface is the abstraction for a *source* of\n-data that you are reading from. In other words, data comes *out* of a\n-Readable stream.\n+##### Event: 'close'\n \n-A Readable stream will not start emitting data until you indicate that\n-you are ready to receive it.\n+The `'close'` event is emitted when the stream and any of its underlying\n+resources (a file descriptor, for example) have been closed. The event indicates\n+that no more events will be emitted, and no further computation will occur.\n \n-Readable streams have two \"modes\": a **flowing mode** and a **paused\n-mode**. When in flowing mode, data is read from the underlying system\n-and provided to your program as fast as possible. In paused mode, you\n-must explicitly call [`stream.read()`][stream-read] to get chunks of data out.\n-Streams start out in paused mode.\n+Not all Writable streams will emit the `'close'` event.\n \n-**Note**: If no data event handlers are attached, and there are no\n-[`stream.pipe()`][] destinations, and the stream is switched into flowing\n-mode, then data will be lost.\n+##### Event: 'drain'\n \n-You can switch to flowing mode by doing any of the following:\n+If a call to [`stream.write(chunk)`][stream-write] returns `false`, the\n+`'drain'` event will be emitted when it is appropriate to resume writing data\n+to the stream.\n \n-* Adding a [`'data'`][] event handler to listen for data.\n-* Calling the [`stream.resume()`][stream-resume] method to explicitly open the\n-  flow.\n-* Calling the [`stream.pipe()`][] method to send the data to a [Writable][].\n+```js\n+// Write the data to the supplied writable stream one million times.\n+// Be attentive to back-pressure.\n+function writeOneMillionTimes(writer, data, encoding, callback) {\n+  var i = 1000000;\n+  write();\n+  function write() {\n+    var ok = true;\n+    do {\n+      i--;\n+      if (i === 0) {\n+        // last time!\n+        writer.write(data, encoding, callback);\n+      } else {\n+        // see if we should continue, or wait\n+        // don't pass the callback, because we're not done yet.\n+        ok = writer.write(data, encoding);\n+      }\n+    } while (i > 0 && ok);\n+    if (i > 0) {\n+      // had to stop early!\n+      // write some more once it drains\n+      writer.once('drain', write);\n+    }\n+  }\n+}\n+```","path":"doc/api/stream.md","position":229,"original_position":229,"commit_id":"e6907a1a8c3d328e6630d4641110dff03af83bee","original_commit_id":"e6907a1a8c3d328e6630d4641110dff03af83bee","user":{"login":"mcollina","id":52195,"avatar_url":"https://avatars.githubusercontent.com/u/52195?v=3","gravatar_id":"","url":"https://api.github.com/users/mcollina","html_url":"https://github.com/mcollina","followers_url":"https://api.github.com/users/mcollina/followers","following_url":"https://api.github.com/users/mcollina/following{/other_user}","gists_url":"https://api.github.com/users/mcollina/gists{/gist_id}","starred_url":"https://api.github.com/users/mcollina/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mcollina/subscriptions","organizations_url":"https://api.github.com/users/mcollina/orgs","repos_url":"https://api.github.com/users/mcollina/repos","events_url":"https://api.github.com/users/mcollina/events{/privacy}","received_events_url":"https://api.github.com/users/mcollina/received_events","type":"User","site_admin":false},"body":"@jasnell I think these two tasks needs to be paired up and part of a single PR. I would prefer to leave this just to the API (users vs implementors), and have a full discussion on the stream state machine and backpressure on another document.","created_at":"2016-05-24T16:00:45Z","updated_at":"2016-05-24T16:00:45Z","html_url":"https://github.com/nodejs/node/pull/6947#discussion_r64421161","pull_request_url":"https://api.github.com/repos/nodejs/node/pulls/6947","_links":{"self":{"href":"https://api.github.com/repos/nodejs/node/pulls/comments/64421161"},"html":{"href":"https://github.com/nodejs/node/pull/6947#discussion_r64421161"},"pull_request":{"href":"https://api.github.com/repos/nodejs/node/pulls/6947"}}},"pull_request":{"url":"https://api.github.com/repos/nodejs/node/pulls/6947","id":71159935,"html_url":"https://github.com/nodejs/node/pull/6947","diff_url":"https://github.com/nodejs/node/pull/6947.diff","patch_url":"https://github.com/nodejs/node/pull/6947.patch","issue_url":"https://api.github.com/repos/nodejs/node/issues/6947","number":6947,"state":"open","locked":false,"title":"doc: general improvements to stream.md copy","user":{"login":"jasnell","id":439929,"avatar_url":"https://avatars.githubusercontent.com/u/439929?v=3","gravatar_id":"","url":"https://api.github.com/users/jasnell","html_url":"https://github.com/jasnell","followers_url":"https://api.github.com/users/jasnell/followers","following_url":"https://api.github.com/users/jasnell/following{/other_user}","gists_url":"https://api.github.com/users/jasnell/gists{/gist_id}","starred_url":"https://api.github.com/users/jasnell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasnell/subscriptions","organizations_url":"https://api.github.com/users/jasnell/orgs","repos_url":"https://api.github.com/users/jasnell/repos","events_url":"https://api.github.com/users/jasnell/events{/privacy}","received_events_url":"https://api.github.com/users/jasnell/received_events","type":"User","site_admin":false},"body":"##### Checklist\r\n\r\n- [x] documentation is changed or added\r\n- [x] the commit message follows commit guidelines\r\n\r\n##### Affected core subsystem(s)\r\n\r\ndoc (stream)\r\n\r\n##### Description of change\r\n\r\nGeneral improvements to stream.md. This one is significantly larger and will need a more detailed review.\r\n\r\n@nodejs/documentation @nodejs/streams \r\n","created_at":"2016-05-24T05:32:11Z","updated_at":"2016-05-24T16:00:45Z","closed_at":null,"merged_at":null,"merge_commit_sha":"65eaf964db6554f7e26da4badf5620ab8264ced6","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/nodejs/node/pulls/6947/commits","review_comments_url":"https://api.github.com/repos/nodejs/node/pulls/6947/comments","review_comment_url":"https://api.github.com/repos/nodejs/node/pulls/comments{/number}","comments_url":"https://api.github.com/repos/nodejs/node/issues/6947/comments","statuses_url":"https://api.github.com/repos/nodejs/node/statuses/e6907a1a8c3d328e6630d4641110dff03af83bee","head":{"label":"jasnell:doc-stream-copy","ref":"doc-stream-copy","sha":"e6907a1a8c3d328e6630d4641110dff03af83bee","user":{"login":"jasnell","id":439929,"avatar_url":"https://avatars.githubusercontent.com/u/439929?v=3","gravatar_id":"","url":"https://api.github.com/users/jasnell","html_url":"https://github.com/jasnell","followers_url":"https://api.github.com/users/jasnell/followers","following_url":"https://api.github.com/users/jasnell/following{/other_user}","gists_url":"https://api.github.com/users/jasnell/gists{/gist_id}","starred_url":"https://api.github.com/users/jasnell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasnell/subscriptions","organizations_url":"https://api.github.com/users/jasnell/orgs","repos_url":"https://api.github.com/users/jasnell/repos","events_url":"https://api.github.com/users/jasnell/events{/privacy}","received_events_url":"https://api.github.com/users/jasnell/received_events","type":"User","site_admin":false},"repo":{"id":37868459,"name":"node","full_name":"jasnell/node","owner":{"login":"jasnell","id":439929,"avatar_url":"https://avatars.githubusercontent.com/u/439929?v=3","gravatar_id":"","url":"https://api.github.com/users/jasnell","html_url":"https://github.com/jasnell","followers_url":"https://api.github.com/users/jasnell/followers","following_url":"https://api.github.com/users/jasnell/following{/other_user}","gists_url":"https://api.github.com/users/jasnell/gists{/gist_id}","starred_url":"https://api.github.com/users/jasnell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasnell/subscriptions","organizations_url":"https://api.github.com/users/jasnell/orgs","repos_url":"https://api.github.com/users/jasnell/repos","events_url":"https://api.github.com/users/jasnell/events{/privacy}","received_events_url":"https://api.github.com/users/jasnell/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jasnell/node","description":"Future Node.js releases will be based on io.js","fork":true,"url":"https://api.github.com/repos/jasnell/node","forks_url":"https://api.github.com/repos/jasnell/node/forks","keys_url":"https://api.github.com/repos/jasnell/node/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jasnell/node/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jasnell/node/teams","hooks_url":"https://api.github.com/repos/jasnell/node/hooks","issue_events_url":"https://api.github.com/repos/jasnell/node/issues/events{/number}","events_url":"https://api.github.com/repos/jasnell/node/events","assignees_url":"https://api.github.com/repos/jasnell/node/assignees{/user}","branches_url":"https://api.github.com/repos/jasnell/node/branches{/branch}","tags_url":"https://api.github.com/repos/jasnell/node/tags","blobs_url":"https://api.github.com/repos/jasnell/node/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jasnell/node/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jasnell/node/git/refs{/sha}","trees_url":"https://api.github.com/repos/jasnell/node/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jasnell/node/statuses/{sha}","languages_url":"https://api.github.com/repos/jasnell/node/languages","stargazers_url":"https://api.github.com/repos/jasnell/node/stargazers","contributors_url":"https://api.github.com/repos/jasnell/node/contributors","subscribers_url":"https://api.github.com/repos/jasnell/node/subscribers","subscription_url":"https://api.github.com/repos/jasnell/node/subscription","commits_url":"https://api.github.com/repos/jasnell/node/commits{/sha}","git_commits_url":"https://api.github.com/repos/jasnell/node/git/commits{/sha}","comments_url":"https://api.github.com/repos/jasnell/node/comments{/number}","issue_comment_url":"https://api.github.com/repos/jasnell/node/issues/comments{/number}","contents_url":"https://api.github.com/repos/jasnell/node/contents/{+path}","compare_url":"https://api.github.com/repos/jasnell/node/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jasnell/node/merges","archive_url":"https://api.github.com/repos/jasnell/node/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jasnell/node/downloads","issues_url":"https://api.github.com/repos/jasnell/node/issues{/number}","pulls_url":"https://api.github.com/repos/jasnell/node/pulls{/number}","milestones_url":"https://api.github.com/repos/jasnell/node/milestones{/number}","notifications_url":"https://api.github.com/repos/jasnell/node/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jasnell/node/labels{/name}","releases_url":"https://api.github.com/repos/jasnell/node/releases{/id}","deployments_url":"https://api.github.com/repos/jasnell/node/deployments","created_at":"2015-06-22T17:01:18Z","updated_at":"2016-01-11T18:47:43Z","pushed_at":"2016-05-24T15:19:18Z","git_url":"git://github.com/jasnell/node.git","ssh_url":"git@github.com:jasnell/node.git","clone_url":"https://github.com/jasnell/node.git","svn_url":"https://github.com/jasnell/node","homepage":"https://iojs.org","size":207334,"stargazers_count":0,"watchers_count":0,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":1,"forks":3,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"nodejs:master","ref":"master","sha":"20501275d376f1f3e950c2131dfad71c931f79e7","user":{"login":"nodejs","id":9950313,"avatar_url":"https://avatars.githubusercontent.com/u/9950313?v=3","gravatar_id":"","url":"https://api.github.com/users/nodejs","html_url":"https://github.com/nodejs","followers_url":"https://api.github.com/users/nodejs/followers","following_url":"https://api.github.com/users/nodejs/following{/other_user}","gists_url":"https://api.github.com/users/nodejs/gists{/gist_id}","starred_url":"https://api.github.com/users/nodejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodejs/subscriptions","organizations_url":"https://api.github.com/users/nodejs/orgs","repos_url":"https://api.github.com/users/nodejs/repos","events_url":"https://api.github.com/users/nodejs/events{/privacy}","received_events_url":"https://api.github.com/users/nodejs/received_events","type":"Organization","site_admin":false},"repo":{"id":27193779,"name":"node","full_name":"nodejs/node","owner":{"login":"nodejs","id":9950313,"avatar_url":"https://avatars.githubusercontent.com/u/9950313?v=3","gravatar_id":"","url":"https://api.github.com/users/nodejs","html_url":"https://github.com/nodejs","followers_url":"https://api.github.com/users/nodejs/followers","following_url":"https://api.github.com/users/nodejs/following{/other_user}","gists_url":"https://api.github.com/users/nodejs/gists{/gist_id}","starred_url":"https://api.github.com/users/nodejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodejs/subscriptions","organizations_url":"https://api.github.com/users/nodejs/orgs","repos_url":"https://api.github.com/users/nodejs/repos","events_url":"https://api.github.com/users/nodejs/events{/privacy}","received_events_url":"https://api.github.com/users/nodejs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/nodejs/node","description":"Node.js JavaScript runtime :sparkles::turtle::rocket::sparkles:","fork":false,"url":"https://api.github.com/repos/nodejs/node","forks_url":"https://api.github.com/repos/nodejs/node/forks","keys_url":"https://api.github.com/repos/nodejs/node/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nodejs/node/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nodejs/node/teams","hooks_url":"https://api.github.com/repos/nodejs/node/hooks","issue_events_url":"https://api.github.com/repos/nodejs/node/issues/events{/number}","events_url":"https://api.github.com/repos/nodejs/node/events","assignees_url":"https://api.github.com/repos/nodejs/node/assignees{/user}","branches_url":"https://api.github.com/repos/nodejs/node/branches{/branch}","tags_url":"https://api.github.com/repos/nodejs/node/tags","blobs_url":"https://api.github.com/repos/nodejs/node/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nodejs/node/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nodejs/node/git/refs{/sha}","trees_url":"https://api.github.com/repos/nodejs/node/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nodejs/node/statuses/{sha}","languages_url":"https://api.github.com/repos/nodejs/node/languages","stargazers_url":"https://api.github.com/repos/nodejs/node/stargazers","contributors_url":"https://api.github.com/repos/nodejs/node/contributors","subscribers_url":"https://api.github.com/repos/nodejs/node/subscribers","subscription_url":"https://api.github.com/repos/nodejs/node/subscription","commits_url":"https://api.github.com/repos/nodejs/node/commits{/sha}","git_commits_url":"https://api.github.com/repos/nodejs/node/git/commits{/sha}","comments_url":"https://api.github.com/repos/nodejs/node/comments{/number}","issue_comment_url":"https://api.github.com/repos/nodejs/node/issues/comments{/number}","contents_url":"https://api.github.com/repos/nodejs/node/contents/{+path}","compare_url":"https://api.github.com/repos/nodejs/node/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nodejs/node/merges","archive_url":"https://api.github.com/repos/nodejs/node/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nodejs/node/downloads","issues_url":"https://api.github.com/repos/nodejs/node/issues{/number}","pulls_url":"https://api.github.com/repos/nodejs/node/pulls{/number}","milestones_url":"https://api.github.com/repos/nodejs/node/milestones{/number}","notifications_url":"https://api.github.com/repos/nodejs/node/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nodejs/node/labels{/name}","releases_url":"https://api.github.com/repos/nodejs/node/releases{/id}","deployments_url":"https://api.github.com/repos/nodejs/node/deployments","created_at":"2014-11-26T19:57:11Z","updated_at":"2016-05-24T15:50:29Z","pushed_at":"2016-05-24T15:33:59Z","git_url":"git://github.com/nodejs/node.git","ssh_url":"git@github.com:nodejs/node.git","clone_url":"https://github.com/nodejs/node.git","svn_url":"https://github.com/nodejs/node","homepage":"https://nodejs.org","size":275785,"stargazers_count":23438,"watchers_count":23438,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3344,"mirror_url":null,"open_issues_count":677,"forks":3344,"open_issues":677,"watchers":23438,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/nodejs/node/pulls/6947"},"html":{"href":"https://github.com/nodejs/node/pull/6947"},"issue":{"href":"https://api.github.com/repos/nodejs/node/issues/6947"},"comments":{"href":"https://api.github.com/repos/nodejs/node/issues/6947/comments"},"review_comments":{"href":"https://api.github.com/repos/nodejs/node/pulls/6947/comments"},"review_comment":{"href":"https://api.github.com/repos/nodejs/node/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/nodejs/node/pulls/6947/commits"},"statuses":{"href":"https://api.github.com/repos/nodejs/node/statuses/e6907a1a8c3d328e6630d4641110dff03af83bee"}}}}
{"actor":{"display_login":"mcollina"}}