{"action":"created","comment":{"url":"https://api.github.com/repos/dotnet/core-docs/pulls/comments/48878833","id":48878833,"diff_hunk":"@@ -0,0 +1,121 @@\n+# Async In Depth\n+\n+By [Phillip Carter](https://github.com/cartermp)\n+\n+Writing I/O-Bound or CPU-Bound asynchronous code is simple using the `async` and `await` keywords, but what's happening under the covers is fairly complex.  The two key objects involved are `Task` and `Task<T>`.\n+\n+## Task and Task<T>\n+\n+Tasks are constructs used to represent operations running in the background.\n+\n+*   `Task` represents a single operation which does not return a value.\n+*   `Task<T>` represents a single operation which returns a value of type `T`.\n+\n+Tasks are awaitable, meaning that using `await` will allow your application or service to perform useful work while the task is running by yielding control to its caller until the task is done. If you’re using `Task<T>`, the `await` keyword will additionally “unwrap” the value returned when the Task is complete.\n+\n+It’s important to reason about Tasks as abstractions of work happening in the background, and _not_ an abstraction over multithreading. In fact, unless explicitly started on a new thread via `Task.Run`, a Task will start on the current thread and delegate work to the Operating System.\n+\n+## Deeper Dive into Tasks for an I/O-Bound Operation\n+\n+Here’s a 10,000 foot view of what happens with a typical async I/O call:\n+\n+```csharp\n+public async Task<string> GetHtml()\n+{\n+\tvar client = new HttpClient();\n+\t\n+\t// Execution is still synchronous here!\n+\t// The task handle \"getHtmlTask\" represents the active HTTP request.\n+\tvar getHtmlTask = client.GetStringAsync(\"http://www.dotnetfoundation.org\");","path":"docs/async/async-in-depth.md","position":29,"original_position":29,"commit_id":"08a97b80ac13633029d9f37719faf082e5f3f024","original_commit_id":"08a97b80ac13633029d9f37719faf082e5f3f024","user":{"login":"cartermp","id":6309070,"avatar_url":"https://avatars.githubusercontent.com/u/6309070?v=3","gravatar_id":"","url":"https://api.github.com/users/cartermp","html_url":"https://github.com/cartermp","followers_url":"https://api.github.com/users/cartermp/followers","following_url":"https://api.github.com/users/cartermp/following{/other_user}","gists_url":"https://api.github.com/users/cartermp/gists{/gist_id}","starred_url":"https://api.github.com/users/cartermp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cartermp/subscriptions","organizations_url":"https://api.github.com/users/cartermp/orgs","repos_url":"https://api.github.com/users/cartermp/repos","events_url":"https://api.github.com/users/cartermp/events{/privacy}","received_events_url":"https://api.github.com/users/cartermp/received_events","type":"User","site_admin":false},"body":"I'm thinking about if that's worth mentioning.  It's generally a bad thing to mix mutability and concurrency because you then cause non-deterministic side effects.  I call that out in the C# tutorial on async already, but it might be worth mentioning that you can technically do that, but you really should have referentially transparent asynchronous calls.","created_at":"2016-01-05T18:38:40Z","updated_at":"2016-01-05T18:38:40Z","html_url":"https://github.com/dotnet/core-docs/pull/199#discussion_r48878833","pull_request_url":"https://api.github.com/repos/dotnet/core-docs/pulls/199","_links":{"self":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/comments/48878833"},"html":{"href":"https://github.com/dotnet/core-docs/pull/199#discussion_r48878833"},"pull_request":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/199"}}},"pull_request":{"url":"https://api.github.com/repos/dotnet/core-docs/pulls/199","id":53077419,"html_url":"https://github.com/dotnet/core-docs/pull/199","diff_url":"https://github.com/dotnet/core-docs/pull/199.diff","patch_url":"https://github.com/dotnet/core-docs/pull/199.patch","issue_url":"https://api.github.com/repos/dotnet/core-docs/issues/199","number":199,"state":"open","locked":false,"title":"Async Refactor","user":{"login":"cartermp","id":6309070,"avatar_url":"https://avatars.githubusercontent.com/u/6309070?v=3","gravatar_id":"","url":"https://api.github.com/users/cartermp","html_url":"https://github.com/cartermp","followers_url":"https://api.github.com/users/cartermp/followers","following_url":"https://api.github.com/users/cartermp/following{/other_user}","gists_url":"https://api.github.com/users/cartermp/gists{/gist_id}","starred_url":"https://api.github.com/users/cartermp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cartermp/subscriptions","organizations_url":"https://api.github.com/users/cartermp/orgs","repos_url":"https://api.github.com/users/cartermp/repos","events_url":"https://api.github.com/users/cartermp/events{/privacy}","received_events_url":"https://api.github.com/users/cartermp/received_events","type":"User","site_admin":false},"body":"This addresses #176 and #69.\r\n\r\nThe previous set of async articles had a focus which no longer works with the current TOC and overall set of principles.  I've augmented the async file under the C# tutorials to now have a focus on how to write async code in C# (both I/O and CPU-bound code).  There are some links to a more in-depth article which contains deeper dives into the `Task` and `Task<T>` types, explains how they're relevant for client/server scenarios, and some more potential deeper information.\r\n\r\nCurrent issues to be addressed:\r\n\r\n* Diagrams for in-depth article\r\n* Write the full buildable samples to be embedded\r\n* Replace existing sample code with embedded samples\r\n\r\n/cc @richlander @BethMassi @blackdwarf @mairaw @stevehoag @matthewreily ","created_at":"2015-12-09T05:10:19Z","updated_at":"2016-01-05T18:38:40Z","closed_at":null,"merged_at":null,"merge_commit_sha":"af4f1b1842b7fc194d810322d6c51c9113fdf4bf","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/dotnet/core-docs/pulls/199/commits","review_comments_url":"https://api.github.com/repos/dotnet/core-docs/pulls/199/comments","review_comment_url":"https://api.github.com/repos/dotnet/core-docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/dotnet/core-docs/issues/199/comments","statuses_url":"https://api.github.com/repos/dotnet/core-docs/statuses/08a97b80ac13633029d9f37719faf082e5f3f024","head":{"label":"cartermp:async-refactor","ref":"async-refactor","sha":"08a97b80ac13633029d9f37719faf082e5f3f024","user":{"login":"cartermp","id":6309070,"avatar_url":"https://avatars.githubusercontent.com/u/6309070?v=3","gravatar_id":"","url":"https://api.github.com/users/cartermp","html_url":"https://github.com/cartermp","followers_url":"https://api.github.com/users/cartermp/followers","following_url":"https://api.github.com/users/cartermp/following{/other_user}","gists_url":"https://api.github.com/users/cartermp/gists{/gist_id}","starred_url":"https://api.github.com/users/cartermp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cartermp/subscriptions","organizations_url":"https://api.github.com/users/cartermp/orgs","repos_url":"https://api.github.com/users/cartermp/repos","events_url":"https://api.github.com/users/cartermp/events{/privacy}","received_events_url":"https://api.github.com/users/cartermp/received_events","type":"User","site_admin":false},"repo":{"id":44759105,"name":"core-docs","full_name":"cartermp/core-docs","owner":{"login":"cartermp","id":6309070,"avatar_url":"https://avatars.githubusercontent.com/u/6309070?v=3","gravatar_id":"","url":"https://api.github.com/users/cartermp","html_url":"https://github.com/cartermp","followers_url":"https://api.github.com/users/cartermp/followers","following_url":"https://api.github.com/users/cartermp/following{/other_user}","gists_url":"https://api.github.com/users/cartermp/gists{/gist_id}","starred_url":"https://api.github.com/users/cartermp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cartermp/subscriptions","organizations_url":"https://api.github.com/users/cartermp/orgs","repos_url":"https://api.github.com/users/cartermp/repos","events_url":"https://api.github.com/users/cartermp/events{/privacy}","received_events_url":"https://api.github.com/users/cartermp/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/cartermp/core-docs","description":".NET Core documentation (work in progress).","fork":true,"url":"https://api.github.com/repos/cartermp/core-docs","forks_url":"https://api.github.com/repos/cartermp/core-docs/forks","keys_url":"https://api.github.com/repos/cartermp/core-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cartermp/core-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cartermp/core-docs/teams","hooks_url":"https://api.github.com/repos/cartermp/core-docs/hooks","issue_events_url":"https://api.github.com/repos/cartermp/core-docs/issues/events{/number}","events_url":"https://api.github.com/repos/cartermp/core-docs/events","assignees_url":"https://api.github.com/repos/cartermp/core-docs/assignees{/user}","branches_url":"https://api.github.com/repos/cartermp/core-docs/branches{/branch}","tags_url":"https://api.github.com/repos/cartermp/core-docs/tags","blobs_url":"https://api.github.com/repos/cartermp/core-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cartermp/core-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cartermp/core-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/cartermp/core-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cartermp/core-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/cartermp/core-docs/languages","stargazers_url":"https://api.github.com/repos/cartermp/core-docs/stargazers","contributors_url":"https://api.github.com/repos/cartermp/core-docs/contributors","subscribers_url":"https://api.github.com/repos/cartermp/core-docs/subscribers","subscription_url":"https://api.github.com/repos/cartermp/core-docs/subscription","commits_url":"https://api.github.com/repos/cartermp/core-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/cartermp/core-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/cartermp/core-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/cartermp/core-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/cartermp/core-docs/contents/{+path}","compare_url":"https://api.github.com/repos/cartermp/core-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cartermp/core-docs/merges","archive_url":"https://api.github.com/repos/cartermp/core-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cartermp/core-docs/downloads","issues_url":"https://api.github.com/repos/cartermp/core-docs/issues{/number}","pulls_url":"https://api.github.com/repos/cartermp/core-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/cartermp/core-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/cartermp/core-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cartermp/core-docs/labels{/name}","releases_url":"https://api.github.com/repos/cartermp/core-docs/releases{/id}","created_at":"2015-10-22T16:41:05Z","updated_at":"2015-11-19T00:02:52Z","pushed_at":"2015-12-23T18:56:50Z","git_url":"git://github.com/cartermp/core-docs.git","ssh_url":"git@github.com:cartermp/core-docs.git","clone_url":"https://github.com/cartermp/core-docs.git","svn_url":"https://github.com/cartermp/core-docs","homepage":"http://dotnet.readthedocs.org","size":10077,"stargazers_count":0,"watchers_count":0,"language":"CSS","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":0,"default_branch":"master"}},"base":{"label":"dotnet:master","ref":"master","sha":"fa17c0b40786561ce6df68ecc4a26b36bb61aa8d","user":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"repo":{"id":35890081,"name":"core-docs","full_name":"dotnet/core-docs","owner":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/dotnet/core-docs","description":".NET Core documentation (work in progress).","fork":false,"url":"https://api.github.com/repos/dotnet/core-docs","forks_url":"https://api.github.com/repos/dotnet/core-docs/forks","keys_url":"https://api.github.com/repos/dotnet/core-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/dotnet/core-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/dotnet/core-docs/teams","hooks_url":"https://api.github.com/repos/dotnet/core-docs/hooks","issue_events_url":"https://api.github.com/repos/dotnet/core-docs/issues/events{/number}","events_url":"https://api.github.com/repos/dotnet/core-docs/events","assignees_url":"https://api.github.com/repos/dotnet/core-docs/assignees{/user}","branches_url":"https://api.github.com/repos/dotnet/core-docs/branches{/branch}","tags_url":"https://api.github.com/repos/dotnet/core-docs/tags","blobs_url":"https://api.github.com/repos/dotnet/core-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/dotnet/core-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/dotnet/core-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/dotnet/core-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/dotnet/core-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/dotnet/core-docs/languages","stargazers_url":"https://api.github.com/repos/dotnet/core-docs/stargazers","contributors_url":"https://api.github.com/repos/dotnet/core-docs/contributors","subscribers_url":"https://api.github.com/repos/dotnet/core-docs/subscribers","subscription_url":"https://api.github.com/repos/dotnet/core-docs/subscription","commits_url":"https://api.github.com/repos/dotnet/core-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/dotnet/core-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/dotnet/core-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/dotnet/core-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/dotnet/core-docs/contents/{+path}","compare_url":"https://api.github.com/repos/dotnet/core-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/dotnet/core-docs/merges","archive_url":"https://api.github.com/repos/dotnet/core-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/dotnet/core-docs/downloads","issues_url":"https://api.github.com/repos/dotnet/core-docs/issues{/number}","pulls_url":"https://api.github.com/repos/dotnet/core-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/dotnet/core-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/dotnet/core-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/dotnet/core-docs/labels{/name}","releases_url":"https://api.github.com/repos/dotnet/core-docs/releases{/id}","created_at":"2015-05-19T15:13:32Z","updated_at":"2015-12-30T02:29:57Z","pushed_at":"2016-01-05T00:23:52Z","git_url":"git://github.com/dotnet/core-docs.git","ssh_url":"git@github.com:dotnet/core-docs.git","clone_url":"https://github.com/dotnet/core-docs.git","svn_url":"https://github.com/dotnet/core-docs","homepage":"http://dotnet.github.io/docs/index.html","size":10150,"stargazers_count":39,"watchers_count":39,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":47,"mirror_url":null,"open_issues_count":54,"forks":47,"open_issues":54,"watchers":39,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/199"},"html":{"href":"https://github.com/dotnet/core-docs/pull/199"},"issue":{"href":"https://api.github.com/repos/dotnet/core-docs/issues/199"},"comments":{"href":"https://api.github.com/repos/dotnet/core-docs/issues/199/comments"},"review_comments":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/199/comments"},"review_comment":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/199/commits"},"statuses":{"href":"https://api.github.com/repos/dotnet/core-docs/statuses/08a97b80ac13633029d9f37719faf082e5f3f024"}}}}