You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rollup merge of #134496 - DiuDiu777:fix-doc, r=ibraheemdev
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](#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!
}
}
```
0 commit comments