{"action":"created","comment":{"url":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments/69651231","id":69651231,"diff_hunk":"@@ -0,0 +1,178 @@\n+:title: Users Guide: **forall** loops\n+\n+**forall**-loops: data-parallel loops\n+=====================================\n+\n+The **forall-loop** is Chapel's central concept for expressing data\n+parallelism.  Forall-loops are similar to :ref:`coforall-loops\n+<ug-coforall>` in that they both are parallel variants of Chapel's\n+:ref:`for-loop <ug-forloops>`.  However, where a coforall-loop creates\n+a concurrent task per iteration and a for-loop is executed serially by\n+a single task, a forall-loop may use an arbitrary number of tasks to\n+execute the loop.  As a result, it may execute serially using a single\n+task, or it can use any number of tasks up to the number of iterations\n+(or even beyond, though this is unusual).\n+\n+More specifically, the actual number of tasks used to execute a\n+forall-loop is determined by the its iterand expressions.  The\n+iterands invoke *parallel iterators*, either directly or via\n+expressions that support default parallel iterator methods like\n+ranges, domains, and arrays.  These iterators often select the number\n+of tasks to use based on dynamic information such as the size of the\n+loop and/or the number of available processors.  In addition to\n+specifying the degree of concurrency to use, parallel iterators also\n+determine where their tasks run and how the loop's iterations will be\n+divided between them.  These choices are referred to as the\n+*scheduling policy* for the loop.\n+\n+In practice, the default parallel iterators for many expressions\n+create a number of tasks proportional to the amount of system\n+parallelism that they are targeting.  For example, by default, a local\n+forall loop will typically create a number of tasks equal to the\n+number of available processor cores on its compute node.\n+\n+Like coforall-loops, the original task will not proceed beyond the\n+loop until all tasks used to implement the loop have completed.\n+\n+As a simple motivating example, consider the following serial loop\n+that increments each element in a million-element array *A*:\n+\n+.. literalinclude:: examples/users-guide/datapar/forall.chpl\n+  :caption:\n+  :language: chapel\n+  :lines: 6-7,11-12\n+\n+Since the array is large and the loop's iterations are independent of\n+one other, it should be advantageous to accelerate this computation by\n+executing it in parallel.  A coforall-loop could be used to express\n+the parallelism:\n+\n+.. literalinclude:: examples/users-guide/datapar/forall.chpl\n+  :language: chapel\n+  :lines: 16-17\n+\n+However, a coforall-loop would likely be overkill for this scenario\n+since it would create one million tasks, each of which is simply\n+responsible for incrementing a single element.  For most hardware\n+platforms, this would generate more concurrency than the system could\n+run in parallel while also creating very fine-grain tasks for which\n+the cost of creating, scheduling, and destroying them would likely\n+cost far more than the loop body itself.  Better would be to create a\n+smaller number of tasks, each of which owns a number of loop\n+iterations, as a means of amortizing the task creation overheads while\n+avoiding flooding the target system with more concurrency than it can\n+make use of.\n+\n+This is precisely what forall-loops are for.  While they also result\n+in parallel execution, they typically use a number of tasks that is\n+appropriate for the system, dividing the loop's iterations between\n+them.  Thus, we could write this parallel loop as:\n+\n+.. literalinclude:: examples/users-guide/datapar/forall.chpl\n+  :language: chapel\n+  :lines: 21-22\n+   \n+\n+In slightly more detail, the number of tasks used to implement a\n+forall-loop is determined by its iterand expression(s), in this case,\n+the array *A*.  As declared here, *A* uses a default implementation\n+(\"**domain map**\") which causes it to be allocated locally to the\n+compute node on which the active task is running.  The default\n+parallel itrator for *A* creates a number of tasks equal to the number\n+of available processor cores and divides the iterations evenly between\n+them.  For example, if this program were running on a quad-core\n+processor, *A*'s parallel iterator would create four tasks and assign\n+each of them 250,000 (a quarter) of the array elements / loop\n+iterations.  Note that these policy choices are simply defaults and\n+can be overridden by the programmer using various mechanisms to be\n+covered in subsequent sections.\n+\n+\n+Characteristics of Forall-loop Iterations\n+-----------------------------------------\n+\n+Because the number of tasks used to execute a forall-loop is not\n+well-defined by Chapel, such loops must be *serializable*.  This means\n+that the loop's iterations must be written such that they can legally\n+be executed by a single task.  At the same time, since the loop's\n+iterations are likely to execute in parallel, there should be no\n+sensitivity to the order in which they will execute --- in practice,","path":"doc/sphinx/source/users-guide/datapar/forall.rst","position":99,"original_position":99,"commit_id":"7f8e345a5bc845c5332321237c23b1878d18b649","original_commit_id":"7f8e345a5bc845c5332321237c23b1878d18b649","user":{"login":"psahabu","id":1878289,"avatar_url":"https://avatars.githubusercontent.com/u/1878289?v=3","gravatar_id":"","url":"https://api.github.com/users/psahabu","html_url":"https://github.com/psahabu","followers_url":"https://api.github.com/users/psahabu/followers","following_url":"https://api.github.com/users/psahabu/following{/other_user}","gists_url":"https://api.github.com/users/psahabu/gists{/gist_id}","starred_url":"https://api.github.com/users/psahabu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/psahabu/subscriptions","organizations_url":"https://api.github.com/users/psahabu/orgs","repos_url":"https://api.github.com/users/psahabu/repos","events_url":"https://api.github.com/users/psahabu/events{/privacy}","received_events_url":"https://api.github.com/users/psahabu/received_events","type":"User","site_admin":false},"body":"Probably should replace the --- with the long dash.","created_at":"2016-07-05T22:47:26Z","updated_at":"2016-07-05T22:47:26Z","html_url":"https://github.com/chapel-lang/chapel/pull/4121#discussion_r69651231","pull_request_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121","_links":{"self":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments/69651231"},"html":{"href":"https://github.com/chapel-lang/chapel/pull/4121#discussion_r69651231"},"pull_request":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121"}}},"pull_request":{"url":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121","id":76056182,"html_url":"https://github.com/chapel-lang/chapel/pull/4121","diff_url":"https://github.com/chapel-lang/chapel/pull/4121.diff","patch_url":"https://github.com/chapel-lang/chapel/pull/4121.patch","issue_url":"https://api.github.com/repos/chapel-lang/chapel/issues/4121","number":4121,"state":"open","locked":false,"title":"Draft of users guide forall loops section","user":{"login":"bradcray","id":7536222,"avatar_url":"https://avatars.githubusercontent.com/u/7536222?v=3","gravatar_id":"","url":"https://api.github.com/users/bradcray","html_url":"https://github.com/bradcray","followers_url":"https://api.github.com/users/bradcray/followers","following_url":"https://api.github.com/users/bradcray/following{/other_user}","gists_url":"https://api.github.com/users/bradcray/gists{/gist_id}","starred_url":"https://api.github.com/users/bradcray/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bradcray/subscriptions","organizations_url":"https://api.github.com/users/bradcray/orgs","repos_url":"https://api.github.com/users/bradcray/repos","events_url":"https://api.github.com/users/bradcray/events{/privacy}","received_events_url":"https://api.github.com/users/bradcray/received_events","type":"User","site_admin":false},"body":"This is a first draft of a users guide section on forall loops and a supporting test.\r\n","created_at":"2016-07-02T04:57:19Z","updated_at":"2016-07-05T22:47:26Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1e01010e42551409dc5042c836919d78a745e2be","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121/commits","review_comments_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121/comments","review_comment_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments{/number}","comments_url":"https://api.github.com/repos/chapel-lang/chapel/issues/4121/comments","statuses_url":"https://api.github.com/repos/chapel-lang/chapel/statuses/7f8e345a5bc845c5332321237c23b1878d18b649","head":{"label":"bradcray:users-guide-forall","ref":"users-guide-forall","sha":"7f8e345a5bc845c5332321237c23b1878d18b649","user":{"login":"bradcray","id":7536222,"avatar_url":"https://avatars.githubusercontent.com/u/7536222?v=3","gravatar_id":"","url":"https://api.github.com/users/bradcray","html_url":"https://github.com/bradcray","followers_url":"https://api.github.com/users/bradcray/followers","following_url":"https://api.github.com/users/bradcray/following{/other_user}","gists_url":"https://api.github.com/users/bradcray/gists{/gist_id}","starred_url":"https://api.github.com/users/bradcray/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bradcray/subscriptions","organizations_url":"https://api.github.com/users/bradcray/orgs","repos_url":"https://api.github.com/users/bradcray/repos","events_url":"https://api.github.com/users/bradcray/events{/privacy}","received_events_url":"https://api.github.com/users/bradcray/received_events","type":"User","site_admin":false},"repo":{"id":21837395,"name":"chapel","full_name":"bradcray/chapel","owner":{"login":"bradcray","id":7536222,"avatar_url":"https://avatars.githubusercontent.com/u/7536222?v=3","gravatar_id":"","url":"https://api.github.com/users/bradcray","html_url":"https://github.com/bradcray","followers_url":"https://api.github.com/users/bradcray/followers","following_url":"https://api.github.com/users/bradcray/following{/other_user}","gists_url":"https://api.github.com/users/bradcray/gists{/gist_id}","starred_url":"https://api.github.com/users/bradcray/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bradcray/subscriptions","organizations_url":"https://api.github.com/users/bradcray/orgs","repos_url":"https://api.github.com/users/bradcray/repos","events_url":"https://api.github.com/users/bradcray/events{/privacy}","received_events_url":"https://api.github.com/users/bradcray/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/bradcray/chapel","description":"a Productive Parallel Programming Language","fork":true,"url":"https://api.github.com/repos/bradcray/chapel","forks_url":"https://api.github.com/repos/bradcray/chapel/forks","keys_url":"https://api.github.com/repos/bradcray/chapel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/bradcray/chapel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/bradcray/chapel/teams","hooks_url":"https://api.github.com/repos/bradcray/chapel/hooks","issue_events_url":"https://api.github.com/repos/bradcray/chapel/issues/events{/number}","events_url":"https://api.github.com/repos/bradcray/chapel/events","assignees_url":"https://api.github.com/repos/bradcray/chapel/assignees{/user}","branches_url":"https://api.github.com/repos/bradcray/chapel/branches{/branch}","tags_url":"https://api.github.com/repos/bradcray/chapel/tags","blobs_url":"https://api.github.com/repos/bradcray/chapel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/bradcray/chapel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/bradcray/chapel/git/refs{/sha}","trees_url":"https://api.github.com/repos/bradcray/chapel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/bradcray/chapel/statuses/{sha}","languages_url":"https://api.github.com/repos/bradcray/chapel/languages","stargazers_url":"https://api.github.com/repos/bradcray/chapel/stargazers","contributors_url":"https://api.github.com/repos/bradcray/chapel/contributors","subscribers_url":"https://api.github.com/repos/bradcray/chapel/subscribers","subscription_url":"https://api.github.com/repos/bradcray/chapel/subscription","commits_url":"https://api.github.com/repos/bradcray/chapel/commits{/sha}","git_commits_url":"https://api.github.com/repos/bradcray/chapel/git/commits{/sha}","comments_url":"https://api.github.com/repos/bradcray/chapel/comments{/number}","issue_comment_url":"https://api.github.com/repos/bradcray/chapel/issues/comments{/number}","contents_url":"https://api.github.com/repos/bradcray/chapel/contents/{+path}","compare_url":"https://api.github.com/repos/bradcray/chapel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/bradcray/chapel/merges","archive_url":"https://api.github.com/repos/bradcray/chapel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/bradcray/chapel/downloads","issues_url":"https://api.github.com/repos/bradcray/chapel/issues{/number}","pulls_url":"https://api.github.com/repos/bradcray/chapel/pulls{/number}","milestones_url":"https://api.github.com/repos/bradcray/chapel/milestones{/number}","notifications_url":"https://api.github.com/repos/bradcray/chapel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/bradcray/chapel/labels{/name}","releases_url":"https://api.github.com/repos/bradcray/chapel/releases{/id}","deployments_url":"https://api.github.com/repos/bradcray/chapel/deployments","created_at":"2014-07-14T22:08:29Z","updated_at":"2016-01-30T16:15:15Z","pushed_at":"2016-07-02T05:25:38Z","git_url":"git://github.com/bradcray/chapel.git","ssh_url":"git@github.com:bradcray/chapel.git","clone_url":"https://github.com/bradcray/chapel.git","svn_url":"https://github.com/bradcray/chapel","homepage":"http://chapel.cray.com/","size":372371,"stargazers_count":2,"watchers_count":2,"language":"Chapel","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":2,"default_branch":"master"}},"base":{"label":"chapel-lang:master","ref":"master","sha":"b6c2267fc5024c1a84233855eabaf7fb74ccbf7a","user":{"login":"chapel-lang","id":7597261,"avatar_url":"https://avatars.githubusercontent.com/u/7597261?v=3","gravatar_id":"","url":"https://api.github.com/users/chapel-lang","html_url":"https://github.com/chapel-lang","followers_url":"https://api.github.com/users/chapel-lang/followers","following_url":"https://api.github.com/users/chapel-lang/following{/other_user}","gists_url":"https://api.github.com/users/chapel-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/chapel-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chapel-lang/subscriptions","organizations_url":"https://api.github.com/users/chapel-lang/orgs","repos_url":"https://api.github.com/users/chapel-lang/repos","events_url":"https://api.github.com/users/chapel-lang/events{/privacy}","received_events_url":"https://api.github.com/users/chapel-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":21663285,"name":"chapel","full_name":"chapel-lang/chapel","owner":{"login":"chapel-lang","id":7597261,"avatar_url":"https://avatars.githubusercontent.com/u/7597261?v=3","gravatar_id":"","url":"https://api.github.com/users/chapel-lang","html_url":"https://github.com/chapel-lang","followers_url":"https://api.github.com/users/chapel-lang/followers","following_url":"https://api.github.com/users/chapel-lang/following{/other_user}","gists_url":"https://api.github.com/users/chapel-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/chapel-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chapel-lang/subscriptions","organizations_url":"https://api.github.com/users/chapel-lang/orgs","repos_url":"https://api.github.com/users/chapel-lang/repos","events_url":"https://api.github.com/users/chapel-lang/events{/privacy}","received_events_url":"https://api.github.com/users/chapel-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/chapel-lang/chapel","description":"a Productive Parallel Programming Language","fork":false,"url":"https://api.github.com/repos/chapel-lang/chapel","forks_url":"https://api.github.com/repos/chapel-lang/chapel/forks","keys_url":"https://api.github.com/repos/chapel-lang/chapel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/chapel-lang/chapel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/chapel-lang/chapel/teams","hooks_url":"https://api.github.com/repos/chapel-lang/chapel/hooks","issue_events_url":"https://api.github.com/repos/chapel-lang/chapel/issues/events{/number}","events_url":"https://api.github.com/repos/chapel-lang/chapel/events","assignees_url":"https://api.github.com/repos/chapel-lang/chapel/assignees{/user}","branches_url":"https://api.github.com/repos/chapel-lang/chapel/branches{/branch}","tags_url":"https://api.github.com/repos/chapel-lang/chapel/tags","blobs_url":"https://api.github.com/repos/chapel-lang/chapel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/chapel-lang/chapel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/chapel-lang/chapel/git/refs{/sha}","trees_url":"https://api.github.com/repos/chapel-lang/chapel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/chapel-lang/chapel/statuses/{sha}","languages_url":"https://api.github.com/repos/chapel-lang/chapel/languages","stargazers_url":"https://api.github.com/repos/chapel-lang/chapel/stargazers","contributors_url":"https://api.github.com/repos/chapel-lang/chapel/contributors","subscribers_url":"https://api.github.com/repos/chapel-lang/chapel/subscribers","subscription_url":"https://api.github.com/repos/chapel-lang/chapel/subscription","commits_url":"https://api.github.com/repos/chapel-lang/chapel/commits{/sha}","git_commits_url":"https://api.github.com/repos/chapel-lang/chapel/git/commits{/sha}","comments_url":"https://api.github.com/repos/chapel-lang/chapel/comments{/number}","issue_comment_url":"https://api.github.com/repos/chapel-lang/chapel/issues/comments{/number}","contents_url":"https://api.github.com/repos/chapel-lang/chapel/contents/{+path}","compare_url":"https://api.github.com/repos/chapel-lang/chapel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/chapel-lang/chapel/merges","archive_url":"https://api.github.com/repos/chapel-lang/chapel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/chapel-lang/chapel/downloads","issues_url":"https://api.github.com/repos/chapel-lang/chapel/issues{/number}","pulls_url":"https://api.github.com/repos/chapel-lang/chapel/pulls{/number}","milestones_url":"https://api.github.com/repos/chapel-lang/chapel/milestones{/number}","notifications_url":"https://api.github.com/repos/chapel-lang/chapel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/chapel-lang/chapel/labels{/name}","releases_url":"https://api.github.com/repos/chapel-lang/chapel/releases{/id}","deployments_url":"https://api.github.com/repos/chapel-lang/chapel/deployments","created_at":"2014-07-09T18:15:54Z","updated_at":"2016-07-05T04:01:34Z","pushed_at":"2016-07-05T22:06:45Z","git_url":"git://github.com/chapel-lang/chapel.git","ssh_url":"git@github.com:chapel-lang/chapel.git","clone_url":"https://github.com/chapel-lang/chapel.git","svn_url":"https://github.com/chapel-lang/chapel","homepage":"http://chapel.cray.com/","size":476033,"stargazers_count":284,"watchers_count":284,"language":"Chapel","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":104,"mirror_url":null,"open_issues_count":19,"forks":104,"open_issues":19,"watchers":284,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121"},"html":{"href":"https://github.com/chapel-lang/chapel/pull/4121"},"issue":{"href":"https://api.github.com/repos/chapel-lang/chapel/issues/4121"},"comments":{"href":"https://api.github.com/repos/chapel-lang/chapel/issues/4121/comments"},"review_comments":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121/comments"},"review_comment":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/4121/commits"},"statuses":{"href":"https://api.github.com/repos/chapel-lang/chapel/statuses/7f8e345a5bc845c5332321237c23b1878d18b649"}}}}
{"actor":{"display_login":"psahabu"}}