rust-lang / rust-lang/backtrace-rs
Document Safety on `_unsynchronized` functions
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 628
- Forks
- 291
- PR merge metrics
- No merged PRs in 30d
Description
The documentation on *_unsynchronized functions states that they are unsafe because they are 'unsynchronized'. However, they do not state what kind of synchronization the caller is expected to perform. Looking at the implementations of the safe variants, it seems that they all acquire a global lock. It is not obvious to me why this is necessary. See also #637, which appear to argue that it is not?
If locking is necessary, then I think this locking behavior should be documented on the safe functions, as it is a significant performance pitfall. I get that the main focus of this crate is to help with error diagnostics, where performance is probably not super important. I was planning to use it to implement a sampling profiler for bare-metal environments, and this would be pretty important to know.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the implementations and documentation of the safe and *_unsynchronized functions, then read related issue #637 to understand the synchronization question. Determine what synchronization callers must provide and whether the safe variants acquire a global lock. Done means the relevant function documentation clearly explains the locking or caller requirements and associated performance implications.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100