From cd9fc4919dfd626b0bac5d899860d4ee8f963355 Mon Sep 17 00:00:00 2001 From: Zhen Zhang Date: Tue, 16 Aug 2016 23:53:08 +0200 Subject: [PATCH] Improve File API related comments --- components/net/filemanager_thread.rs | 14 +++++--------- components/net_traits/filemanager_thread.rs | 8 ++++---- components/script/dom/blob.rs | 16 +++++++++------- 3 files changed, 18 insertions(+), 20 deletions(-) diff --git a/components/net/filemanager_thread.rs b/components/net/filemanager_thread.rs index 5f9e6654bed8..4bfa44e87365 100644 --- a/components/net/filemanager_thread.rs +++ b/components/net/filemanager_thread.rs @@ -23,7 +23,7 @@ use util::prefs::PREFS; use util::thread::spawn_named; use uuid::Uuid; -/// Trait that provider of file-dialog UI should implement. +/// The provider of file-dialog UI should implement this trait. /// It will be used to initialize a generic FileManager. /// For example, we can choose a dummy UI for testing purpose. pub trait UIProvider where Self: Sync { @@ -82,8 +82,10 @@ struct FileStoreEntry { origin: FileOrigin, /// Backend implementation file_impl: FileImpl, - /// Number of `FileImpl::Sliced` entries in `FileManagerStore` - /// that has a reference (FileID) to this entry + /// Number of FileID holders that the ID is used to + /// index this entry in `FileManagerStore`. + /// Reference holders include a FileStoreEntry or + /// a script-side File-based Blob refs: AtomicUsize, /// UUIDs only become valid blob URIs when explicitly requested /// by the user with createObjectURL. Validity can be revoked as well. @@ -157,8 +159,6 @@ impl FileManager { FileManagerThreadMsg::DecRef(id, origin, sender) => { if let Ok(id) = Uuid::parse_str(&id.0) { spawn_named("dec ref".to_owned(), move || { - // Since it is simple DecRef (possibly caused by close/drop), - // unset_url_validity is false let _ = sender.send(store.dec_ref(&id, &origin)); }) } else { @@ -168,7 +168,6 @@ impl FileManager { FileManagerThreadMsg::RevokeBlobURL(id, origin, sender) => { if let Ok(id) = Uuid::parse_str(&id.0) { spawn_named("revoke blob url".to_owned(), move || { - // Since it is revocation, unset_url_validity is true let _ = sender.send(store.set_blob_url_validity(false, &id, &origin)); }) } else { @@ -487,8 +486,6 @@ impl FileManagerStore { self.remove(id); if let Some(parent_id) = opt_parent_id { - // unset_url_validity for parent is false since we only need - // to unset the initial requesting URL return self.dec_ref(&parent_id, origin_in); } } @@ -505,7 +502,6 @@ impl FileManagerStore { origin: origin.clone(), file_impl: FileImpl::Memory(blob_buf), refs: AtomicUsize::new(1), - // Valid here since PromoteMemory implies URL creation is_valid_url: AtomicBool::new(set_valid), }); diff --git a/components/net_traits/filemanager_thread.rs b/components/net_traits/filemanager_thread.rs index 8ea607f191fc..5068d48ed00f 100644 --- a/components/net_traits/filemanager_thread.rs +++ b/components/net_traits/filemanager_thread.rs @@ -121,17 +121,17 @@ pub struct FilterPattern(pub String); #[derive(Deserialize, Serialize)] pub enum FileManagerThreadMsg { - /// Select a single file, return triple (FileID, FileName, lastModified) + /// Select a single file. Last field is pre-selected file path for testing SelectFile(Vec, IpcSender>, FileOrigin, Option), - /// Select multiple files, return a vector of triples + /// Select multiple files. Last field is pre-selected file paths for testing SelectFiles(Vec, IpcSender>>, FileOrigin, Option>), - /// Read file in chunks by FileID, optionally check URL validity based on fourth flag + /// Read FileID-indexed file in chunks, optionally check URL validity based on boolean flag ReadFile(IpcSender>, SelectedFileId, bool, FileOrigin), /// Add an entry as promoted memory-based blob and send back the associated FileID - /// as part of a valid/invalid Blob URL depending on the second bool flag + /// as part of a valid/invalid Blob URL depending on the boolean flag PromoteMemory(BlobBuf, bool, IpcSender>, FileOrigin), /// Add a sliced entry pointing to the parent FileID, and send back the associated FileID diff --git a/components/script/dom/blob.rs b/components/script/dom/blob.rs index 4711da800108..0cb342cefcbb 100644 --- a/components/script/dom/blob.rs +++ b/components/script/dom/blob.rs @@ -33,17 +33,18 @@ pub struct FileBlob { } -/// Blob backend implementation +/// Different backends of Blob #[must_root] #[derive(JSTraceable)] pub enum BlobImpl { - /// File-based blob + /// File-based blob, whose content lives in the net process File(FileBlob), - /// Memory-based blob + /// Memory-based blob, whose content lives in the script process Memory(Vec), - /// Sliced blob, including parent blob and - /// relative positions representing current slicing range, - /// it is leaf of a two-layer fat tree + /// Sliced blob, including parent blob reference and + /// relative positions of current slicing range, + /// IMPORTANT: The depth of tree is only two, i.e. the parent Blob must be + /// either File-based or Memory-based Sliced(JS, RelativePos), } @@ -71,6 +72,7 @@ pub struct Blob { reflector_: Reflector, #[ignore_heap_size_of = "No clear owner"] blob_impl: DOMRefCell, + /// content-type string typeString: String, isClosed_: Cell, } @@ -181,7 +183,7 @@ impl Blob { /// Promote non-Slice blob: /// 1. Memory-based: The bytes in data slice will be transferred to file manager thread. - /// 2. File-based: Activation + /// 2. File-based: If set_valid, then activate the FileID so it can serve as URL /// Depending on set_valid, the returned FileID can be part of /// valid or invalid Blob URL. fn promote(&self, set_valid: bool) -> SelectedFileId {