Rollup merge of #129449 - coolreader18:pin-as_deref_mut-signature, r=… · patricklam/verify-rust-std@acf6f03 (original) (raw)

`@@ -1291,8 +1291,8 @@ impl<Ptr: Deref> Pin {

1291

`` /// // Now, if x was the only reference, we have a mutable reference to

1292

`/// // data that we pinned above, which we could use to move it as we have

1293

`/// // seen in the previous example. We have violated the pinning API contract.

1294

/// }

1295


/// ```

1294

/// }

1295


/// ```

1296

`///

1297

`/// ## Pinning of closure captures

1298

`///

`@@ -1370,33 +1370,6 @@ impl<Ptr: Deref> Pin {

1370

`unsafe { Pin::new_unchecked(&*self.__pointer) }

1371

1372

1373

`` -

/// Unwraps this Pin<Ptr>, returning the underlying Ptr.

1374

///

1375

/// # Safety

1376

///

1377

/// This function is unsafe. You must guarantee that you will continue to

1378

`` -

/// treat the pointer Ptr as pinned after you call this function, so that

1379

`` -

/// the invariants on the Pin type can be upheld. If the code using the

1380

`` -

/// resulting Ptr does not continue to maintain the pinning invariants that

1381

/// is a violation of the API contract and may lead to undefined behavior in

1382

/// later (safe) operations.

1383

///

1384

`` -

/// Note that you must be able to guarantee that the data pointed to by Ptr

1385

`` -

/// will be treated as pinned all the way until its drop handler is complete!

1386

///

1387

`` -

/// For more information, see the [pin module docs][self]

1388

///

1389

`` -

/// If the underlying data is [Unpin], [Pin::into_inner] should be used

1390

/// instead.

1391

#[inline(always)]

1392

#[rustc_const_unstable(feature = "const_pin", issue = "76654")]

1393

#[stable(feature = "pin_into_inner", since = "1.39.0")]

1394

pub const unsafe fn into_inner_unchecked(pin: Pin) -> Ptr {

1395

pin.__pointer

1396

}

1397

}

1398

-

1399

impl<Ptr: DerefMut> Pin {

1400

1373

`` /// Gets a mutable reference to the pinned value this Pin<Ptr> points to.

1401

1374

`///

1402

1375

`` /// This is a generic method to go from &mut Pin<Pointer<T>> to Pin<&mut T>.

`@@ -1428,11 +1401,55 @@ impl<Ptr: DerefMut> Pin {

1428

1401

```` /// ```

````

1429

1402

`#[stable(feature = "pin", since = "1.33.0")]

1430

1403

`#[inline(always)]

1431

pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target> {

1404

pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target>

1405

where

1406

Ptr: DerefMut,

1407

{

1432

1408

`// SAFETY: see documentation on this function

1433

1409

`unsafe { Pin::new_unchecked(&mut *self.__pointer) }

1434

1410

1435

1411

1412

`` +

/// Gets Pin<&mut T> to the underlying pinned value from this nested Pin-pointer.

1413

///

1414

`` +

/// This is a generic method to go from Pin<&mut Pin<Pointer<T>>> to Pin<&mut T>. It is

1415

`` +

/// safe because the existence of a Pin<Pointer<T>> ensures that the pointee, T, cannot

1416

/// move in the future, and this method does not enable the pointee to move. "Malicious"

1417

`` +

/// implementations of Ptr::DerefMut are likewise ruled out by the contract of

1418

`` +

/// Pin::new_unchecked.

1419

#[unstable(feature = "pin_deref_mut", issue = "86918")]

1420

`` +

#[must_use = "self will be dropped if the result is not used"]

1421

#[inline(always)]

1422

pub fn as_deref_mut(self: Pin<&mut Pin>) -> Pin<&mut Ptr::Target>

1423

where

1424

Ptr: DerefMut,

1425

{

1426

// SAFETY: What we're asserting here is that going from

1427

1428

// Pin<&mut Pin>

1429

1430

// to

1431

1432

// Pin<&mut Ptr::Target>

1433

1434

// is safe.

1435

1436

// We need to ensure that two things hold for that to be the case:

1437

1438

`` +

// 1) Once we give out a Pin<&mut Ptr::Target>, a &mut Ptr::Target will not be given out.

1439

`` +

// 2) By giving out a Pin<&mut Ptr::Target>, we do not risk violating

1440

`` +

// Pin<&mut Pin<Ptr>>

1441

1442

`` +

// The existence of Pin<Ptr> is sufficient to guarantee #1: since we already have a

1443

`` +

// Pin<Ptr>, it must already uphold the pinning guarantees, which must mean that

1444

`` +

// Pin<&mut Ptr::Target> does as well, since Pin::as_mut is safe. We do not have to rely

1445

`` +

// on the fact that Ptr is also pinned.

1446

1447

`` +

// For #2, we need to ensure that code given a Pin<&mut Ptr::Target> cannot cause the

1448

`` +

// Pin<Ptr> to move? That is not possible, since Pin<&mut Ptr::Target> no longer retains

1449

`` +

// any access to the Ptr itself, much less the Pin<Ptr>.

1450

unsafe { self.get_unchecked_mut() }.as_mut()

1451

}

1452

+

1436

1453

`` /// Assigns a new value to the memory location pointed to by the Pin<Ptr>.

1437

1454

`///

1438

1455

`/// This overwrites pinned data, but that is okay: the original pinned value's destructor gets

`@@ -1457,10 +1474,36 @@ impl<Ptr: DerefMut> Pin {

1457

1474

`#[inline(always)]

1458

1475

`pub fn set(&mut self, value: Ptr::Target)

1459

1476

`where

1477

Ptr: DerefMut,

1460

1478

`Ptr::Target: Sized,

1461

1479

1462

1480

`*(self.__pointer) = value;

1463

1481

1482

+

1483

`` +

/// Unwraps this Pin<Ptr>, returning the underlying Ptr.

1484

///

1485

/// # Safety

1486

///

1487

/// This function is unsafe. You must guarantee that you will continue to

1488

`` +

/// treat the pointer Ptr as pinned after you call this function, so that

1489

`` +

/// the invariants on the Pin type can be upheld. If the code using the

1490

`` +

/// resulting Ptr does not continue to maintain the pinning invariants that

1491

/// is a violation of the API contract and may lead to undefined behavior in

1492

/// later (safe) operations.

1493

///

1494

`` +

/// Note that you must be able to guarantee that the data pointed to by Ptr

1495

`` +

/// will be treated as pinned all the way until its drop handler is complete!

1496

///

1497

`` +

/// For more information, see the [pin module docs][self]

1498

///

1499

`` +

/// If the underlying data is [Unpin], [Pin::into_inner] should be used

1500

/// instead.

1501

#[inline(always)]

1502

#[rustc_const_unstable(feature = "const_pin", issue = "76654")]

1503

#[stable(feature = "pin_into_inner", since = "1.39.0")]

1504

pub const unsafe fn into_inner_unchecked(pin: Pin) -> Ptr {

1505

pin.__pointer

1506

}

1464

1507

1465

1508

1466

1509

`impl<'a, T: ?Sized> Pin<&'a T> {

`@@ -1613,46 +1656,6 @@ impl<T: ?Sized> Pin<&'static T> {

1613

1656

1614

1657

1615

1658

1616

impl<'a, Ptr: DerefMut> Pin<&'a mut Pin> {

1617

`` -

/// Gets Pin<&mut T> to the underlying pinned value from this nested Pin-pointer.

1618

///

1619

`` -

/// This is a generic method to go from Pin<&mut Pin<Pointer<T>>> to Pin<&mut T>. It is

1620

`` -

/// safe because the existence of a Pin<Pointer<T>> ensures that the pointee, T, cannot

1621

/// move in the future, and this method does not enable the pointee to move. "Malicious"

1622

`` -

/// implementations of Ptr::DerefMut are likewise ruled out by the contract of

1623

`` -

/// Pin::new_unchecked.

1624

#[unstable(feature = "pin_deref_mut", issue = "86918")]

1625

`` -

#[must_use = "self will be dropped if the result is not used"]

1626

#[inline(always)]

1627

pub fn as_deref_mut(self) -> Pin<&'a mut Ptr::Target> {

1628

// SAFETY: What we're asserting here is that going from

1629

1630

// Pin<&mut Pin>

1631

1632

// to

1633

1634

// Pin<&mut Ptr::Target>

1635

1636

// is safe.

1637

1638

// We need to ensure that two things hold for that to be the case:

1639

1640

`` -

// 1) Once we give out a Pin<&mut Ptr::Target>, a &mut Ptr::Target will not be given out.

1641

`` -

// 2) By giving out a Pin<&mut Ptr::Target>, we do not risk violating

1642

`` -

// Pin<&mut Pin<Ptr>>

1643

1644

`` -

// The existence of Pin<Ptr> is sufficient to guarantee #1: since we already have a

1645

`` -

// Pin<Ptr>, it must already uphold the pinning guarantees, which must mean that

1646

`` -

// Pin<&mut Ptr::Target> does as well, since Pin::as_mut is safe. We do not have to rely

1647

`` -

// on the fact that Ptr is also pinned.

1648

1649

`` -

// For #2, we need to ensure that code given a Pin<&mut Ptr::Target> cannot cause the

1650

`` -

// Pin<Ptr> to move? That is not possible, since Pin<&mut Ptr::Target> no longer retains

1651

`` -

// any access to the Ptr itself, much less the Pin<Ptr>.

1652

unsafe { self.get_unchecked_mut() }.as_mut()

1653

}

1654

}

1655

-

1656

1659

`impl<T: ?Sized> Pin<&'static mut T> {

1657

1660

`/// Gets a pinning mutable reference from a static mutable reference.

1658

1661

`///