Update documentation for Arc::from_raw, Arc::increment_strong_count, and Arc::decrement_strong_count to clarify allocator requirement
### Related Issue:
This update addresses parts of the issue raised in [#134242](https://github.com/rust-lang/rust/issues/134242), where Arc's documentation lacks `Global Allocator` safety descriptions for three APIs. And this was confirmed by ```@workingjubilee``` :
> Wait, nevermind. I apparently forgot the `increment_strong_count` is implicitly A = Global. Ugh. Another reason these things are hard to track, unfortunately.
### PR Description
This PR updates the document for the following APIs:
- `Arc::from_raw`
- `Arc::increment_strong_count`
- `Arc::decrement_strong_count`
These APIs currently lack an important piece of documentation: **the raw pointer must point to a block of memory allocated by the global allocator**. This crucial detail is specified in the source code but is not reflected in the documentation, which could lead to confusion or incorrect usage by users.
### Problem:
The following example demonstrates the potential confusion caused by the lack of documentation:
```rust
#![feature(allocator_api)]
use std::alloc::{Allocator,AllocError, Layout};
use std::ptr::NonNull;
use std::sync::Arc;
struct LocalAllocator {
memory: NonNull<u8>,
size: usize,
}
impl LocalAllocator {
fn new(size: usize) -> Self {
Self {
memory: unsafe { NonNull::new_unchecked(&mut 0u8 as *mut u8) },
size,
}
}
}
unsafe impl Allocator for LocalAllocator {
fn allocate(&self, _layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
Ok(NonNull::slice_from_raw_parts(self.memory, self.size))
}
unsafe fn deallocate(&self, _ptr: NonNull<u8>, _layout: Layout) {
}
}
fn main() {
let allocator = LocalAllocator::new(64);
let arc = Arc::new_in(5, &allocator); // Here, allocator could be any non-global allocator
let ptr = Arc::into_raw(arc);
unsafe {
Arc::increment_strong_count(ptr);
let arc = Arc::from_raw(ptr);
assert_eq!(2, Arc::strong_count(&arc)); // Failed here!
}
}
```
87b3671ce9