{"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/22837571","id":22837571,"diff_hunk":"@@ -447,7 +457,173 @@ counts, arguments to `main`, and so on).\n ## Revising `Reader` and `Writer`\n [Revising `Reader` and `Writer`]: #revising-reader-and-writer\n \n-> To be added in a follow-up PR.\n+The `Reader` and `Writer` traits are the backbone of IO, representing\n+the ability to (respectively) pull bytes from and push bytes to an IO\n+object. The core operations provided by these traits follows a very\n+long tradition for blocking IO, but they are still surprisingly subtle\n+-- and they need to be revised.\n+\n+* **Atomicity and data loss**. As discussed\n+  [above](#atomicity-and-the-reader-writer-traits), the `Reader` and\n+  `Writer` traits currently expose methods that involve multiple\n+  actual reads or writes, and data is lost when an error occurs after\n+  some (but not all) operations have completed.\n+\n+  The proposed strategy for `Reader` operations is to return the\n+  already-read data together with an error. For writers, the main\n+  change is to make `write` only perform a single underlying write\n+  (returning the number of bytes written on success), and provide a\n+  separate `write_all` method.\n+\n+* **Parsing/serialization**. The `Reader` and `Writer` traits\n+  currently provide a large number of default methods for\n+  (de)serialization of various integer types to bytes with a given\n+  endianness. Unfortunately, these operations pose atomicity problems\n+  as well (e.g., a read could fail after reading two of the bytes\n+  needed for a `u32` value).\n+\n+  Rather than complicate the signatures of these methods, the\n+  (de)serialization infrastructure is removed entirely -- in favor of\n+  instead eventually introducing a much richer\n+  parsing/formatting/(de)serialization framework that works seamlessly\n+  with `Reader` and `Writer`.\n+\n+  Such a framework is out of scope for this RFC, but the\n+  endian-sensitive functionality will be provided elsewhere\n+  (likely out of tree).\n+\n+* **The error type**. The traits currently use `IoResult` in their\n+  return types, which ties them to `IoError` in particular. Besides\n+  being an unnecessary restriction, this type prevents `Reader` and\n+  `Writer` (and various adapters built on top of them) from moving to\n+  `libcore` -- `IoError` currently requires the `String` type.\n+\n+  With associated types, there is essentially no downside in making\n+  the error type generic.\n+\n+With those general points out of the way, let's look at the details.\n+\n+### Nonatomic results\n+[Nonatomic results]: #nonatomic-results\n+\n+To clarity dealing with nonatomic operations and improve their\n+ergonomics, we introduce some new types into `std::error`:\n+\n+```rust\n+// The progress so far (T) paired with an err (Err)\n+struct PartialResult<T, Err>(T, Err);\n+\n+// An operation that may fail after having made some progress:\n+// - S is what's produced on complete success,\n+// - T is what's produced if an operation fails part of the way through\n+type NonatomicResult<S, T, Err> = Result<S, PartialResult<T, Err>>;\n+\n+// Ergonomically throw out the partial result\n+impl<T, Err> FromError<PartialResult<T, Err> for Err { ... }\n+```\n+\n+The `NonatomicResult` type (which could use a shorter name)\n+encapsulates the common pattern of operations that may fail after\n+having made some progress. The `PartialResult` type then returns the\n+progress that was made along with the error, but with a `FromError`\n+implementation that makes it trivial to throw out the partial result\n+if desired.\n+\n+### `Reader`\n+[Reader]: #reader\n+\n+The updated `Reader` trait (and its extension) is as follows:\n+\n+```rust\n+trait Reader {\n+    type Err; // new associated error type\n+\n+    // unchanged except for error type\n+    fn read(&mut self, buf: &mut [u8]) -> Result<uint, Err>;\n+\n+    // these all return partial results on error\n+    fn read_to_end(&mut self) -> NonatomicResult<Vec<u8>, Vec<u8>, Err> { ... }\n+    fn read_to_string(&self) -> NonatomicResult<String, Vec<u8>, Err> { ... }\n+    fn read_at_least(&mut self, min: uint,  buf: &mut [u8]) -> NonatomicResult<uint, uint, Err>  { ... }\n+}\n+\n+// extension trait needed for object safety\n+trait ReaderExt: Reader {\n+    fn bytes(&mut self) -> Bytes<Self> { ... }\n+    fn chars<'r>(&'r mut self) -> Chars<'r, Self, Err> { ... }\n+\n+    ... // more to come later in the RFC\n+}\n+impl<R: Reader> ReaderExt for R {}\n+```\n+\n+#### Removed methods\n+\n+The proposed `Reader` trait is much slimmer than today's. The vast\n+majority of removed methods are parsing/deserialization, which were\n+discussed above.\n+\n+The remaining methods (`read_exact`, `push`, `push_at_least`) were\n+removed largely because they are *not memory safe*: they involve\n+extending a vector's capacity, and then *passing in the resulting\n+uninitialized memory* to the `read` method, which is not marked\n+`unsafe`! Thus the current design can lead to undefined behavior in\n+safe code.\n+\n+The solution is to instead extend `Vec<T>` with a useful unsafe method:\n+\n+```rust\n+unsafe fn with_extra(&mut self, n: uint) -> &mut [T];\n+```\n+\n+This method is equivalent to calling `reserve(n)` and then providing a\n+slice to the memory starting just after `len()` entries. Using this\n+method, clients of `Reader` can easily recover the above removed\n+methods, but they are explicitly marking the unsafety of doing so.\n+\n+(Note: `read_to_end` is currently not memory safe for the same reason,\n+but is considered a very important convenience. Thus, we will continue\n+to provide it, but will zero the slice beforehand.)\n+\n+### `Writer`\n+[Writer]: #writer\n+\n+The `Writer` trait is cut down to even smaller size:\n+\n+```rust\n+trait Writer {\n+    type Err;\n+    fn write(&mut self, buf: &[u8]) -> Result<uint, Err>;\n+\n+    fn write_all(&mut self, buf: &[u8]) -> NonatomicResult<(), uint, Err> { ... };\n+    fn write_fmt(&mut self, fmt: &fmt::Arguments) -> Result<(), Err> { ... }\n+    fn flush(&mut self) -> Result<(), Err> { ... }\n+}\n+```\n+\n+The biggest change here is to the semantics of `write`. Instead of\n+repeatedly writing to the underlying IO object until all of `buf` is\n+written, it attempts a *single* write and on success returns the\n+number of bytes written. This follows the long tradition of blocking\n+IO, and is a more fundamental building block than the looping write we\n+currently have.\n+\n+For convenience, `write_all` recovers the behavior of today's `write`,\n+looping until either the entire buffer is written or an error\n+occurs. In the latter case, however, it now also yields the number of\n+bytes that had been written prior to the error.","path":"text/0517-io-os-reform.md","position":186,"original_position":186,"commit_id":"91970395fdd193f1d2383c8a2694263a8b1c7fb2","original_commit_id":"91970395fdd193f1d2383c8a2694263a8b1c7fb2","user":{"login":"mahkoh","id":1882250,"avatar_url":"https://avatars.githubusercontent.com/u/1882250?v=3","gravatar_id":"","url":"https://api.github.com/users/mahkoh","html_url":"https://github.com/mahkoh","followers_url":"https://api.github.com/users/mahkoh/followers","following_url":"https://api.github.com/users/mahkoh/following{/other_user}","gists_url":"https://api.github.com/users/mahkoh/gists{/gist_id}","starred_url":"https://api.github.com/users/mahkoh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mahkoh/subscriptions","organizations_url":"https://api.github.com/users/mahkoh/orgs","repos_url":"https://api.github.com/users/mahkoh/repos","events_url":"https://api.github.com/users/mahkoh/events{/privacy}","received_events_url":"https://api.github.com/users/mahkoh/received_events","type":"User","site_admin":false},"body":"What about signals?","created_at":"2015-01-13T01:22:31Z","updated_at":"2015-01-13T01:22:31Z","html_url":"https://github.com/rust-lang/rfcs/pull/576#discussion_r22837571","pull_request_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/576","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/22837571"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/576#discussion_r22837571"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/576"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/576","id":27239618,"html_url":"https://github.com/rust-lang/rfcs/pull/576","diff_url":"https://github.com/rust-lang/rfcs/pull/576.diff","patch_url":"https://github.com/rust-lang/rfcs/pull/576.patch","issue_url":"https://api.github.com/repos/rust-lang/rfcs/issues/576","number":576,"state":"open","locked":false,"title":"Amend RFC 517: Revisions to reader/writer, core::io and std::io","user":{"login":"aturon","id":709807,"avatar_url":"https://avatars.githubusercontent.com/u/709807?v=3","gravatar_id":"","url":"https://api.github.com/users/aturon","html_url":"https://github.com/aturon","followers_url":"https://api.github.com/users/aturon/followers","following_url":"https://api.github.com/users/aturon/following{/other_user}","gists_url":"https://api.github.com/users/aturon/gists{/gist_id}","starred_url":"https://api.github.com/users/aturon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aturon/subscriptions","organizations_url":"https://api.github.com/users/aturon/orgs","repos_url":"https://api.github.com/users/aturon/repos","events_url":"https://api.github.com/users/aturon/events{/privacy}","received_events_url":"https://api.github.com/users/aturon/received_events","type":"User","site_admin":false},"body":"The [IO reform RFC](https://github.com/rust-lang/rfcs/pull/517) is [being split](https://github.com/rust-lang/rfcs/pull/517#issuecomment-69669731) into several semi-independent pieces, posted as PRs like this one.\r\n\r\nThis RFC amendment adds the sections on `Reader`/`Writer` revisions, as well as `core::io` and `std::io` (which are closely related).\r\n\r\n[Rendered](https://github.com/aturon/rfcs/blob/io-reader-writer/text/0517-io-os-reform.md)","created_at":"2015-01-13T00:41:17Z","updated_at":"2015-01-13T01:22:31Z","closed_at":null,"merged_at":null,"merge_commit_sha":"875ff2b6e423da6166307299f9e4657858ef73ee","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/576/commits","review_comments_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/576/comments","review_comment_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/{number}","comments_url":"https://api.github.com/repos/rust-lang/rfcs/issues/576/comments","statuses_url":"https://api.github.com/repos/rust-lang/rfcs/statuses/91970395fdd193f1d2383c8a2694263a8b1c7fb2","head":{"label":"aturon:io-reader-writer","ref":"io-reader-writer","sha":"91970395fdd193f1d2383c8a2694263a8b1c7fb2","user":{"login":"aturon","id":709807,"avatar_url":"https://avatars.githubusercontent.com/u/709807?v=3","gravatar_id":"","url":"https://api.github.com/users/aturon","html_url":"https://github.com/aturon","followers_url":"https://api.github.com/users/aturon/followers","following_url":"https://api.github.com/users/aturon/following{/other_user}","gists_url":"https://api.github.com/users/aturon/gists{/gist_id}","starred_url":"https://api.github.com/users/aturon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aturon/subscriptions","organizations_url":"https://api.github.com/users/aturon/orgs","repos_url":"https://api.github.com/users/aturon/repos","events_url":"https://api.github.com/users/aturon/events{/privacy}","received_events_url":"https://api.github.com/users/aturon/received_events","type":"User","site_admin":false},"repo":{"id":20423396,"name":"rfcs","full_name":"aturon/rfcs","owner":{"login":"aturon","id":709807,"avatar_url":"https://avatars.githubusercontent.com/u/709807?v=3","gravatar_id":"","url":"https://api.github.com/users/aturon","html_url":"https://github.com/aturon","followers_url":"https://api.github.com/users/aturon/followers","following_url":"https://api.github.com/users/aturon/following{/other_user}","gists_url":"https://api.github.com/users/aturon/gists{/gist_id}","starred_url":"https://api.github.com/users/aturon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aturon/subscriptions","organizations_url":"https://api.github.com/users/aturon/orgs","repos_url":"https://api.github.com/users/aturon/repos","events_url":"https://api.github.com/users/aturon/events{/privacy}","received_events_url":"https://api.github.com/users/aturon/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/aturon/rfcs","description":"RFCs for changes to Rust","fork":true,"url":"https://api.github.com/repos/aturon/rfcs","forks_url":"https://api.github.com/repos/aturon/rfcs/forks","keys_url":"https://api.github.com/repos/aturon/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/aturon/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/aturon/rfcs/teams","hooks_url":"https://api.github.com/repos/aturon/rfcs/hooks","issue_events_url":"https://api.github.com/repos/aturon/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/aturon/rfcs/events","assignees_url":"https://api.github.com/repos/aturon/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/aturon/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/aturon/rfcs/tags","blobs_url":"https://api.github.com/repos/aturon/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/aturon/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/aturon/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/aturon/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/aturon/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/aturon/rfcs/languages","stargazers_url":"https://api.github.com/repos/aturon/rfcs/stargazers","contributors_url":"https://api.github.com/repos/aturon/rfcs/contributors","subscribers_url":"https://api.github.com/repos/aturon/rfcs/subscribers","subscription_url":"https://api.github.com/repos/aturon/rfcs/subscription","commits_url":"https://api.github.com/repos/aturon/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/aturon/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/aturon/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/aturon/rfcs/issues/comments/{number}","contents_url":"https://api.github.com/repos/aturon/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/aturon/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/aturon/rfcs/merges","archive_url":"https://api.github.com/repos/aturon/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/aturon/rfcs/downloads","issues_url":"https://api.github.com/repos/aturon/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/aturon/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/aturon/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/aturon/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/aturon/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/aturon/rfcs/releases{/id}","created_at":"2014-06-02T23:35:56Z","updated_at":"2015-01-11T12:30:51Z","pushed_at":"2015-01-13T00:46:00Z","git_url":"git://github.com/aturon/rfcs.git","ssh_url":"git@github.com:aturon/rfcs.git","clone_url":"https://github.com/aturon/rfcs.git","svn_url":"https://github.com/aturon/rfcs","homepage":"","size":1991,"stargazers_count":3,"watchers_count":3,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":3,"default_branch":"master"}},"base":{"label":"rust-lang:master","ref":"master","sha":"e0999be5aade97bb794d9f886bac31cfcb0f8a8d","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":17527989,"name":"rfcs","full_name":"rust-lang/rfcs","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rust-lang/rfcs","description":"RFCs for changes to Rust","fork":false,"url":"https://api.github.com/repos/rust-lang/rfcs","forks_url":"https://api.github.com/repos/rust-lang/rfcs/forks","keys_url":"https://api.github.com/repos/rust-lang/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/rfcs/teams","hooks_url":"https://api.github.com/repos/rust-lang/rfcs/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/rfcs/events","assignees_url":"https://api.github.com/repos/rust-lang/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/rfcs/tags","blobs_url":"https://api.github.com/repos/rust-lang/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/rfcs/languages","stargazers_url":"https://api.github.com/repos/rust-lang/rfcs/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/rfcs/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/rfcs/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/rfcs/subscription","commits_url":"https://api.github.com/repos/rust-lang/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/rfcs/issues/comments/{number}","contents_url":"https://api.github.com/repos/rust-lang/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/rfcs/merges","archive_url":"https://api.github.com/repos/rust-lang/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/rfcs/downloads","issues_url":"https://api.github.com/repos/rust-lang/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/rfcs/releases{/id}","created_at":"2014-03-07T21:29:00Z","updated_at":"2015-01-12T13:52:23Z","pushed_at":"2015-01-13T00:31:18Z","git_url":"git://github.com/rust-lang/rfcs.git","ssh_url":"git@github.com:rust-lang/rfcs.git","clone_url":"https://github.com/rust-lang/rfcs.git","svn_url":"https://github.com/rust-lang/rfcs","homepage":"","size":6228,"stargazers_count":221,"watchers_count":221,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":140,"mirror_url":null,"open_issues_count":216,"forks":140,"open_issues":216,"watchers":221,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/576"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/576"},"issue":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/576"},"comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/576/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/576/comments"},"review_comment":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/576/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/rfcs/statuses/91970395fdd193f1d2383c8a2694263a8b1c7fb2"}}}}