Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: static keyword #1872

Merged
merged 11 commits into from
Feb 1, 2024
Merged

Docs: static keyword #1872

merged 11 commits into from
Feb 1, 2024

Conversation

anshumanmohan
Copy link
Contributor

@anshumanmohan anshumanmohan commented Jan 26, 2024

First steps towards documenting the shiny new static keyword.
Progress so far:

  • Background about static vs dynamic.
  • Intro to Calyx's support for static: components, groups, control.
  • Information about the guarantees given to us by static.
  • Removed the "tricks and tips" section.
  • Examples.

docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
Copy link
Contributor

@sampsyo sampsyo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome; thanks for getting this going! This looks REALLY great!

I have put nothing in there about refinement; it's perhaps "just a cute detail" as far as the user is concerned. Thoughts?

I think it would be great to add something about this someday, but in a separate PR! Namely, a thing that users might want to know is the following paradigm for how they might use static:

  1. Emit fully dynamic code everywhere.
  2. Observe places where performance is suffering because static inference was incomplete.
  3. Sprinkle static qualifiers in there.

The relevant idea offered by refinement is that step 3 is guaranteed not to break the program.

By this logic, I'd say that inference should be presented here, but I'm not sure about compaction. Thoughts?

Yep!! In particular, maybe we can talk about inference/promotion when we add stuff about refinement above. It's good for people to know this pass exists; the details of how it works or how capable it is probably are not worth writing down. Compaction seems like "just an optimization" like any other, i.e., it can be documented like any other optimization pass.

docs/lang/static.md Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
docs/lang/static.md Outdated Show resolved Hide resolved
@anshumanmohan
Copy link
Contributor Author

Thanks Adrian, your suggestions are now in #1885!

@anshumanmohan anshumanmohan marked this pull request as ready for review January 29, 2024 23:19
@anshumanmohan
Copy link
Contributor Author

I have removed the section about guarantees and instead distributed that info where appropriate. This also means that we have one list of the various control operators, where I introduce each, give an example, and explain the associated guarantees. A little better than making a number of corresponding lists.

@rachitnigam
Copy link
Contributor

LGTM! I like the list of control operators. One thing to consider is making them headings so that we can link to them more easily like with dynamic operators (example: invoke). Feel free to change and merge at your discretion modulo @sampsyo comments!

@anshumanmohan
Copy link
Contributor Author

Nice, I made them into headings and also linked back to the dynamic variants in a number of places. Merging for now.

@anshumanmohan anshumanmohan enabled auto-merge (squash) February 1, 2024 21:43
@anshumanmohan anshumanmohan merged commit cc6783e into main Feb 1, 2024
7 checks passed
@anshumanmohan anshumanmohan deleted the piezo-doc branch February 1, 2024 21:55
rachitnigam pushed a commit that referenced this pull request Feb 16, 2024
* Tweaks

* Guarantees

* nix tricks and tips

* Correct syntax

* Title case

* Various comments from Adrian

* Drag guarantees out into their own section

* Push guarantees in throughout

* More headings for better linking
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants