{"action":"created","comment":{"url":"https://api.github.com/repos/akka/akka/pulls/comments/28086742","id":28086742,"diff_hunk":"@@ -0,0 +1,134 @@\n+.. _stages-overview:\n+\n+###############################################\n+Overview of built-in stages and their semantics\n+###############################################\n+\n+All stages by default backpressure if the computation they encapsulate is not fast enough to keep up with the rate of\n+incoming elements from the preceding stage. There are differences though how the different stages handle when some of\n+their downstream stages backpressure them. This table provides a summary of all built-in stages and their semantics.\n+\n+All stages stop and propagate the failure downstream as soon as any of their upstreams emit a failure unless supervision\n+is used. This happens to ensure reliable teardown of streams and cleanup when failures happen. Failures are meant to\n+be to model unrecoverable conditions, therefore they are always eagerly propagated.\n+For in-band error handling of normal errors (dropping elements ifa map fails for example) you should use the\n+upervision support, or explicitly wrap your element types in a proper container that can express error or success\n+states (for example `Try` in Scala).\n+\n+Custom components are not covered by this table since their semantics are defined by the user.\n+\n+Simple processing stages\n+^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+These stages are all expressible as a `PushPullStage`. These stages can transform the rate of incoming elements\n+since there are stages that emit multiple elements for a single input (e.g. `mapConcat') or consume\n+multiple elements before emitting one output (e.g. `filter`). However, these rate transformations are data-driven, i.e. it is\n+the incoming elements that define how the rate is affected. This is in contrast with :ref:`detached-stages-overview`\n+which can change their processing behavior depending on being backpressured by downstream or not.\n+\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+Stage                  Emits when                                                                                                                  Backpressures when                                                                                                              Completes when\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+map                    the function mapping the element finishes                                                                                   downstream backpressures                                                                                                        Upstream completes\n+mapConcat              the function mapping the element finishes or there are still available elements from the previously calculated collection   downstream backpressures or there are still available elements from the previously calculated collection                        Upstream completes\n+filter                 the given predicate returns true for the element                                                                            the given predicate returns true for the element and downstream backpressures                                                   Upstream completes\n+collect                the provided partial function is defined for the element                                                                    the partial functin is defined for the element and downstream backpressures                                                     Upstream completes\n+grouped                the specified number of elements has been accumulated or upstream completed                                                 a group has been assembled and downstream backpressures                                                                         Upstream completes\n+scan                   the function scanning the element finishes                                                                                  downstream backpressures                                                                                                        Upstream completes\n+drop                   the specified number of elements has been dropped already                                                                   the specified number of elements has been dropped and downstream backpressures                                                  Upstream completes\n+take                   the specified number of elements to take has not yet been reached                                                           downstream backpressures The specified number of elements has been emitted, or upstream completes                               The defined number of elements has been taken or upstream completes\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+\n+Asynchronous processing stages\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous\n+operation at the same time (usually handling the completion of a Future).\n+\n+**It is currently not possible to build custom asynchronous processing stages**\n+\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+Stage                  Emits when                                                                                                                  Backpressures when                                                                                                              Completes when\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+mapAsync               the Future returned by the provided function finishes for the next element in sequence                                      the distance between the first uncompleted Future and between the last processed Future is larger than the defined parallelism  Upstream completes [1]_\n+mapAsyncUnordered      a Future returned by the provided function finishes for any of the pending Futures                                          downstream backpressures and the number of pending Futures equals to the defined parallelism                                    Upstream completes [1]_\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+\n+Timer driven stages\n+^^^^^^^^^^^^^^^^^^^\n+\n+*TODO*\n+\n+**It is currently not possible to build custom timer driven stages**\n+\n+.. _detached-stages-overview:\n+Backpressure aware stages\n+^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+These stages are all expressible as a `DetachedStage`. These stages are aware of the backpressure provided by their\n+downstreams and able to adapt their behavior to that signal.\n+\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+Stage                  Emits when                                                                                                                  Backpressures when                                                                                                              Completes when\n+=====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================\n+conflate               downstream stops backpressuring and there is a conflated element available                                                  never [2]_                                                                                                                      Upstream completes\n+expand                 downstream stops backpressuring                                                                                             downstream backpressures                                                                                                        Upstream completes\n+buffer (Backpressure)  downstream stops backpressuring and there is a pending element in the buffer                              buffer is full                                                                                                                                    Upstream completes and buffered elements has been drained","path":"akka-docs-dev/rst/stages-overview.rst","position":76,"original_position":76,"commit_id":"173758b9794abe4d93c86045ca44dcbad35121d7","original_commit_id":"173758b9794abe4d93c86045ca44dcbad35121d7","user":{"login":"rkuhn","id":470469,"avatar_url":"https://avatars.githubusercontent.com/u/470469?v=3","gravatar_id":"","url":"https://api.github.com/users/rkuhn","html_url":"https://github.com/rkuhn","followers_url":"https://api.github.com/users/rkuhn/followers","following_url":"https://api.github.com/users/rkuhn/following{/other_user}","gists_url":"https://api.github.com/users/rkuhn/gists{/gist_id}","starred_url":"https://api.github.com/users/rkuhn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rkuhn/subscriptions","organizations_url":"https://api.github.com/users/rkuhn/orgs","repos_url":"https://api.github.com/users/rkuhn/repos","events_url":"https://api.github.com/users/rkuhn/events{/privacy}","received_events_url":"https://api.github.com/users/rkuhn/received_events","type":"User","site_admin":false},"body":"“elements _have_ been drained”","created_at":"2015-04-09T18:06:42Z","updated_at":"2015-04-09T18:06:42Z","html_url":"https://github.com/akka/akka/pull/17164#discussion_r28086742","pull_request_url":"https://api.github.com/repos/akka/akka/pulls/17164","_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/comments/28086742"},"html":{"href":"https://github.com/akka/akka/pull/17164#discussion_r28086742"},"pull_request":{"href":"https://api.github.com/repos/akka/akka/pulls/17164"}}},"pull_request":{"url":"https://api.github.com/repos/akka/akka/pulls/17164","id":32959278,"html_url":"https://github.com/akka/akka/pull/17164","diff_url":"https://github.com/akka/akka/pull/17164.diff","patch_url":"https://github.com/akka/akka/pull/17164.patch","issue_url":"https://api.github.com/repos/akka/akka/issues/17164","number":17164,"state":"open","locked":false,"title":"+doc, str #16716: Table summarizing built-in processing stages","user":{"login":"drewhk","id":932285,"avatar_url":"https://avatars.githubusercontent.com/u/932285?v=3","gravatar_id":"","url":"https://api.github.com/users/drewhk","html_url":"https://github.com/drewhk","followers_url":"https://api.github.com/users/drewhk/followers","following_url":"https://api.github.com/users/drewhk/following{/other_user}","gists_url":"https://api.github.com/users/drewhk/gists{/gist_id}","starred_url":"https://api.github.com/users/drewhk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drewhk/subscriptions","organizations_url":"https://api.github.com/users/drewhk/orgs","repos_url":"https://api.github.com/users/drewhk/repos","events_url":"https://api.github.com/users/drewhk/events{/privacy}","received_events_url":"https://api.github.com/users/drewhk/received_events","type":"User","site_admin":false},"body":"Missing:\r\n\r\n - [ ] Timer driven stages\r\n - [ ] Make scaladocs consistent with table after the table has been reviewed\r\n - [ ] Link from relevant documentation pages\r\n\r\nPlease look through this carefully (I will do the same) since it is easy to make typos and mistakes in such a large table. Sorry for the overly long lines, it is hard to make the table relatively maintainable and at the same time keep reStructuredText happy.","created_at":"2015-04-09T14:14:10Z","updated_at":"2015-04-09T18:06:42Z","closed_at":null,"merged_at":null,"merge_commit_sha":"0f0285748239908c82cee33c7fe6c777053cef20","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/akka/akka/pulls/17164/commits","review_comments_url":"https://api.github.com/repos/akka/akka/pulls/17164/comments","review_comment_url":"https://api.github.com/repos/akka/akka/pulls/comments{/number}","comments_url":"https://api.github.com/repos/akka/akka/issues/17164/comments","statuses_url":"https://api.github.com/repos/akka/akka/statuses/173758b9794abe4d93c86045ca44dcbad35121d7","head":{"label":"drewhk:wip-16716-stage-semantics-documentation-drewhk","ref":"wip-16716-stage-semantics-documentation-drewhk","sha":"173758b9794abe4d93c86045ca44dcbad35121d7","user":{"login":"drewhk","id":932285,"avatar_url":"https://avatars.githubusercontent.com/u/932285?v=3","gravatar_id":"","url":"https://api.github.com/users/drewhk","html_url":"https://github.com/drewhk","followers_url":"https://api.github.com/users/drewhk/followers","following_url":"https://api.github.com/users/drewhk/following{/other_user}","gists_url":"https://api.github.com/users/drewhk/gists{/gist_id}","starred_url":"https://api.github.com/users/drewhk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drewhk/subscriptions","organizations_url":"https://api.github.com/users/drewhk/orgs","repos_url":"https://api.github.com/users/drewhk/repos","events_url":"https://api.github.com/users/drewhk/events{/privacy}","received_events_url":"https://api.github.com/users/drewhk/received_events","type":"User","site_admin":false},"repo":{"id":4322312,"name":"akka","full_name":"drewhk/akka","owner":{"login":"drewhk","id":932285,"avatar_url":"https://avatars.githubusercontent.com/u/932285?v=3","gravatar_id":"","url":"https://api.github.com/users/drewhk","html_url":"https://github.com/drewhk","followers_url":"https://api.github.com/users/drewhk/followers","following_url":"https://api.github.com/users/drewhk/following{/other_user}","gists_url":"https://api.github.com/users/drewhk/gists{/gist_id}","starred_url":"https://api.github.com/users/drewhk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drewhk/subscriptions","organizations_url":"https://api.github.com/users/drewhk/orgs","repos_url":"https://api.github.com/users/drewhk/repos","events_url":"https://api.github.com/users/drewhk/events{/privacy}","received_events_url":"https://api.github.com/users/drewhk/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/drewhk/akka","description":"Akka Project","fork":true,"url":"https://api.github.com/repos/drewhk/akka","forks_url":"https://api.github.com/repos/drewhk/akka/forks","keys_url":"https://api.github.com/repos/drewhk/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/drewhk/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/drewhk/akka/teams","hooks_url":"https://api.github.com/repos/drewhk/akka/hooks","issue_events_url":"https://api.github.com/repos/drewhk/akka/issues/events{/number}","events_url":"https://api.github.com/repos/drewhk/akka/events","assignees_url":"https://api.github.com/repos/drewhk/akka/assignees{/user}","branches_url":"https://api.github.com/repos/drewhk/akka/branches{/branch}","tags_url":"https://api.github.com/repos/drewhk/akka/tags","blobs_url":"https://api.github.com/repos/drewhk/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/drewhk/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/drewhk/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/drewhk/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/drewhk/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/drewhk/akka/languages","stargazers_url":"https://api.github.com/repos/drewhk/akka/stargazers","contributors_url":"https://api.github.com/repos/drewhk/akka/contributors","subscribers_url":"https://api.github.com/repos/drewhk/akka/subscribers","subscription_url":"https://api.github.com/repos/drewhk/akka/subscription","commits_url":"https://api.github.com/repos/drewhk/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/drewhk/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/drewhk/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/drewhk/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/drewhk/akka/contents/{+path}","compare_url":"https://api.github.com/repos/drewhk/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/drewhk/akka/merges","archive_url":"https://api.github.com/repos/drewhk/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/drewhk/akka/downloads","issues_url":"https://api.github.com/repos/drewhk/akka/issues{/number}","pulls_url":"https://api.github.com/repos/drewhk/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/drewhk/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/drewhk/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/drewhk/akka/labels{/name}","releases_url":"https://api.github.com/repos/drewhk/akka/releases{/id}","created_at":"2012-05-14T09:57:34Z","updated_at":"2015-02-17T12:40:08Z","pushed_at":"2015-04-09T14:11:29Z","git_url":"git://github.com/drewhk/akka.git","ssh_url":"git@github.com:drewhk/akka.git","clone_url":"https://github.com/drewhk/akka.git","svn_url":"https://github.com/drewhk/akka","homepage":"http://akka.io","size":160799,"stargazers_count":1,"watchers_count":1,"language":"Scala","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":1,"default_branch":"master"}},"base":{"label":"akka:release-2.3-dev","ref":"release-2.3-dev","sha":"98cad6d547836e231908a909a618031afa5a9757","user":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"repo":{"id":130013,"name":"akka","full_name":"akka/akka","owner":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/akka/akka","description":"Akka Project","fork":false,"url":"https://api.github.com/repos/akka/akka","forks_url":"https://api.github.com/repos/akka/akka/forks","keys_url":"https://api.github.com/repos/akka/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/akka/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/akka/akka/teams","hooks_url":"https://api.github.com/repos/akka/akka/hooks","issue_events_url":"https://api.github.com/repos/akka/akka/issues/events{/number}","events_url":"https://api.github.com/repos/akka/akka/events","assignees_url":"https://api.github.com/repos/akka/akka/assignees{/user}","branches_url":"https://api.github.com/repos/akka/akka/branches{/branch}","tags_url":"https://api.github.com/repos/akka/akka/tags","blobs_url":"https://api.github.com/repos/akka/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/akka/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/akka/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/akka/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/akka/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/akka/akka/languages","stargazers_url":"https://api.github.com/repos/akka/akka/stargazers","contributors_url":"https://api.github.com/repos/akka/akka/contributors","subscribers_url":"https://api.github.com/repos/akka/akka/subscribers","subscription_url":"https://api.github.com/repos/akka/akka/subscription","commits_url":"https://api.github.com/repos/akka/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/akka/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/akka/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/akka/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/akka/akka/contents/{+path}","compare_url":"https://api.github.com/repos/akka/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/akka/akka/merges","archive_url":"https://api.github.com/repos/akka/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/akka/akka/downloads","issues_url":"https://api.github.com/repos/akka/akka/issues{/number}","pulls_url":"https://api.github.com/repos/akka/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/akka/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/akka/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/akka/akka/labels{/name}","releases_url":"https://api.github.com/repos/akka/akka/releases{/id}","created_at":"2009-02-16T12:51:54Z","updated_at":"2015-04-09T15:34:40Z","pushed_at":"2015-04-09T16:13:55Z","git_url":"git://github.com/akka/akka.git","ssh_url":"git@github.com:akka/akka.git","clone_url":"https://github.com/akka/akka.git","svn_url":"https://github.com/akka/akka","homepage":"http://akka.io","size":245397,"stargazers_count":3783,"watchers_count":3783,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1085,"mirror_url":null,"open_issues_count":641,"forks":1085,"open_issues":641,"watchers":3783,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/17164"},"html":{"href":"https://github.com/akka/akka/pull/17164"},"issue":{"href":"https://api.github.com/repos/akka/akka/issues/17164"},"comments":{"href":"https://api.github.com/repos/akka/akka/issues/17164/comments"},"review_comments":{"href":"https://api.github.com/repos/akka/akka/pulls/17164/comments"},"review_comment":{"href":"https://api.github.com/repos/akka/akka/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/akka/akka/pulls/17164/commits"},"statuses":{"href":"https://api.github.com/repos/akka/akka/statuses/173758b9794abe4d93c86045ca44dcbad35121d7"}}}}