style: Document the owning_handle module.

This commit is contained in:
Emilio Cobos Álvarez 2017-01-02 00:20:03 +01:00
parent 081b8399e6
commit b31470dddb
No known key found for this signature in database
GPG key ID: 056B727BB9C1027C

View file

@ -3,6 +3,9 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#![allow(unsafe_code)]
#![deny(missing_docs)]
//! A handle that encapsulate a reference to a given data along with its owner.
use owning_ref::StableAddress;
use std::ops::{Deref, DerefMut};
@ -24,21 +27,23 @@ use std::ops::{Deref, DerefMut};
///
/// This does foist some unsafety onto the callback, which needs an `unsafe`
/// block to dereference the pointer. It would be almost good enough for
/// OwningHandle to pass a transmuted &'statc reference to the callback
/// OwningHandle to pass a transmuted &'static reference to the callback
/// since the lifetime is infinite as far as the minted handle is concerned.
/// However, even an `Fn` callback can still allow the reference to escape
/// via a `StaticMutex` or similar, which technically violates the safety
/// contract. Some sort of language support in the lifetime system could
/// make this API a bit nicer.
pub struct OwningHandle<O, H>
where O: StableAddress, H: Deref,
where O: StableAddress,
H: Deref,
{
handle: H,
_owner: O,
}
impl<O, H> Deref for OwningHandle<O, H>
where O: StableAddress, H: Deref,
where O: StableAddress,
H: Deref,
{
type Target = H::Target;
fn deref(&self) -> &H::Target {
@ -47,11 +52,13 @@ impl<O, H> Deref for OwningHandle<O, H>
}
unsafe impl<O, H> StableAddress for OwningHandle<O, H>
where O: StableAddress, H: StableAddress,
where O: StableAddress,
H: StableAddress,
{}
impl<O, H> DerefMut for OwningHandle<O, H>
where O: StableAddress, H: DerefMut,
where O: StableAddress,
H: DerefMut,
{
fn deref_mut(&mut self) -> &mut H::Target {
self.handle.deref_mut()
@ -59,14 +66,15 @@ impl<O, H> DerefMut for OwningHandle<O, H>
}
impl<O, H> OwningHandle<O, H>
where O: StableAddress, H: Deref,
where O: StableAddress,
H: Deref,
{
/// Create a new OwningHandle. The provided callback will be invoked with
/// a pointer to the object owned by `o`, and the returned value is stored
/// as the object to which this `OwningHandle` will forward `Deref` and
/// `DerefMut`.
pub fn new<F>(o: O, f: F) -> Self
where F: Fn(*const O::Target) -> H
where F: Fn(*const O::Target) -> H,
{
let h: H;
{