зеркало из https://github.com/mozilla/gecko-dev.git
servo: Merge #2653 - Make rustdoc handle the documentation in js.rs (from Ms2ger:docs); r=Ms2ger,metajack
Source-Repo: https://github.com/servo/servo Source-Revision: 239fa77dd52a364634cdee0f4c1e762d602cecb7
This commit is contained in:
Родитель
a07db23157
Коммит
3bb550df0f
|
@ -2,42 +2,45 @@
|
||||||
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||||
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
||||||
|
|
||||||
/// The DOM is made up of Rust types whose lifetime is entirely controlled by the whims of
|
//! The DOM is made up of Rust types whose lifetime is entirely controlled by the whims of
|
||||||
/// the SpiderMonkey garbage collector. The types in this module are designed to ensure
|
//! the SpiderMonkey garbage collector. The types in this module are designed to ensure
|
||||||
/// that any interactions with said Rust types only occur on values that will remain alive
|
//! that any interactions with said Rust types only occur on values that will remain alive
|
||||||
/// the entire time.
|
//! the entire time.
|
||||||
///
|
//!
|
||||||
/// Here is a brief overview of the important types:
|
//! Here is a brief overview of the important types:
|
||||||
/// - JSRef<T>: a freely-copyable reference to a rooted value.
|
//!
|
||||||
/// - JS<T>: a pointer to JS-owned memory that can automatically be traced by the GC when
|
//! - `JSRef<T>`: a freely-copyable reference to a rooted value.
|
||||||
/// encountered as a field of a Rust structure.
|
//! - `JS<T>`: a pointer to JS-owned memory that can automatically be traced by the GC when
|
||||||
/// - Temporary<T>: a value that will remain rooted for the duration of its lifetime.
|
//! encountered as a field of a Rust structure.
|
||||||
///
|
//! - `Temporary<T>`: a value that will remain rooted for the duration of its lifetime.
|
||||||
/// The rule of thumb is as follows:
|
//!
|
||||||
/// - All methods return Temporary<T>, to ensure the value remains alive until it is stored
|
//! The rule of thumb is as follows:
|
||||||
/// somewhere that is reachable by the GC.
|
//!
|
||||||
/// - All functions take &JSRef<T> arguments, to ensure that they will remain uncollected for
|
//! - All methods return `Temporary<T>`, to ensure the value remains alive until it is stored
|
||||||
/// the duration of their usage.
|
//! somewhere that is reachable by the GC.
|
||||||
/// - All types contain JS<T> fields and derive the Encodable trait, to ensure that they are
|
//! - All functions take `&JSRef<T>` arguments, to ensure that they will remain uncollected for
|
||||||
/// transitively marked as reachable by the GC if the enclosing value is reachable.
|
//! the duration of their usage.
|
||||||
/// - All methods for type T are implemented for JSRef<T>, to ensure that the self value
|
//! - All types contain `JS<T>` fields and derive the `Encodable` trait, to ensure that they are
|
||||||
/// will not be collected for the duration of the method call.
|
//! transitively marked as reachable by the GC if the enclosing value is reachable.
|
||||||
///
|
//! - All methods for type `T` are implemented for `JSRef<T>`, to ensure that the self value
|
||||||
/// Both Temporary<T> and JS<T> do not allow access to their inner value without explicitly
|
//! will not be collected for the duration of the method call.
|
||||||
/// creating a stack-based root via the `root` method. This returns a Root<T>, which causes
|
//!
|
||||||
/// the JS-owned value to be uncollectable for the duration of the Root type's lifetime.
|
//! Both `Temporary<T>` and `JS<T>` do not allow access to their inner value without explicitly
|
||||||
/// A JSRef<T> can be obtained from a Root<T> either by dereferencing the Root<T> (`*rooted`)
|
//! creating a stack-based root via the `root` method. This returns a `Root<T>`, which causes
|
||||||
/// or explicitly calling the `root_ref` method. These JSRef<T> values are not allowed to
|
//! the JS-owned value to be uncollectable for the duration of the `Root` object's lifetime.
|
||||||
/// outlive their originating Root<T>, to ensure that all interactions with the enclosed value
|
//! A `JSRef<T>` can be obtained from a `Root<T>` either by dereferencing the `Root<T>` (`*rooted`)
|
||||||
/// only occur when said value is uncollectable, and will cause static lifetime errors if
|
//! or explicitly calling the `root_ref` method. These `JSRef<T>` values are not allowed to
|
||||||
/// misused.
|
//! outlive their originating `Root<T>`, to ensure that all interactions with the enclosed value
|
||||||
///
|
//! only occur when said value is uncollectable, and will cause static lifetime errors if
|
||||||
/// Other miscellaneous helper traits:
|
//! misused.
|
||||||
/// - OptionalRootable and OptionalRootedRootable: make rooting Option values easy via a `root` method
|
//!
|
||||||
/// - ResultRootable: make rooting successful Result values easy
|
//! Other miscellaneous helper traits:
|
||||||
/// - TemporaryPushable: allows mutating vectors of JS<T> with new elements of JSRef/Temporary
|
//!
|
||||||
/// - OptionalSettable: allows assigning Option values of JSRef/Temporary to fields of Option<JS<T>>
|
//! - `OptionalRootable` and `OptionalRootedRootable`: make rooting `Option` values easy via a `root` method
|
||||||
/// - RootedReference: makes obtaining an Option<JSRef<T>> from an Option<Root<T>> easy
|
//! - `ResultRootable`: make rooting successful `Result` values easy
|
||||||
|
//! - `TemporaryPushable`: allows mutating vectors of `JS<T>` with new elements of `JSRef`/`Temporary`
|
||||||
|
//! - `OptionalSettable`: allows assigning `Option` values of `JSRef`/`Temporary` to fields of `Option<JS<T>>`
|
||||||
|
//! - `RootedReference`: makes obtaining an `Option<JSRef<T>>` from an `Option<Root<T>>` easy
|
||||||
|
|
||||||
use dom::bindings::utils::{Reflector, Reflectable};
|
use dom::bindings::utils::{Reflector, Reflectable};
|
||||||
use dom::node::Node;
|
use dom::node::Node;
|
||||||
|
@ -52,8 +55,8 @@ use std::mem;
|
||||||
|
|
||||||
/// A type that represents a JS-owned value that is rooted for the lifetime of this value.
|
/// A type that represents a JS-owned value that is rooted for the lifetime of this value.
|
||||||
/// Importantly, it requires explicit rooting in order to interact with the inner value.
|
/// Importantly, it requires explicit rooting in order to interact with the inner value.
|
||||||
/// Can be assigned into JS-owned member fields (ie. JS<T> types) safely via the
|
/// Can be assigned into JS-owned member fields (i.e. `JS<T>` types) safely via the
|
||||||
/// `JS<T>::assign` method or `OptionalSettable::assign` (for Option<JS<T>> fields).
|
/// `JS<T>::assign` method or `OptionalSettable::assign` (for `Option<JS<T>>` fields).
|
||||||
pub struct Temporary<T> {
|
pub struct Temporary<T> {
|
||||||
inner: JS<T>,
|
inner: JS<T>,
|
||||||
/// On-stack JS pointer to assuage conservative stack scanner
|
/// On-stack JS pointer to assuage conservative stack scanner
|
||||||
|
@ -67,7 +70,7 @@ impl<T> Eq for Temporary<T> {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl<T: Reflectable> Temporary<T> {
|
impl<T: Reflectable> Temporary<T> {
|
||||||
/// Create a new Temporary value from a JS-owned value.
|
/// Create a new `Temporary` value from a JS-owned value.
|
||||||
pub fn new(inner: JS<T>) -> Temporary<T> {
|
pub fn new(inner: JS<T>) -> Temporary<T> {
|
||||||
Temporary {
|
Temporary {
|
||||||
inner: inner,
|
inner: inner,
|
||||||
|
@ -75,7 +78,7 @@ impl<T: Reflectable> Temporary<T> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Create a new Temporary value from a rooted value.
|
/// Create a new `Temporary` value from a rooted value.
|
||||||
pub fn from_rooted<'a>(root: &JSRef<'a, T>) -> Temporary<T> {
|
pub fn from_rooted<'a>(root: &JSRef<'a, T>) -> Temporary<T> {
|
||||||
Temporary::new(JS::from_rooted(root))
|
Temporary::new(JS::from_rooted(root))
|
||||||
}
|
}
|
||||||
|
@ -119,7 +122,7 @@ impl <T> Clone for JS<T> {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl JS<Node> {
|
impl JS<Node> {
|
||||||
/// Create a new JS-owned value wrapped from an address known to be a Node pointer.
|
/// Create a new JS-owned value wrapped from an address known to be a `Node` pointer.
|
||||||
pub unsafe fn from_trusted_node_address(inner: TrustedNodeAddress) -> JS<Node> {
|
pub unsafe fn from_trusted_node_address(inner: TrustedNodeAddress) -> JS<Node> {
|
||||||
let TrustedNodeAddress(addr) = inner;
|
let TrustedNodeAddress(addr) = inner;
|
||||||
JS {
|
JS {
|
||||||
|
@ -201,7 +204,7 @@ impl<From, To> JS<From> {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/// Get an Option<JSRef<T>> out of an Option<Root<T>>
|
/// Get an `Option<JSRef<T>>` out of an `Option<Root<T>>`
|
||||||
pub trait RootedReference<T> {
|
pub trait RootedReference<T> {
|
||||||
fn root_ref<'a>(&'a self) -> Option<JSRef<'a, T>>;
|
fn root_ref<'a>(&'a self) -> Option<JSRef<'a, T>>;
|
||||||
}
|
}
|
||||||
|
@ -212,7 +215,7 @@ impl<'a, 'b, T: Reflectable> RootedReference<T> for Option<Root<'a, 'b, T>> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Get an Option<Option<JSRef<T>>> out of an Option<Option<Root<T>>>
|
/// Get an `Option<Option<JSRef<T>>>` out of an `Option<Option<Root<T>>>`
|
||||||
pub trait OptionalRootedReference<T> {
|
pub trait OptionalRootedReference<T> {
|
||||||
fn root_ref<'a>(&'a self) -> Option<Option<JSRef<'a, T>>>;
|
fn root_ref<'a>(&'a self) -> Option<Option<JSRef<'a, T>>>;
|
||||||
}
|
}
|
||||||
|
@ -223,7 +226,7 @@ impl<'a, 'b, T: Reflectable> OptionalRootedReference<T> for Option<Option<Root<'
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Trait that allows extracting a JS<T> value from a variety of rooting-related containers,
|
/// Trait that allows extracting a `JS<T>` value from a variety of rooting-related containers,
|
||||||
/// which in general is an unsafe operation since they can outlive the rooted lifetime of the
|
/// which in general is an unsafe operation since they can outlive the rooted lifetime of the
|
||||||
/// original value.
|
/// original value.
|
||||||
/*definitely not public*/ trait Assignable<T> {
|
/*definitely not public*/ trait Assignable<T> {
|
||||||
|
@ -248,8 +251,8 @@ impl<T: Reflectable> Assignable<T> for Temporary<T> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Assign an optional rootable value (either of JS<T> or Temporary<T>) to an optional
|
/// Assign an optional rootable value (either of `JS<T>` or `Temporary<T>`) to an optional
|
||||||
/// field of a DOM type (ie. Option<JS<T>>)
|
/// field of a DOM type (ie. `Option<JS<T>>`)
|
||||||
pub trait OptionalSettable<T> {
|
pub trait OptionalSettable<T> {
|
||||||
fn assign(&self, val: Option<T>);
|
fn assign(&self, val: Option<T>);
|
||||||
}
|
}
|
||||||
|
@ -261,7 +264,7 @@ impl<T: Assignable<U>, U: Reflectable> OptionalSettable<T> for Cell<Option<JS<U>
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/// Root a rootable Option type (used for Option<Temporary<T>>)
|
/// Root a rootable `Option` type (used for `Option<Temporary<T>>`)
|
||||||
pub trait OptionalRootable<T> {
|
pub trait OptionalRootable<T> {
|
||||||
fn root<'a, 'b>(self) -> Option<Root<'a, 'b, T>>;
|
fn root<'a, 'b>(self) -> Option<Root<'a, 'b, T>>;
|
||||||
}
|
}
|
||||||
|
@ -283,7 +286,7 @@ impl<'a, T: Reflectable> OptionalUnrootable<T> for Option<JSRef<'a, T>> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Root a rootable Option type (used for Option<JS<T>>)
|
/// Root a rootable `Option` type (used for `Option<JS<T>>`)
|
||||||
pub trait OptionalRootedRootable<T> {
|
pub trait OptionalRootedRootable<T> {
|
||||||
fn root<'a, 'b>(&self) -> Option<Root<'a, 'b, T>>;
|
fn root<'a, 'b>(&self) -> Option<Root<'a, 'b, T>>;
|
||||||
}
|
}
|
||||||
|
@ -294,7 +297,7 @@ impl<T: Reflectable> OptionalRootedRootable<T> for Option<JS<T>> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Root a rootable Option<Option> type (used for Option<Option<JS<T>>>)
|
/// Root a rootable `Option<Option>` type (used for `Option<Option<JS<T>>>`)
|
||||||
pub trait OptionalOptionalRootedRootable<T> {
|
pub trait OptionalOptionalRootedRootable<T> {
|
||||||
fn root<'a, 'b>(&self) -> Option<Option<Root<'a, 'b, T>>>;
|
fn root<'a, 'b>(&self) -> Option<Option<Root<'a, 'b, T>>>;
|
||||||
}
|
}
|
||||||
|
@ -306,7 +309,7 @@ impl<T: Reflectable> OptionalOptionalRootedRootable<T> for Option<Option<JS<T>>>
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/// Root a rootable Result type (any of Temporary<T> or JS<T>)
|
/// Root a rootable `Result` type (any of `Temporary<T>` or `JS<T>`)
|
||||||
pub trait ResultRootable<T,U> {
|
pub trait ResultRootable<T,U> {
|
||||||
fn root<'a, 'b>(self) -> Result<Root<'a, 'b, T>, U>;
|
fn root<'a, 'b>(self) -> Result<Root<'a, 'b, T>, U>;
|
||||||
}
|
}
|
||||||
|
@ -377,8 +380,8 @@ impl RootCollection {
|
||||||
|
|
||||||
/// A rooted JS value. The JS value is pinned for the duration of this object's lifetime;
|
/// A rooted JS value. The JS value is pinned for the duration of this object's lifetime;
|
||||||
/// roots are additive, so this object's destruction will not invalidate other roots
|
/// roots are additive, so this object's destruction will not invalidate other roots
|
||||||
/// for the same JS value. Roots cannot outlive the associated RootCollection object.
|
/// for the same JS value. `Root`s cannot outlive the associated `RootCollection` object.
|
||||||
/// Attempts to transfer ownership of a Root via moving will trigger dynamic unrooting
|
/// Attempts to transfer ownership of a `Root` via moving will trigger dynamic unrooting
|
||||||
/// failures due to incorrect ordering.
|
/// failures due to incorrect ordering.
|
||||||
pub struct Root<'a, 'b, T> {
|
pub struct Root<'a, 'b, T> {
|
||||||
/// List that ensures correct dynamic root ordering
|
/// List that ensures correct dynamic root ordering
|
||||||
|
@ -393,8 +396,8 @@ pub struct Root<'a, 'b, T> {
|
||||||
|
|
||||||
impl<'a, 'b, T: Reflectable> Root<'a, 'b, T> {
|
impl<'a, 'b, T: Reflectable> Root<'a, 'b, T> {
|
||||||
/// Create a new stack-bounded root for the provided JS-owned value.
|
/// Create a new stack-bounded root for the provided JS-owned value.
|
||||||
/// It cannot not outlive its associated RootCollection, and it contains a JSRef
|
/// It cannot not outlive its associated `RootCollection`, and it contains a `JSRef`
|
||||||
/// which cannot outlive this new Root.
|
/// which cannot outlive this new `Root`.
|
||||||
fn new(roots: &'a RootCollection, unrooted: &JS<T>) -> Root<'a, 'b, T> {
|
fn new(roots: &'a RootCollection, unrooted: &JS<T>) -> Root<'a, 'b, T> {
|
||||||
let root = Root {
|
let root = Root {
|
||||||
root_list: roots,
|
root_list: roots,
|
||||||
|
|
Загрузка…
Ссылка в новой задаче