GitHub PullRequestReviewCommentEvent at 2014-09-11 04:15:21
Repository: rust
Actor: Manishearth
Payload: {"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/rust/pulls/comments/17403532","id":17403532,"diff_hunk":"@@ -0,0 +1,210 @@\n+% The Rust Ownership Guide\n+\n+One of Rust's most important features is its system of ownership. Other\n+important concepts like borrowing and lifetimes follow from the ownership\n+system too. A solid understanding of ownership is what separates an\n+intermediate Rust programmer from a new one.\n+\n+At the same time, ownership is one of the more unique features that Rust has,\n+and so it may seem a bit strange at first. With a little bit of studying, the\n+ownership system will become second nature.\n+\n+# Ownership\n+\n+Virtually all programs make use of some kind of shared resource on your\n+computer. The most common of these is memory. In order to use a particular\n+resource, you are given a reference to that resource. It's through this\n+reference that you are able to utilize the underlying resource. As an example,\n+here is some Rust code which allocates some memory on the heap, and stores\n+an integer there:\n+\n+```{rust}\n+fn main() {\n+    let x = box 5i;\n+}\n+```\n+\n+The `box` keyword allocates memory on the heap, and places a `Box<int>` there.\n+`x` is then used to refer to that heap memory.\n+\n+Each resource can have at most one **owner**. In this case, `x` is the owner of\n+the box. An 'owner' is able to deallocate, de-provision, or otherwise free the\n+particular resource in question. In the given example, since `x` owns the box,\n+when `x` goes out of scope, the Rust compiler sees that the owner is going\n+away, and therefore, frees the heap memory for us. This is the core of Rust's\n+strategy for memory management. Instead of having the programmer manage\n+deallocating resources, or having a garbage collector pick up after a\n+programmer, Rust's compiler is able to analyze the ownership of your resource\n+usage, and free the resource for you.\n+\n+# Borrowing\n+\n+Of course, it would be very limiting to only have a single possible pointer to\n+a resource. If you need additional pointers, Rust offers a second concept:\n+borrowing. Another reference may borrow the contents of a pointer which has\n+ownership. Here's an example:\n+\n+```{rust}\n+fn add_one(i: &int) -> int {\n+    *i + 1\n+}\n+\n+fn main() {\n+    let x = 5;\n+    println!(\"{}\", add_one(&x));\n+}\n+```\n+\n+The `&x` on the seventh line creates a reference to `x`, and the `add_one`\n+function takes a reference to an `int` as a parameter. In this case, the `i`\n+parameter is said to be **borrowing** the value.\n+\n+What's the difference between being an owner and borrowing a reference? A major\n+difference is that when a reference goes out of scope, the resource is _not_\n+deallocated. The owner still exists, of course! If we did a deallocation when a\n+reference went out of scope, the owner would point to something invalid. There\n+are some restrictions placed upon when you may borrow a reference, but we'll\n+discuss those later in this guide.\n+\n+# The borrow checker\n+\n+It's important to understand that ownership and borrowing are both entirely\n+_compile time_ concepts in Rust. That is, the rules involving both are checked\n+entirely at compile time, so you pay no runtime penalty. The part of the\n+compiler that does this is called 'the borrow checker,' and it's a friend and\n+foe to all Rustaceans.\n+\n+Your first interaction with the borrow checker probably resulted from an\n+error message that looks a bit like this:\n+\n+```{rust}\n+error: cannot borrow immutable local variable `x` as mutable\n+     let y = &mut x;\n+                  ^\n+```\n+\n+or maybe\n+\n+```{rust}\n+ 2:19 error: missing lifetime specifier [E0106]\n+ a_string: &str,\n+           ^~~~\n+```\n+\n+or even\n+\n+```{rust}\n+34:29 error: cannot borrow `env` as mutable more than once at a time\n+        let e = &mut env;\n+                     ^~~\n+29:29 note: previous borrow of `env` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `env` until the borrow ends\n+        let e = &mut env;\n+                     ^~~\n+6:6 note: previous borrow ends here\n+\n+}\n+^\n+```\n+\n+They indicate that the compiler believes that you're breaking the rules around\n+who and what can borrow, in what way, and when. But before we get into the\n+details around those rules, these error messages mention the last concept we\n+haven't discussed yet: lifetimes.\n+\n+# Lifetimes\n+\n+A **lifetime** is defined as 'the length of time that a reference exists.' Why\n+do we care about how long our references live?  Let's see some code:\n+\n+```{rust}\n+struct SomeStruct {\n+    a_string: &str,\n+}\n+```\n+\n+If we try to compile this code, we get an error:\n+\n+```{ignore,notrust}\n+2:19 error: missing lifetime specifier [E0106]\n+a_string: &str,\n+          ^~~~\n+```\n+\n+The error here is 'missing lifetime specifier'. Why do we need a specifier?\n+Well, consider this code:\n+\n+```{rust,ignore}\n+struct SomeStruct {\n+    a_string: &str,\n+}\n+\n+fn main() {\n+    let x = box SomeStruct { a_string: \"A string\" };\n+}\n+```\n+\n+Here, `x` is a box with a `SomeStruct` inside. So we have this pointer to the\n+structure itself, but the structure _also_ contains a pointer to a `str`.  We\n+have no guarantee that the reference inside of `a_string` is valid for the\n+entire time that the reference to the `SomeStruct` itself. If it's not, then we\n+could have a valid reference to a `SomeStruct` which contained an invalid\n+reference in its `a_string`. That would lead to problems.\n+\n+We need a way to tell the compiler that we expect `a_string` must be valid\n+as long as a reference to the struct itself is valid. We can do this with an\n+**explicit lifetime annotation**:\n+\n+```{rust}\n+struct SomeStruct<'struct> {\n+    a_string: &'struct str,\n+}\n+\n+fn main() {\n+    let x = box SomeStruct { a_string: \"A string\" };\n+}\n+```\n+\n+This code compiles. We have two additions: a `<'struct>` and a `&'struct`.","path":"src/doc/guide-ownership.md","position":167,"original_position":167,"commit_id":"698ce1efc432d3d40f87f65a465c6241a8633deb","original_commit_id":"698ce1efc432d3d40f87f65a465c6241a8633deb","user":{"login":"Manishearth","id":1617736,"avatar_url":"https://avatars.githubusercontent.com/u/1617736?v=2","gravatar_id":"0a3069491bfded90cdf623341cadc1d1","url":"https://api.github.com/users/Manishearth","html_url":"https://github.com/Manishearth","followers_url":"https://api.github.com/users/Manishearth/followers","following_url":"https://api.github.com/users/Manishearth/following{/other_user}","gists_url":"https://api.github.com/users/Manishearth/gists{/gist_id}","starred_url":"https://api.github.com/users/Manishearth/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Manishearth/subscriptions","organizations_url":"https://api.github.com/users/Manishearth/orgs","repos_url":"https://api.github.com/users/Manishearth/repos","events_url":"https://api.github.com/users/Manishearth/events{/privacy}","received_events_url":"https://api.github.com/users/Manishearth/received_events","type":"User","site_admin":false},"body":"Huh, I thought that was addressed in a seperate comment.","created_at":"2014-09-11T04:15:21Z","updated_at":"2014-09-11T04:15:21Z","html_url":"https://github.com/rust-lang/rust/pull/17138#discussion_r17403532","pull_request_url":"https://api.github.com/repos/rust-lang/rust/pulls/17138","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/comments/17403532"},"html":{"href":"https://github.com/rust-lang/rust/pull/17138#discussion_r17403532"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/17138"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/rust/pulls/17138","id":20993606,"html_url":"https://github.com/rust-lang/rust/pull/17138","diff_url":"https://github.com/rust-lang/rust/pull/17138.diff","patch_url":"https://github.com/rust-lang/rust/pull/17138.patch","issue_url":"https://api.github.com/repos/rust-lang/rust/issues/17138","number":17138,"state":"open","locked":false,"title":"New ownership guide","user":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=2","gravatar_id":"233c279c012ebac792aaa805f966cbc7","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"body":"This is the start of the new \"Ownership\" guide, to replace the lifetimes guide.\r\n\r\nI'm still working on it, but I wanted to share my progress, as this guide is _very_ important, and I'd like as many eyes on it as possible. :smile: ","created_at":"2014-09-10T00:55:05Z","updated_at":"2014-09-11T04:15:21Z","closed_at":null,"merged_at":null,"merge_commit_sha":"192b302f97e6a857e381f71b208a80aabeaf63d7","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/rust/pulls/17138/commits","review_comments_url":"https://api.github.com/repos/rust-lang/rust/pulls/17138/comments","review_comment_url":"https://api.github.com/repos/rust-lang/rust/pulls/comments/{number}","comments_url":"https://api.github.com/repos/rust-lang/rust/issues/17138/comments","statuses_url":"https://api.github.com/repos/rust-lang/rust/statuses/698ce1efc432d3d40f87f65a465c6241a8633deb","head":{"label":"steveklabnik:new_ownership_guide","ref":"new_ownership_guide","sha":"698ce1efc432d3d40f87f65a465c6241a8633deb","user":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=2","gravatar_id":"233c279c012ebac792aaa805f966cbc7","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"repo":{"id":7349289,"name":"rust","full_name":"steveklabnik/rust","owner":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=2","gravatar_id":"233c279c012ebac792aaa805f966cbc7","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/steveklabnik/rust","description":"a safe, concurrent, practical language","fork":true,"url":"https://api.github.com/repos/steveklabnik/rust","forks_url":"https://api.github.com/repos/steveklabnik/rust/forks","keys_url":"https://api.github.com/repos/steveklabnik/rust/keys{/key_id}","collaborators_url":"https://api.github.com/repos/steveklabnik/rust/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/steveklabnik/rust/teams","hooks_url":"https://api.github.com/repos/steveklabnik/rust/hooks","issue_events_url":"https://api.github.com/repos/steveklabnik/rust/issues/events{/number}","events_url":"https://api.github.com/repos/steveklabnik/rust/events","assignees_url":"https://api.github.com/repos/steveklabnik/rust/assignees{/user}","branches_url":"https://api.github.com/repos/steveklabnik/rust/branches{/branch}","tags_url":"https://api.github.com/repos/steveklabnik/rust/tags","blobs_url":"https://api.github.com/repos/steveklabnik/rust/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/steveklabnik/rust/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/steveklabnik/rust/git/refs{/sha}","trees_url":"https://api.github.com/repos/steveklabnik/rust/git/trees{/sha}","statuses_url":"https://api.github.com/repos/steveklabnik/rust/statuses/{sha}","languages_url":"https://api.github.com/repos/steveklabnik/rust/languages","stargazers_url":"https://api.github.com/repos/steveklabnik/rust/stargazers","contributors_url":"https://api.github.com/repos/steveklabnik/rust/contributors","subscribers_url":"https://api.github.com/repos/steveklabnik/rust/subscribers","subscription_url":"https://api.github.com/repos/steveklabnik/rust/subscription","commits_url":"https://api.github.com/repos/steveklabnik/rust/commits{/sha}","git_commits_url":"https://api.github.com/repos/steveklabnik/rust/git/commits{/sha}","comments_url":"https://api.github.com/repos/steveklabnik/rust/comments{/number}","issue_comment_url":"https://api.github.com/repos/steveklabnik/rust/issues/comments/{number}","contents_url":"https://api.github.com/repos/steveklabnik/rust/contents/{+path}","compare_url":"https://api.github.com/repos/steveklabnik/rust/compare/{base}...{head}","merges_url":"https://api.github.com/repos/steveklabnik/rust/merges","archive_url":"https://api.github.com/repos/steveklabnik/rust/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/steveklabnik/rust/downloads","issues_url":"https://api.github.com/repos/steveklabnik/rust/issues{/number}","pulls_url":"https://api.github.com/repos/steveklabnik/rust/pulls{/number}","milestones_url":"https://api.github.com/repos/steveklabnik/rust/milestones{/number}","notifications_url":"https://api.github.com/repos/steveklabnik/rust/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/steveklabnik/rust/labels{/name}","releases_url":"https://api.github.com/repos/steveklabnik/rust/releases{/id}","created_at":"2012-12-28T03:07:04Z","updated_at":"2014-07-30T11:18:32Z","pushed_at":"2014-09-10T22:31:38Z","git_url":"git://github.com/steveklabnik/rust.git","ssh_url":"git@github.com:steveklabnik/rust.git","clone_url":"https://github.com/steveklabnik/rust.git","svn_url":"https://github.com/steveklabnik/rust","homepage":"http://www.rust-lang.org","size":160455,"stargazers_count":2,"watchers_count":2,"language":"Rust","has_issues":false,"has_downloads":true,"has_wiki":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":2,"default_branch":"master"}},"base":{"label":"rust-lang:master","ref":"master","sha":"651106462c357b71a4ca2c02ba2bfedfc38b0035","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=2","gravatar_id":"a4268b59e433144466a0f67cbcfd8cdc","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":724712,"name":"rust","full_name":"rust-lang/rust","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=2","gravatar_id":"a4268b59e433144466a0f67cbcfd8cdc","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/rust","description":"a safe, concurrent, practical language","fork":false,"url":"https://api.github.com/repos/rust-lang/rust","forks_url":"https://api.github.com/repos/rust-lang/rust/forks","keys_url":"https://api.github.com/repos/rust-lang/rust/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/rust/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/rust/teams","hooks_url":"https://api.github.com/repos/rust-lang/rust/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/rust/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/rust/events","assignees_url":"https://api.github.com/repos/rust-lang/rust/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/rust/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/rust/tags","blobs_url":"https://api.github.com/repos/rust-lang/rust/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/rust/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/rust/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/rust/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/rust/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/rust/languages","stargazers_url":"https://api.github.com/repos/rust-lang/rust/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/rust/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/rust/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/rust/subscription","commits_url":"https://api.github.com/repos/rust-lang/rust/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/rust/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/rust/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/rust/issues/comments/{number}","contents_url":"https://api.github.com/repos/rust-lang/rust/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/rust/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/rust/merges","archive_url":"https://api.github.com/repos/rust-lang/rust/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/rust/downloads","issues_url":"https://api.github.com/repos/rust-lang/rust/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/rust/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/rust/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/rust/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/rust/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/rust/releases{/id}","created_at":"2010-06-16T20:39:03Z","updated_at":"2014-09-11T03:05:08Z","pushed_at":"2014-09-11T02:35:40Z","git_url":"git://github.com/rust-lang/rust.git","ssh_url":"git@github.com:rust-lang/rust.git","clone_url":"https://github.com/rust-lang/rust.git","svn_url":"https://github.com/rust-lang/rust","homepage":"http://www.rust-lang.org","size":455572,"stargazers_count":6311,"watchers_count":6311,"language":"Rust","has_issues":true,"has_downloads":true,"has_wiki":true,"forks_count":1256,"mirror_url":null,"open_issues_count":1957,"forks":1256,"open_issues":1957,"watchers":6311,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/17138"},"html":{"href":"https://github.com/rust-lang/rust/pull/17138"},"issue":{"href":"https://api.github.com/repos/rust-lang/rust/issues/17138"},"comments":{"href":"https://api.github.com/repos/rust-lang/rust/issues/17138/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/17138/comments"},"review_comment":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/17138/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/rust/statuses/698ce1efc432d3d40f87f65a465c6241a8633deb"}}}}