MozillaWiki

JSFileApi: Difference between revisions

Page Discussion

JSFileApi (view source)

Revision as of 14:33, 12 January 2013

249 bytes added ,  12 January 2013
no edit summary
(Renamed modules/constructors)
No edit summary
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page details a proposal for [https://bugzilla.mozilla.org/show_bug.cgi?id=563742 Bug 563742 - Efficient ctypes API for file handling].
This page details a proposal for [https://bugzilla.mozilla.org/show_bug.cgi?id=563742 Bug 563742 - Efficient ctypes API for file handling].
'''Note''' This is an early draft. The final API is documented [https://developer.mozilla.org/en/JavaScript_OS.File on MDN].


The general idea of this API is to provide a low-level, cross-platform, fast access to file management functions. For this reason, it does not implement some primitives that are very different between platforms, e.g. chmod, mmap, epoll.
The general idea of this API is to provide a low-level, cross-platform, fast access to file management functions. For this reason, it does not implement some primitives that are very different between platforms, e.g. chmod, mmap, epoll.


''Conventions'' By the way, this document uses the conventions of [http://code.google.com/closure/compiler/docs/js-for-compiler.html the Google Closure Compiler] for  type annotations.
'''Conventions''' This document uses the conventions of [http://code.google.com/closure/compiler/docs/js-for-compiler.html the Google Closure Compiler] for  type annotations.


= Problems addressed by this API  =
= Problems addressed by this API  =
Line 13: Line 15:
*input/output streams do not play too nicely with JavaScript.
*input/output streams do not play too nicely with JavaScript.


Note: Do we know how expensive the XPCom/XPConnect overhead is, by opposition to js-ctypes and JSAPI?  
'''Note''' Do we know how expensive the XPCom/XPConnect overhead is, by opposition to js-ctypes and JSAPI?  


The present proposal attempts to address these points as follows:
The present proposal attempts to address these points as follows:
Line 19: Line 21:
*it attempts to minimize filename lookups by using file/directory descriptors wherever possible;
*it attempts to minimize filename lookups by using file/directory descriptors wherever possible;
*it attempts to minimize calls to <tt>stat</tt>, in particular when traversing a directory;
*it attempts to minimize calls to <tt>stat</tt>, in particular when traversing a directory;
*input/output attempts to play much more nicely with JavaScript, by using JavaScript low-level data structures designed for this task (and which didn't exist when the nsIFile API was designed).
*input/output attempts to play much more nicely with JavaScript, by using JavaScript low-level data structures designed for this task (and which didn't exist when the <tt>nsIFile</tt> API was designed).


= Problems not addressed by this API =
= Problems not addressed by this API =
Line 28: Line 30:




= Module Files =
= Module <tt>Files</tt> =
This module is the first access point to the file API. It contains constructors, functions to copy, move files, etc. as well as the constants used in the API.
This module is the first access point to the file API. It contains constructors, functions to copy, move files, etc. as well as the constants used in the API.


Line 36: Line 38:
== Access a file or a directory ==
== Access a file or a directory ==
   
   
 
     /**
     /**
       * Create a temporary directory.
       * Create a temporary file in the system-defined temporary directory (if it exists). This file is deleted when the process closes or when the file is closed, whichever happens first.
       *
       *
      * Note: For the time being, there is no guarantee *when* the temporary directory is cleaned
       * @param {string=} name An optional name that can be used for debugging purposes as a template for the name of the file created.
      *
       */
       * @returns {RawDir} a descriptor which may be used to access this directory
     createTempFile: function(name) {
       */  
  //Unix:       uses cached [nsIDirectoryService] to get temporary directoy, [mkstemp] and [this.openFile]
     createTempDirectory: function() {
  //Windows:     uses cached [nsIDirectoryService] to get temporary directory, [GetTempFileName] + [CreateFile] http://msdn.microsoft.com/en-us/library/windows/desktop/aa363875%28v=vs.85%29.aspx
  //Unix:   [Files.tmpdir] followed by [mkdtemp] and [Files.openDirectory]
  //Windows: [Files.tmpdir] followed by [GetTempFileName] and [Files.openDirectory]
     },
     },
 
   
   
== General utilities ==  
== General utilities ==  
Line 192: Line 192:


== Interfaces ==
== Interfaces ==
=== File Information ===
   
   
     /**
     /**
       * The kind of information that can be found by calling [RawFile.info] or [RawDir.forEachFile].
       * The kind of information that can be found by calling [RawFile.info] or [RawDir.contents].
       *
       *
       * Note that some or all fields may be computed lazily.
       * Note that some or all fields may be computed lazily.
Line 227: Line 228:
         }
         }
     },
     },
=== Directory entries ===
    DirEntry: {
        /**
        * The name of the file.
        *
        * Note that there is no guarantee that the file still exists by the time you attempt to open it.
        *
        * @return {string=}
        */
        get name(): { ...
        },
   
   
        /**
        * All the information that could be gathered about the file without opening it.
        *
        * @return {FileInfo}
        */
        get info(): { ...
            //Precomputed by [RawDir.contents]
        }
    },
=== Errors ===
     /**
     /**
       * An exception launched by this module.
       * An exception launched by this module.
Line 238: Line 262:
     Error: function(){}
     Error: function(){}


= Instances of RawFile =  
= Instances of <tt>RawFile</tt> =  


A <tt>RawFile</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows).
A <tt>RawFile</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows).
Line 249: Line 273:
       * @param {ArrayBuffer} buf The buffer which will receive the data.
       * @param {ArrayBuffer} buf The buffer which will receive the data.
       * @param {number} offset The position in the array at which to start putting data, in bytes.
       * @param {number} offset The position in the array at which to start putting data, in bytes.
       * @param {number} size The maximal number of bytes to read. This method can read less bytes if the file is shorter.
       * @param {number} size The maximal number of bytes to read. This method can read less bytes if (and only if) the file is shorter.
       * @return {number} The number of bytes read.
       * @return {number} The number of bytes read.
       * @throws {RawFileException} In case of file error.
       * @throws {RawFileException} In case of file error.
Line 258: Line 282:
  //Windows: [ReadFile]  http://msdn.microsoft.com/en-us/library/windows/desktop/aa365467%28v=VS.85%29.aspx
  //Windows: [ReadFile]  http://msdn.microsoft.com/en-us/library/windows/desktop/aa365467%28v=VS.85%29.aspx
     },
     },
 
     /**
     /**
       * As [read], but read from a given position and do not advance.
       * As [read], but read from a given position and do not advance.
Line 353: Line 377:
  //Windows: [FlushFileBuffers] http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=VS.85).aspx
  //Windows: [FlushFileBuffers] http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=VS.85).aspx
     },
     },
= Instances of RawDir =


A <tt>RawDir</tt> is a slightly higher-level object wrapping a directory _name_ (for reasons of portability & iteration, this seemed more appropriate than _opening_ the directory during construction). On the Unix side, some of the methods rely upon (or have to reimplement) systems that obey recent versions of Posix, with functions such as <tt>openat</tt>.
= Instances of <tt>RawDir</tt> =
 
A <tt>RawDir</tt> is an object wrapping either a directory ''name'' or a directory descriptor, depending on the platform. On the Unix side, some of the methods rely upon (or have to reimplement) systems that obey recent versions of Posix, with functions such as <tt>openat</tt>.


== Opening/creating ==
== Opening/creating ==
Line 378: Line 402:
   
   
     /**
     /**
       * Create a temporary file in this directory. This file is deleted when the process closes, when the file is closed.
       * Create a temporary file in this directory. This file is deleted when the process closes or when the file is closed, whichever happens first.
       */
       */
     createTempFile: function() {
     createTempFile: function() {
Line 399: Line 423:
   
   
     /**
     /**
       * Create a temporary directory.
       * Create a temporary subdirectory.
       *
       *
       * Note: For the time being, there is no guarantee that the temporary directory will be cleaned
       * Note: For the time being, there is no guarantee that the temporary directory will be cleaned
Line 421: Line 445:


== Browsing contents ==
== Browsing contents ==
This API provides three ways of browsing contents:
* using the directory as an iterator;
* using the more powerful function [forEachMap], which also provides fast filtering on platforms where it is possible.
   
   
     /**
     /**
       * Apply a treatment to all files in the directory.
       * Get the contents of the directory.
      *
      * Note: objects of type RawDir are iterable. Therefore, you can also loop through them using a standard [for..in].
       *
       *
       * @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available.
       * @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available.
       * @param {function(string, RawFile.FileInfo, number, function() RawFile)} onFile  A function called for each file in the directory, with the name of the file, a (lazy) file info for that file and a file number. If the function returns anything [null], the loop stops immediately and returns the value returned by that function.
       * @return {Array.<Files.DirEntry>} The list of files of the directory that match the filter.
      *
      * @returns The first value returned by [onFile], or [undefined] otherwise.
       */
       */
     forEachFile: function(filter, onFile) {
     contents: function(filter) {    
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat], lazy calls to [openat]/[open], [closedir]
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat], lazy calls to [openat]/[open], [closedir]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
Yoric
184

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/356788...499247"