Improve File API related comments

This commit is contained in:
Zhen Zhang 2016-08-16 23:53:08 +02:00
parent 49431be44a
commit cd9fc4919d
3 changed files with 18 additions and 20 deletions

View file

@ -23,7 +23,7 @@ use util::prefs::PREFS;
use util::thread::spawn_named; use util::thread::spawn_named;
use uuid::Uuid; 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. /// It will be used to initialize a generic FileManager.
/// For example, we can choose a dummy UI for testing purpose. /// For example, we can choose a dummy UI for testing purpose.
pub trait UIProvider where Self: Sync { pub trait UIProvider where Self: Sync {
@ -82,8 +82,10 @@ struct FileStoreEntry {
origin: FileOrigin, origin: FileOrigin,
/// Backend implementation /// Backend implementation
file_impl: FileImpl, file_impl: FileImpl,
/// Number of `FileImpl::Sliced` entries in `FileManagerStore` /// Number of FileID holders that the ID is used to
/// that has a reference (FileID) to this entry /// index this entry in `FileManagerStore`.
/// Reference holders include a FileStoreEntry or
/// a script-side File-based Blob
refs: AtomicUsize, refs: AtomicUsize,
/// UUIDs only become valid blob URIs when explicitly requested /// UUIDs only become valid blob URIs when explicitly requested
/// by the user with createObjectURL. Validity can be revoked as well. /// by the user with createObjectURL. Validity can be revoked as well.
@ -157,8 +159,6 @@ impl<UI: 'static + UIProvider> FileManager<UI> {
FileManagerThreadMsg::DecRef(id, origin, sender) => { FileManagerThreadMsg::DecRef(id, origin, sender) => {
if let Ok(id) = Uuid::parse_str(&id.0) { if let Ok(id) = Uuid::parse_str(&id.0) {
spawn_named("dec ref".to_owned(), move || { 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)); let _ = sender.send(store.dec_ref(&id, &origin));
}) })
} else { } else {
@ -168,7 +168,6 @@ impl<UI: 'static + UIProvider> FileManager<UI> {
FileManagerThreadMsg::RevokeBlobURL(id, origin, sender) => { FileManagerThreadMsg::RevokeBlobURL(id, origin, sender) => {
if let Ok(id) = Uuid::parse_str(&id.0) { if let Ok(id) = Uuid::parse_str(&id.0) {
spawn_named("revoke blob url".to_owned(), move || { 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)); let _ = sender.send(store.set_blob_url_validity(false, &id, &origin));
}) })
} else { } else {
@ -487,8 +486,6 @@ impl <UI: 'static + UIProvider> FileManagerStore<UI> {
self.remove(id); self.remove(id);
if let Some(parent_id) = opt_parent_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); return self.dec_ref(&parent_id, origin_in);
} }
} }
@ -505,7 +502,6 @@ impl <UI: 'static + UIProvider> FileManagerStore<UI> {
origin: origin.clone(), origin: origin.clone(),
file_impl: FileImpl::Memory(blob_buf), file_impl: FileImpl::Memory(blob_buf),
refs: AtomicUsize::new(1), refs: AtomicUsize::new(1),
// Valid here since PromoteMemory implies URL creation
is_valid_url: AtomicBool::new(set_valid), is_valid_url: AtomicBool::new(set_valid),
}); });

View file

@ -121,17 +121,17 @@ pub struct FilterPattern(pub String);
#[derive(Deserialize, Serialize)] #[derive(Deserialize, Serialize)]
pub enum FileManagerThreadMsg { 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<FilterPattern>, IpcSender<FileManagerResult<SelectedFile>>, FileOrigin, Option<String>), SelectFile(Vec<FilterPattern>, IpcSender<FileManagerResult<SelectedFile>>, FileOrigin, Option<String>),
/// Select multiple files, return a vector of triples /// Select multiple files. Last field is pre-selected file paths for testing
SelectFiles(Vec<FilterPattern>, IpcSender<FileManagerResult<Vec<SelectedFile>>>, FileOrigin, Option<Vec<String>>), SelectFiles(Vec<FilterPattern>, IpcSender<FileManagerResult<Vec<SelectedFile>>>, FileOrigin, Option<Vec<String>>),
/// 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<FileManagerResult<ReadFileProgress>>, SelectedFileId, bool, FileOrigin), ReadFile(IpcSender<FileManagerResult<ReadFileProgress>>, SelectedFileId, bool, FileOrigin),
/// Add an entry as promoted memory-based blob and send back the associated FileID /// 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<Result<SelectedFileId, BlobURLStoreError>>, FileOrigin), PromoteMemory(BlobBuf, bool, IpcSender<Result<SelectedFileId, BlobURLStoreError>>, FileOrigin),
/// Add a sliced entry pointing to the parent FileID, and send back the associated FileID /// Add a sliced entry pointing to the parent FileID, and send back the associated FileID

View file

@ -33,17 +33,18 @@ pub struct FileBlob {
} }
/// Blob backend implementation /// Different backends of Blob
#[must_root] #[must_root]
#[derive(JSTraceable)] #[derive(JSTraceable)]
pub enum BlobImpl { pub enum BlobImpl {
/// File-based blob /// File-based blob, whose content lives in the net process
File(FileBlob), File(FileBlob),
/// Memory-based blob /// Memory-based blob, whose content lives in the script process
Memory(Vec<u8>), Memory(Vec<u8>),
/// Sliced blob, including parent blob and /// Sliced blob, including parent blob reference and
/// relative positions representing current slicing range, /// relative positions of current slicing range,
/// it is leaf of a two-layer fat tree /// IMPORTANT: The depth of tree is only two, i.e. the parent Blob must be
/// either File-based or Memory-based
Sliced(JS<Blob>, RelativePos), Sliced(JS<Blob>, RelativePos),
} }
@ -71,6 +72,7 @@ pub struct Blob {
reflector_: Reflector, reflector_: Reflector,
#[ignore_heap_size_of = "No clear owner"] #[ignore_heap_size_of = "No clear owner"]
blob_impl: DOMRefCell<BlobImpl>, blob_impl: DOMRefCell<BlobImpl>,
/// content-type string
typeString: String, typeString: String,
isClosed_: Cell<bool>, isClosed_: Cell<bool>,
} }
@ -181,7 +183,7 @@ impl Blob {
/// Promote non-Slice blob: /// Promote non-Slice blob:
/// 1. Memory-based: The bytes in data slice will be transferred to file manager thread. /// 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 /// Depending on set_valid, the returned FileID can be part of
/// valid or invalid Blob URL. /// valid or invalid Blob URL.
fn promote(&self, set_valid: bool) -> SelectedFileId { fn promote(&self, set_valid: bool) -> SelectedFileId {