mozilla
/
gecko-dev
зеркало из https://github.com/mozilla/gecko-dev.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

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:
Ms2ger 2014-06-13 15:01:54 -04:00
Родитель a07db23157
Коммит 3bb550df0f
1 изменённых файлов: 57 добавлений и 54 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

111
servo/src/components/script/dom/bindings/js.rs
Просмотреть файл

@ -2,42 +2,45 @@
* 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/. */
/// 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
/// that any interactions with said Rust types only occur on values that will remain alive
/// the entire time.
///
/// 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
/// 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
/// somewhere that is reachable by the GC.
/// - All functions take &JSRef<T> arguments, to ensure that they will remain uncollected for
/// the duration of their usage.
/// - All types contain JS<T> fields and derive the Encodable trait, to ensure that they are
/// 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
/// will not be collected for the duration of the method call.
///
/// Both Temporary<T> and JS<T> do not allow access to their inner value without explicitly
/// 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.
/// A JSRef<T> can be obtained from a Root<T> either by dereferencing the Root<T> (`*rooted`)
/// or explicitly calling the `root_ref` method. These JSRef<T> values are not allowed to
/// 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
/// misused.
///
/// Other miscellaneous helper traits:
/// - OptionalRootable and OptionalRootedRootable: make rooting Option values easy via a `root` method
/// - 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
//! 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
//! that any interactions with said Rust types only occur on values that will remain alive
//! the entire time.
//!
//! 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
//! 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
//! somewhere that is reachable by the GC.
//! - All functions take `&JSRef<T>` arguments, to ensure that they will remain uncollected for
//! the duration of their usage.
//! - All types contain `JS<T>` fields and derive the `Encodable` trait, to ensure that they are
//! 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
//! will not be collected for the duration of the method call.
//!
//! Both `Temporary<T>` and `JS<T>` do not allow access to their inner value without explicitly
//! 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` object's lifetime.
//! A `JSRef<T>` can be obtained from a `Root<T>` either by dereferencing the `Root<T>` (`*rooted`)
//! or explicitly calling the `root_ref` method. These `JSRef<T>` values are not allowed to
//! 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
//! misused.
//!
//! Other miscellaneous helper traits:
//!
//! - `OptionalRootable` and `OptionalRootedRootable`: make rooting `Option` values easy via a `root` method
//! - `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::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.
/// 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
/// `JS<T>::assign` method or `OptionalSettable::assign` (for Option<JS<T>> fields).
/// 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).
pub struct Temporary<T> {
inner: JS<T>,
/// On-stack JS pointer to assuage conservative stack scanner
@ -67,7 +70,7 @@ impl<T> Eq for 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> {
Temporary {
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> {
Temporary::new(JS::from_rooted(root))
}
@ -119,7 +122,7 @@ impl <T> Clone for JS<T> {
}
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> {
let TrustedNodeAddress(addr) = inner;
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> {
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> {
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
/// original value.
/*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
/// field of a DOM type (ie. Option<JS<T>>)
/// Assign an optional rootable value (either of `JS<T>` or `Temporary<T>`) to an optional
/// field of a DOM type (ie. `Option<JS<T>>`)
pub trait OptionalSettable<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> {
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> {
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> {
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> {
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;
/// 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.
/// Attempts to transfer ownership of a Root via moving will trigger dynamic unrooting
/// 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
/// failures due to incorrect ordering.
pub struct Root<'a, 'b, T> {
/// 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> {
/// Create a new stack-bounded root for the provided JS-owned value.
/// It cannot not outlive its associated RootCollection, and it contains a JSRef
/// which cannot outlive this new Root.
/// It cannot not outlive its associated `RootCollection`, and it contains a `JSRef`
/// which cannot outlive this new `Root`.
fn new(roots: &'a RootCollection, unrooted: &JS<T>) -> Root<'a, 'b, T> {
let root = Root {
root_list: roots,