JavaScript module OS.File contains primitives for manipulating files out of the main thread.
F.A.Q.
- What is OS.File?
- OS.File is a new API designed for efficient, off-main thread, manipulation of files by privileged JavaScript code. This API is intended to replace, in time, most XPCOM-based manipulation of files (nsIFile, subsets of nsIIOService, etc.) by JavaScript code.
- What are the relationships with the HTML5 File API?
- None, really. The File API is designed for high-level, highly-restricted manipulation of files by web applications. OS.File is designed for efficient, unrestricted, manipulation of files by Firefox itself and by add-ons.
- Why is Off Main Thread File I/O important?
- One thing that all developers need to remember is that the duration of a File I/O operation is unbounded. Depending on the current load of the kernel, the current disk activity, the current load of the bus, the current rotation speed of the disk, the amount of battery power, etc. operations can take an arbitrary amount of time. We are talking about several seconds to execute operations that look trivial, such as closing a file, or checking when it was last modified.
If the operation is called on the main thread, this means that the whole user experience is stuck for several seconds, which is quite bad. - Why is I/O Efficiency important?
- I/O efficiency is all about minimizing the number of actual I/O calls. This is critical because some platforms have extremely slow storage (e.g. smartphones, tablets) and because, regardless of the platforms, doing too much I/O penalizes not just your application but potentially all the applications running on the system, which is quite bad for the user experience. Finally, I/O is often expensive in terms of energy, so wasting I/O is wasting battery.
Consequently, one of the key design choices of OS.File is to provide operations that are low-level enough that they do not hide any I/O from the developer (which could cause the developer to perform more I/O than they think) and, since not all platforms have the same features, offer system-specific information that the developer can use to optimize his algorithms for a platform.
Using OS.File
... from the main thread
Most uses of OS.File are from the main thread. In this mode, main thread clients use the API to request off main thread file I/O.
- Calling OS.File from the main thread
- Asynchronous, off-main thread file I/O, main thread API.
- Calling OS.File.DirectoryIterator from the main thread
- Asynchronous, off-main thread file directory access, main thread API.
... from a worker thread
In some cases, the main thread API for OS.File is not appropriate as it would require too much message passing, or because the code that requires file I/O is already executed on a worker thread. For this reason, API clients can also spawn their own worker threads and make use of OS.File directly from these threads.
- OS.File for workers
- Synchronous file I/O for worker threads
- OS.File.DirectoryIterator for workers
- Visiting directories synchronously from a worker thread
... shared components
- OS.Path and OS.Constants.Path
- Manipulation of paths
- OS.File.Error
- Representation of file-related errors
- OS.File.Info
- Representation of file information (size, creation date, etc.)
- OS.File.DirectoryIterator.Entry
- File information obtained while visiting a directory