JavaScript OS.File

  • Revision slug: JavaScript_OS.File
  • Revision title: JavaScript OS.File
  • Revision id: 320561
  • Created:
  • Creator: Yoric
  • Is current revision? No
  • Comment

Revision Content

JavaScript module OS.File contains primitives for manipulating files. In time, this module is intended to replace most uses of nsIFile, NetUtil.jsm, FileUtils.jsm and nsIIOService for file access.

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 operatin is called on the main thread, this means that the whole user experience is stuck for several seconds, which is quite bad.
What 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

Calling OS.File from the main thread (TBD)
Asynchronous, off-main thread file I/O, main thread API.
Calling OS.File.DirectoryIterator from the main thread (TBD)
Asynchronous, off-main thread file directory access, main thread API.

... from a worker thread

OS.File for workers
Synchronous file I/O for worker threads
OS.File.DirectoryIterator for workers (TBD)
Visiting directories synchronously from a worker thread

... shared components

OS.File.Error
Representation of file-related errors
OS.File.Info (TBD)
Representation of file information (size, creation date, etc.)

Revision Source

<p>JavaScript module <code>OS.File</code> contains primitives for manipulating files. In time, this module is intended to replace most uses of <a href="/en/XPCOM_Interface_Reference/nsIFile" title="en/nsIFile">nsIFile</a>, <a href="/en/JavaScript_code_modules/NetUtils.jsm" title="en/JavaScript_code_modules/NetUtils.jsm">NetUtil.jsm</a>, <a href="/en/JavaScript_code_modules/FileUtils.jsm" title="en/JavaScript_code_modules/FileUtils.jsm">FileUtils.jsm</a> and <a href="/en/XPCOM_Interface_Reference/nsIIOService" title="en/XPCOM_Interface_Reference/nsIIOService">nsIIOService</a> for file access.</p>
<h2 id="F.A.Q.">F.A.Q.</h2>
<dl>
  <dt>
    What is OS.File?</dt>
  <dd>
    OS.File is a new API designed for <em>efficient</em>, <em>off-main thread</em>, manipulation of files by <em>privileged JavaScript </em>code. This API is intended to replace, in time, most XPCOM-based manipulation of files (nsIFile, subsets of nsIIOService, etc.) by JavaScript code.</dd>
  <dt>
    What are the relationships with the HTML5 File API?</dt>
  <dd>
    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.</dd>
  <dt>
    Why is Off Main Thread File I/O important?</dt>
  <dd>
    One thing that all developers need to remember is that the duration of a File I/O operation is <em>unbounded</em>. 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 <strong>several seconds</strong> to execute operations that look trivial, such as closing a file, or checking when it was last modified.<br />
    If the operatin is called on the main thread, this means that the whole user experience is stuck for several seconds, which is quite bad.</dd>
  <dt>
    What is I/O Efficiency important?</dt>
  <dd>
    I/O efficiency is all about <em>minimizing the number of actual I/O calls</em>. 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 <em>wasting I/O is wasting battery</em>.
    <p style="text-align:justify;">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.</p>
  </dd>
</dl>
<h2 id="How_can_I_use_OS.File_in_my_code.3F">Using OS.File</h2>
<h3>... from the main thread</h3>
<dl>
  <dt>
    Calling OS.File from the main thread (TBD)</dt>
  <dd>
    Asynchronous, off-main thread file I/O, main thread API.</dd>
  <dt>
    Calling OS.File.DirectoryIterator from the main thread (TBD)</dt>
  <dd>
    Asynchronous, off-main thread file directory access, main thread API.</dd>
</dl>
<h3>... from a worker thread</h3>
<dl>
  <dt>
    <a href="/en-US/docs/JavaScript_OS.File/OS.File_for_workers" title="/en-US/docs/JavaScript_OS.File/OS.File_for_workers">OS.File for workers</a></dt>
  <dd>
    Synchronous file I/O for worker threads</dd>
  <dt>
    OS.File.DirectoryIterator for workers (TBD)</dt>
  <dd>
    Visiting directories synchronously from a worker thread</dd>
</dl>
<h3>... shared components</h3>
<dl>
  <dt>
    <a href="/en-US/docs/JavaScript_OS.File/OS.File.Error" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    Representation of file-related errors</dd>
  <dt>
    OS.File.Info (TBD)</dt>
  <dd>
    Representation of file information (size, creation date, etc.)</dd>
</dl>
Revert to this revision