Reducer documentation

[VoxSciurorum]

No description provided.

[netlify]

✅ Deploy Preview for sage-licorice-6da44d ready!

Name	Link
🔨 Latest commit
🔍 Latest deploy log	https://app.netlify.com/sites/sage-licorice-6da44d/deploys/632e061ae811f753cbe4bcc6
😎 Deploy Preview	https://deploy-preview-97--sage-licorice-6da44d.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[neboat]

Some minor comments, to start things off:

• I think it's weird to call std::list<int>::splice an "associative binary operation." That class method takes both a const_iterator and another std::list as its arguments, rather than just another std::list. A list-append or a list-prepend function would be better, but the spec of std::list doesn't include those class methods.
• The 5th paragraph contains an explicit   that should be removed.
• To syntax-highlight the code consistently with the rest of the website, the code blocks should be surrounded by ```cpp and ``` (or by ```c and ```).
• I think this documentation needs more sectioning, including sections that show up in the TOC for the page.
• I'm guessing we will want terms that are defined on this page to use the defn shortcode, but I'm not sure.

[VoxSciurorum]

• The 5th paragraph contains an explicit   that should be removed.
• To syntax-highlight the code consistently with the rest of the website, the code blocks should be surrounded by ```cpp and ``` (or by ```c and ```).

I wrote the documentation in emacs using standard markdown and it was correct as written. Something in the uploading process quoted the &. I will try to edit the file on my branch to fix it.

As for the code blocks, I don't think language tags are part of standard markdown. I will add them if we are only displaying the code on this web page.

[behoppe]

Thanks @VoxSciurorum for documenting our new reducer functionality and tapping some reviewers. To complement this reference perspective, I wonder if we want to develop an OpenCilk tutorial that gets new parallel programmers interested in using reducers. I have collected Cilk Plus material along these lines into #146. It's very much a work in progress, but I'm curious if you agree that a tutorial along those lines would help?

[wsmoses]

``Of the same kind'' is unclear

[neboat]

Added a couple of comments. These comments are minor nits; I think this doc is essentially ready to deploy.

[neboat]

For consistency with the rest of the code examples, I think we want cilk_reducer(I,R) (or something like that) here, rather than just cilk_reducer. That way it's clearer that one always needs to specify the arguments to the cilk_reducer keyword.

[neboat]

Likewise with my previous comment, I think we want cilk_reducer(I,R) here, rather than just a bare cilk_reducer.

[neboat]

Minor nit: I'd prefer that the sentence that starts, A reducer has a type, relates to the previous comment about a reducer being a monoid. Otherwise a reader might be confused about what the comment about a monoid has to do with the rest of the paragraph.

Here's a possible rephrasing:

Formally, a reducer is a mathematical object called a {% defn "monoid" %}, meaning it has the following components:

• a type (e.g., double),
• an identity value (e.g., 0.0), and
• an associative binary operation (e.g., +).

The operation does not need to be commutative...

[neboat]

I'm not sure how everything will look once this page is merged with style fixes in other PRs. But right now I think this line can be removed, since the title "Reducers" already show up elsewhere on the page.

(For clarity, this comment applies specifically to line 6.)

[neboat]

My inclination is to remove the leading indentation on the code within the code block (for this code block and all other code blocks in this document). Right now this indentation appears to add unnecessary whitespace to the code on the deployed page.