rust-lang / rust-lang/rust

Document the runtime environment assumptions of `std`

Open
#133,604 6 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs A-runtime C-tracking-issue T-libs
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

std makes a number of assumptions about the runtime environment that go beyond what is guaranteed by the ABI. They should be documented somewhere. I'm filing this issue to both collect these assumptions and have a discussion about what the best place is to put them.

Assumptions std makes:

  • On pretty much any platform: std is not used when the C platform functions are not available. E.g. using clone on Linux and then calling into std is definitely not sound. (This one is very obvious)
  • std is not called from an asynchronous signal handler or after fork. std makes no attempt at being async-signal-safe (except for panic! after always_abort has been called).
  • On UNIX: threads must not be exited or cancelled (e.g. using pthread_exit or pthread_cancel).
    This is because cancellation does not result in proper unwinding meaning destructors aren't called, but the thread's stack is reused – this is incompatible with pin! and probably a bunch of library code.
  • On UNIX: the stdio file descriptors (STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO) are assumed to be usable as standard input/output/error.
    * On UNIX: sigaltstack is not used by code that does not also install it's own handlers for SIGSEGV and SIGBUS (only applicable when sigaltstack is used in threads not spawned by std).
    std uses TLS variables to store the address of the stack guard page. While TLS accesses are not documented to be async-signal-safe, they mostly are – except for the first access to a variable. std makes sure to always access the relevant variables before setting up a sigaltstack, thereby ensuring that the TLS accesses are safe when the signal handler is successfully called. User code has no access to these variables and therefore cannot initialize them, so it must ensure that std's signal handler is not called when they could be uninitialized.
  • On older macOS systems: the first access to any TLS variable with a destructor is not done from within _tlv_atexit.
    There was a platform bug that resulted in crashes when _tlv_atexit is recursively called. It has since been fixed, but our minimum supported version is not high enough to include the fix.
  • ...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue lists runtime assumptions for std across general platforms, UNIX, and older macOS, but names no target file, test, or entry point. Start by locating where std's platform and runtime assumptions are documented, then compare that coverage with the listed assumptions. Done means the assumptions are collected in an agreed location with their platform scope and safety constraints clear.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, operating-systems
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.