Restore RawVec::reserve* documentation · rust-lang/rust@9c4e5b3 (original) (raw)

`@@ -385,26 +385,7 @@ impl<T, A: Alloc> RawVec<T, A> {

385

386

387

388

/// Ensures that the buffer contains at least enough space to hold

389

`` -

/// used_cap + needed_extra_cap elements. If it doesn't already,

390

/// will reallocate the minimum possible amount of memory necessary.

391

/// Generally this will be exactly the amount of memory necessary,

392

/// but in principle the allocator is free to give back more than

393

/// we asked for.

394

///

395

`` -

/// If used_cap exceeds self.cap(), this may fail to actually allocate

396

/// the requested space. This is not really unsafe, but the unsafe

397

/// code you write that relies on the behavior of this function may break.

398

///

399

/// # Panics

400

///

401

`` -

/// * Panics if the requested capacity exceeds usize::MAX bytes.

402

/// * Panics on 32-bit platforms if the requested capacity exceeds

403

`` -

/// isize::MAX bytes.

404

///

405

/// # Aborts

406

///

407

/// Aborts on OOM

388

`` +

/// The same as reserve_exact, but returns on errors instead of panicking or aborting.

408

389

`pub fn try_reserve_exact(&mut self, used_cap: usize, needed_extra_cap: usize)

409

390

` -> Result<(), CollectionAllocErr> {

410

391

`@@ -441,6 +422,26 @@ impl<T, A: Alloc> RawVec<T, A> {

441

422

442

423

443

424

425

/// Ensures that the buffer contains at least enough space to hold

426

`` +

/// used_cap + needed_extra_cap elements. If it doesn't already,

427

/// will reallocate the minimum possible amount of memory necessary.

428

/// Generally this will be exactly the amount of memory necessary,

429

/// but in principle the allocator is free to give back more than

430

/// we asked for.

431

///

432

`` +

/// If used_cap exceeds self.cap(), this may fail to actually allocate

433

/// the requested space. This is not really unsafe, but the unsafe

434

/// code you write that relies on the behavior of this function may break.

435

///

436

/// # Panics

437

///

438

`` +

/// * Panics if the requested capacity exceeds usize::MAX bytes.

439

/// * Panics on 32-bit platforms if the requested capacity exceeds

440

`` +

/// isize::MAX bytes.

441

///

442

/// # Aborts

443

///

444

/// Aborts on OOM

444

445

`pub fn reserve_exact(&mut self, used_cap: usize, needed_extra_cap: usize) {

445

446

`match self.try_reserve_exact(used_cap, needed_extra_cap) {

446

447

`Err(CapacityOverflow) => capacity_overflow(),

`@@ -463,6 +464,42 @@ impl<T, A: Alloc> RawVec<T, A> {

463

464

`Ok(cmp::max(double_cap, required_cap))

464

465

466

467

`` +

/// The same as reserve, but returns on errors instead of panicking or aborting.

468

pub fn try_reserve(&mut self, used_cap: usize, needed_extra_cap: usize)

469

-> Result<(), CollectionAllocErr> {

470

unsafe {

471

// NOTE: we don't early branch on ZSTs here because we want this

472

// to actually catch "asking for more than usize::MAX" in that case.

473

// If we make it past the first branch then we are guaranteed to

474

// panic.

475

+

476

// Don't actually need any more capacity.

477

`` +

// Wrapping in case they give a bad used_cap

478

if self.cap().wrapping_sub(used_cap) >= needed_extra_cap {

479

return Ok(());

480

}

481

+

482

let new_cap = self.amortized_new_size(used_cap, needed_extra_cap)?;

483

let new_layout = Layout::array::(new_cap).map_err(|_| CapacityOverflow)?;

484

+

485

// FIXME: may crash and burn on over-reserve

486

alloc_guard(new_layout.size())?;

487

+

488

let res = match self.current_layout() {

489

Some(layout) => {

490

debug_assert!(new_layout.align() == layout.align());

491

self.a.realloc(NonNull::from(self.ptr).as_opaque(), layout, new_layout.size())

492

}

493

None => self.a.alloc(new_layout),

494

};

495

+

496

self.ptr = res?.cast().into();

497

self.cap = new_cap;

498

+

499

Ok(())

500

}

501

}

502

+

466

503

`/// Ensures that the buffer contains at least enough space to hold

467

504

`` /// used_cap + needed_extra_cap elements. If it doesn't already have

468

505

`/// enough capacity, will reallocate enough space plus comfortable slack

`@@ -515,42 +552,6 @@ impl<T, A: Alloc> RawVec<T, A> {

515

552

`/// # vector.push_all(&[1, 3, 5, 7, 9]);

516

553

`/// # }

517

554

```` /// ```

````

518

pub fn try_reserve(&mut self, used_cap: usize, needed_extra_cap: usize)

519

-> Result<(), CollectionAllocErr> {

520

unsafe {

521

// NOTE: we don't early branch on ZSTs here because we want this

522

// to actually catch "asking for more than usize::MAX" in that case.

523

// If we make it past the first branch then we are guaranteed to

524

// panic.

525

-

526

// Don't actually need any more capacity.

527

`` -

// Wrapping in case they give a bad used_cap

528

if self.cap().wrapping_sub(used_cap) >= needed_extra_cap {

529

return Ok(());

530

}

531

-

532

let new_cap = self.amortized_new_size(used_cap, needed_extra_cap)?;

533

let new_layout = Layout::array::(new_cap).map_err(|_| CapacityOverflow)?;

534

-

535

// FIXME: may crash and burn on over-reserve

536

alloc_guard(new_layout.size())?;

537

-

538

let res = match self.current_layout() {

539

Some(layout) => {

540

debug_assert!(new_layout.align() == layout.align());

541

self.a.realloc(NonNull::from(self.ptr).as_opaque(), layout, new_layout.size())

542

}

543

None => self.a.alloc(new_layout),

544

};

545

-

546

self.ptr = res?.cast().into();

547

self.cap = new_cap;

548

-

549

Ok(())

550

}

551

}

552

-

553

/// The same as try_reserve, but errors are lowered to a call to oom().

554

555

`pub fn reserve(&mut self, used_cap: usize, needed_extra_cap: usize) {

555

556

`match self.try_reserve(used_cap, needed_extra_cap) {

556

557

`Err(CapacityOverflow) => capacity_overflow(),