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

Remove static/dynamic memories from public docs #9545

Conversation

alexcrichton
Copy link
Member

@alexcrichton alexcrichton commented Nov 2, 2024

This commit removes the terminology of "static" and "dynamic" memories from the public-facing documentation of Wasmtime, notably on the Config structure and its various configuration settings. The goal of this commit is in the same vein as #9543 which is to simplify the memory settings of Wasmtime for users in this case.

This change doesn't actually have any code changes beyond renames (and handling now-deprecated CLI options). The goal of this commit is to basically rewrite how we document the effect of various settings of Wasmtime. Notably:

  • Config::static_memory_maximum_size is now memory_reservation.
  • Config::static_memory_forced is now memory_may_move.
  • Config::dynamic_memory_reserved_for_growth is now memory_reservation_for_growth.

Documentation for all of these options has been rewritten and updated to take into account the removal of "dynamic" and "static" terminology. Additionally more words have been written about the various effects of each setting and how things related to wasm features such as index type sizes and custom page sizes.

The rewritten documentation is intended to basically already match what Wasmtime does today. I believe that all of these settings are useful in one form or another so none have been dropped but the updated documentation is intended to help simplify the mental model for how they're processed internally and how they affect allocations and such.

@alexcrichton alexcrichton requested review from a team as code owners November 2, 2024 20:41
@alexcrichton alexcrichton requested review from fitzgen and removed request for a team November 2, 2024 20:41
@github-actions github-actions bot added fuzzing Issues related to our fuzzing infrastructure wasmtime:api Related to the API of the `wasmtime` crate itself wasmtime:c-api Issues pertaining to the C API. wasmtime:config Issues related to the configuration of Wasmtime labels Nov 2, 2024
Copy link

github-actions bot commented Nov 2, 2024

Subscribe to Label Action

cc @fitzgen

This issue or pull request has been labeled: "fuzzing", "wasmtime:api", "wasmtime:c-api", "wasmtime:config"

Thus the following users have been cc'd because of the following labels:

  • fitzgen: fuzzing

To subscribe or unsubscribe from this label, edit the .github/subscribe-to-label.json configuration file.

Learn more.

Copy link

github-actions bot commented Nov 2, 2024

Label Messager: wasmtime:config

It looks like you are changing Wasmtime's configuration options. Make sure to
complete this check list:

  • If you added a new Config method, you wrote extensive documentation for
    it.

    Our documentation should be of the following form:

    Short, simple summary sentence.
    
    More details. These details can be multiple paragraphs. There should be
    information about not just the method, but its parameters and results as
    well.
    
    Is this method fallible? If so, when can it return an error?
    
    Can this method panic? If so, when does it panic?
    
    # Example
    
    Optional example here.
    
  • If you added a new Config method, or modified an existing one, you
    ensured that this configuration is exercised by the fuzz targets.

    For example, if you expose a new strategy for allocating the next instance
    slot inside the pooling allocator, you should ensure that at least one of our
    fuzz targets exercises that new strategy.

    Often, all that is required of you is to ensure that there is a knob for this
    configuration option in wasmtime_fuzzing::Config (or one
    of its nested structs).

    Rarely, this may require authoring a new fuzz target to specifically test this
    configuration. See our docs on fuzzing for more details.

  • If you are enabling a configuration option by default, make sure that it
    has been fuzzed for at least two weeks before turning it on by default.


To modify this label's message, edit the .github/label-messager/wasmtime-config.md file.

To add new label messages or remove existing label messages, edit the
.github/label-messager.json configuration file.

Learn more.

Copy link
Member

@fitzgen fitzgen left a comment

Choose a reason for hiding this comment

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

Thanks! Some bike shedding inline below, interested in what you think.

This commit removes the terminology of "static" and "dynamic" memories
from the public-facing documentation of Wasmtime, notably on the
`Config` structure and its various configuration settings. The goal of
this commit is in the same vein as bytecodealliance#9543 which is to simplify the memory
settings of Wasmtime for users in this case.

This change doesn't actually have any code changes beyond renames (and
handling now-deprecated CLI options). The goal of this commit is to
basically rewrite how we document the effect of various settings of
Wasmtime. Notably:

* `Config::static_memory_maximum_size` is now `memory_reservation`.
* `Config::static_memory_forced` is now `memory_reservation_is_maximum`.
* `Config::dynamic_memory_reserved_for_growth` is now
  `memory_reservation_for_growth`.

Documentation for all of these options has been rewritten and updated to
take into account the removal of "dynamic" and "static" terminology.
Additionally more words have been written about the various effects of
each setting and how things related to wasm features such as index type
sizes and custom page sizes.

The rewritten documentation is intended to basically already match what
Wasmtime does today. I believe that all of these settings are useful in
one form or another so none have been dropped but the updated
documentation is intended to help simplify the mental model for how
they're processed internally and how they affect allocations and such.
@alexcrichton alexcrichton force-pushed the update-memory-configuration-options branch from 64cfa53 to 6b21001 Compare November 4, 2024 22:46
@alexcrichton alexcrichton requested a review from fitzgen November 4, 2024 23:01
Copy link
Member

@fitzgen fitzgen left a comment

Choose a reason for hiding this comment

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

nitpicks on docs wording below, but lgtm

@alexcrichton alexcrichton added this pull request to the merge queue Nov 5, 2024
Merged via the queue into bytecodealliance:main with commit 7a28a5b Nov 5, 2024
42 checks passed
@alexcrichton alexcrichton deleted the update-memory-configuration-options branch November 5, 2024 01:21
jder added a commit to jder/wasmtime that referenced this pull request Nov 12, 2024
@jder jder mentioned this pull request Nov 12, 2024
github-merge-queue bot pushed a commit that referenced this pull request Nov 12, 2024
github-merge-queue bot pushed a commit to dfinity/ic that referenced this pull request Jan 9, 2025
Wasmtime release notes:
https://github.com/bytecodealliance/wasmtime/releases/tag/v28.0.0

- Changed `LinearMemory` trait API,
[code](bytecodealliance/wasmtime#9577)
- Changed static/dynamic memory config, removed
`static_memory_maximum_size`
[code](bytecodealliance/wasmtime#9545)

---------

Co-authored-by: Andriy Berestovskyy <[email protected]>
Co-authored-by: IDX GitHub Automation <[email protected]>
github-merge-queue bot pushed a commit to dfinity/ic that referenced this pull request Jan 9, 2025
Wasmtime release notes:
https://github.com/bytecodealliance/wasmtime/releases/tag/v28.0.0

- Changed `LinearMemory` trait API,
[code](bytecodealliance/wasmtime#9577)
- Changed static/dynamic memory config, removed
`static_memory_maximum_size`
[code](bytecodealliance/wasmtime#9545)

---------

Co-authored-by: Andriy Berestovskyy <[email protected]>
Co-authored-by: IDX GitHub Automation <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
fuzzing Issues related to our fuzzing infrastructure wasmtime:api Related to the API of the `wasmtime` crate itself wasmtime:c-api Issues pertaining to the C API. wasmtime:config Issues related to the configuration of Wasmtime
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants