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.

Sign up for GitHub

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

Jump to bottom

Minor doc improvements on AllocRef #70728

Merged
merged 2 commits into from
Apr 3, 2020
Merged

Minor doc improvements on AllocRef #70728

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8b0c5f
Minor doc improvements on `AllocRef`
TimDiekmann Apr 3, 2020
c061ff4
Update mod.rs
TimDiekmann Apr 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions src/libcore/alloc/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ pub enum ReallocPlacement {
///
/// Unlike [`GlobalAlloc`][], zero-sized allocations are allowed in `AllocRef`. If an underlying
/// allocator does not support this (like jemalloc) or return a null pointer (such as
/// `libc::malloc`), this case must be caught.
/// `libc::malloc`), this is caught by the implementation.
TimDiekmann marked this conversation as resolved.
Show resolved Hide resolved
///
/// ### Currently allocated memory
///
Expand Down Expand Up @@ -157,18 +157,20 @@ pub enum ReallocPlacement {
/// # Safety
///
/// * Memory blocks returned from an allocator must point to valid memory and retain their validity
/// until the instance and all of its clones are dropped, and
/// until the instance and all of its clones are dropped,
///
/// * cloning or moving the allocator must not invalidate memory blocks returned from this
/// allocator. A cloned allocator must behave like the same allocator.
/// allocator. A cloned allocator must behave like the same allocator, and
///
/// * any pointer to a memory block which is [*currently allocated*] may be passed to any other
/// method of the allocator.
///
/// [*currently allocated*]: #currently-allocated-memory
#[unstable(feature = "allocator_api", issue = "32838")]
pub unsafe trait AllocRef {
/// On success, returns a memory block meeting the size and alignment guarantees of `layout`.
/// Attempts to allocate a block of memory.
///
/// On success, returns a [`MemoryBlock`][] meeting the size and alignment guarantees of `layout`.
///
/// The returned block may have a larger size than specified by `layout.size()` and is
/// initialized as specified by [`init`], all the way up to the returned size of the block.
Expand All @@ -190,26 +192,26 @@ pub unsafe trait AllocRef {
/// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
fn alloc(&mut self, layout: Layout, init: AllocInit) -> Result<MemoryBlock, AllocErr>;

/// Deallocates the memory denoted by `memory`.
/// Deallocates the memory referenced by `ptr`.
///
/// # Safety
///
/// * `ptr` must be [*currently allocated*] via this allocator, and
/// * `layout` must [*fit*] the `ptr`.
/// * `ptr` must denote a block of memory [*currently allocated*] via this allocator, and
/// * `layout` must [*fit*] that block of memory.
///
/// [*currently allocated*]: #currently-allocated-memory
/// [*fit*]: #memory-fitting
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout);

/// Attempts to extend the memory block.
///
/// Returns a new memory block containing a pointer and the actual size of the allocated
/// block. The pointer is suitable for holding data described by a new layout with `layout`’s
/// Returns a new [`MemoryBlock`][] containing a pointer and the actual size of the allocated
/// memory. The pointer is suitable for holding data described by a new layout with `layout`’s
/// alignment and a size given by `new_size`. To accomplish this, the allocator may extend the
/// allocation referenced by `ptr` to fit the new layout. If the [`placement`] is
/// [`InPlace`], the returned pointer is guaranteed to be the same as the passed `ptr`.
///
/// If `ReallocPlacement::MayMove` is used then ownership of the memory block referenced by `ptr`
/// If [`MayMove`] is used then ownership of the memory block referenced by `ptr`
/// is transferred to this allocator. The memory may or may not be freed, and should be
/// considered unusable (unless of course it is transferred back to the caller again via the
/// return value of this method).
Expand All @@ -227,17 +229,18 @@ pub unsafe trait AllocRef {
/// the size of the `MemoryBlock` returned by the `grow` call.
///
/// [`InPlace`]: ReallocPlacement::InPlace
/// [`MayMove`]: ReallocPlacement::MayMove
/// [`placement`]: ReallocPlacement
/// [`init`]: AllocInit
///
/// # Safety
///
/// * `ptr` must be [*currently allocated*] via this allocator,
/// * `layout` must [*fit*] the `ptr`. (The `new_size` argument need not fit it.)
/// * `ptr` must denote a block of memory [*currently allocated*] via this allocator,
/// * `layout` must [*fit*] that block of memory (The `new_size` argument need not fit it.),
// We can't require that `new_size` is strictly greater than `memory.size` because of ZSTs.
// An alternative would be
// * `new_size must be strictly greater than `memory.size` or both are zero
/// * `new_size` must be greater than or equal to `layout.size()`
/// * `new_size` must be greater than or equal to `layout.size()`, and
/// * `new_size`, when rounded up to the nearest multiple of `layout.align()`, must not overflow
/// (i.e., the rounded value must be less than or equal to `usize::MAX`).
///
Expand Down Expand Up @@ -289,8 +292,8 @@ pub unsafe trait AllocRef {

/// Attempts to shrink the memory block.
///
/// Returns a new memory block containing a pointer and the actual size of the allocated
/// block. The pointer is suitable for holding data described by a new layout with `layout`’s
/// Returns a new [`MemoryBlock`][] containing a pointer and the actual size of the allocated
/// memory. The pointer is suitable for holding data described by a new layout with `layout`’s
/// alignment and a size given by `new_size`. To accomplish this, the allocator may shrink the
/// allocation referenced by `ptr` to fit the new layout. If the [`placement`] is
/// [`InPlace`], the returned pointer is guaranteed to be the same as the passed `ptr`.
Expand All @@ -310,20 +313,20 @@ pub unsafe trait AllocRef {
///
/// # Safety
///
/// * `ptr` must be [*currently allocated*] via this allocator,
/// * `layout` must [*fit*] the `ptr`. (The `new_size` argument need not fit it.)
/// * `ptr` must denote a block of memory [*currently allocated*] via this allocator,
/// * `layout` must [*fit*] that block of memory (The `new_size` argument need not fit it.), and
// We can't require that `new_size` is strictly smaller than `memory.size` because of ZSTs.
// An alternative would be
// * `new_size must be strictly smaller than `memory.size` or both are zero
/// * `new_size` must be smaller than or equal to `layout.size()`
/// * `new_size` must be smaller than or equal to `layout.size()`.
///
/// [*currently allocated*]: #currently-allocated-memory
/// [*fit*]: #memory-fitting
///
/// # Errors
///
/// Returns `Err` if the new layout does not meet the allocator's size and alignment
/// constraints of the allocator, or if growing otherwise fails.
/// constraints of the allocator, or if shrinking otherwise fails.
///
/// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
/// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
Expand Down