The Tor Browser: comparison toolkit/components/osfile/modules/osfile_shared

--1:000000000000
+:93c9d21a6c10
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this file,
+* You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+/**
+* OS.File utilities used by all threads.
+*
+* This module defines:
+* - logging;
+* - the base constants;
+* - base types and primitives for declaring new types;
+* - primitives for importing C functions;
+* - primitives for dealing with integers, pointers, typed arrays;
+* - the base class OSError;
+* - a few additional utilities.
+*/
+// Boilerplate used to be able to import this module both from the main
+// thread and from worker threads.
+if (typeof Components != "undefined") {
+// Global definition of |exports|, to keep everybody happy.
+// In non-main thread, |exports| is provided by the module
+// loader.
+this.exports = {};
+const Cu = Components.utils;
+const Ci = Components.interfaces;
+const Cc = Components.classes;
+Cu.import("resource://gre/modules/Services.jsm", this);
+}
+let EXPORTED_SYMBOLS = [
+"LOG",
+"clone",
+"Config",
+"Constants",
+"Type",
+"HollowStructure",
+"OSError",
+"Library",
+"declareFFI",
+"declareLazy",
+"declareLazyFFI",
+"normalizeToPointer",
+"projectValue",
+"isTypedArray",
+"defineLazyGetter",
+"offsetBy",
+"OS" // Warning: this exported symbol will disappear
+];
+////////////////////// Configuration of OS.File
+let Config = {
+/**
+* If |true|, calls to |LOG| are shown. Otherwise, they are hidden.
+*
+* This configuration option is controlled by preference "toolkit.osfile.log".
+*/
+DEBUG: false,
+/**
+* TEST
+*/
+TEST: false
+};
+exports.Config = Config;
+////////////////////// OS Constants
+if (typeof Components != "undefined") {
+// On the main thread, OS.Constants is defined by a xpcom
+// component. On other threads, it is available automatically
+Cu.import("resource://gre/modules/ctypes.jsm");
+Cc["@mozilla.org/net/osfileconstantsservice;1"].
+getService(Ci.nsIOSFileConstantsService).init();
+}
+exports.Constants = OS.Constants;
+///////////////////// Utilities
+// Define a lazy getter for a property
+let defineLazyGetter = function defineLazyGetter(object, name, getter) {
+Object.defineProperty(object, name, {
+configurable: true,
+get: function lazy() {
+delete this[name];
+let value = getter.call(this);
+Object.defineProperty(object, name, {
+value: value
+});
+return value;
+}
+});
+};
+exports.defineLazyGetter = defineLazyGetter;
+///////////////////// Logging
+/**
+* The default implementation of the logger.
+*
+* The choice of logger can be overridden with Config.TEST.
+*/
+let gLogger;
+if (typeof window != "undefined" && window.console && console.log) {
+gLogger = console.log.bind(console, "OS");
+} else {
+gLogger = function(...args) {
+dump("OS " + args.join(" ") + "\n");
+};
+}
+/**
+* Attempt to stringify an argument into something useful for
+* debugging purposes, by using |.toString()| or |JSON.stringify|
+* if available.
+*
+* @param {*} arg An argument to be stringified if possible.
+* @return {string} A stringified version of |arg|.
+*/
+let stringifyArg = function stringifyArg(arg) {
+if (typeof arg === "string") {
+return arg;
+}
+if (arg && typeof arg === "object") {
+let argToString = "" + arg;
+/**
+* The only way to detect whether this object has a non-default
+* implementation of |toString| is to check whether it returns
+* '[object Object]'. Unfortunately, we cannot simply compare |arg.toString|
+* and |Object.prototype.toString| as |arg| typically comes from another
+* compartment.
+*/
+if (argToString === "[object Object]") {
+return JSON.stringify(arg);
+} else {
+return argToString;
+}
+}
+return arg;
+};
+let LOG = function (...args) {
+if (!Config.DEBUG) {
+// If logging is deactivated, don't log
+return;
+}
+let logFunc = gLogger;
+if (Config.TEST && typeof Components != "undefined") {
+// If _TESTING_LOGGING is set, and if we are on the main thread,
+// redirect logs to Services.console, for testing purposes
+logFunc = function logFunc(...args) {
+let message = ["TEST", "OS"].concat(args).join(" ");
+Services.console.logStringMessage(message + "\n");
+};
+}
+logFunc.apply(null, [stringifyArg(arg) for (arg of args)]);
+};
+exports.LOG = LOG;
+/**
+* Return a shallow clone of the enumerable properties of an object.
+*
+* Utility used whenever normalizing options requires making (shallow)
+* changes to an option object. The copy ensures that we do not modify
+* a client-provided object by accident.
+*
+* Note: to reference and not copy specific fields, provide an optional
+* |refs| argument containing their names.
+*
+* @param {JSON} object Options to be cloned.
+* @param {Array} refs An optional array of field names to be passed by
+* reference instead of copying.
+*/
+let clone = function (object, refs = []) {
+let result = {};
+// Make a reference between result[key] and object[key].
+let refer = function refer(result, key, object) {
+Object.defineProperty(result, key, {
+enumerable: true,
+get: function() {
+return object[key];
+},
+set: function(value) {
+object[key] = value;
+}
+});
+};
+for (let k in object) {
+if (refs.indexOf(k) < 0) {
+result[k] = object[k];
+} else {
+refer(result, k, object);
+}
+}
+return result;
+};
+exports.clone = clone;
+///////////////////// Abstractions above js-ctypes
+/**
+* Abstraction above js-ctypes types.
+*
+* Use values of this type to register FFI functions. In addition to the
+* usual features of js-ctypes, values of this type perform the necessary
+* transformations to ensure that C errors are handled nicely, to connect
+* resources with their finalizer, etc.
+*
+* @param {string} name The name of the type. Must be unique.
+* @param {CType} implementation The js-ctypes implementation of the type.
+*
+* @constructor
+*/
+function Type(name, implementation) {
+if (!(typeof name == "string")) {
+throw new TypeError("Type expects as first argument a name, got: "
++ name);
+}
+if (!(implementation instanceof ctypes.CType)) {
+throw new TypeError("Type expects as second argument a ctypes.CType"+
+", got: " + implementation);
+}
+Object.defineProperty(this, "name", { value: name });
+Object.defineProperty(this, "implementation", { value: implementation });
+}
+Type.prototype = {
+/**
+* Serialize a value of |this| |Type| into a format that can
+* be transmitted as a message (not necessarily a string).
+*
+* In the default implementation, the method returns the
+* value unchanged.
+*/
+toMsg: function default_toMsg(value) {
+return value;
+},
+/**
+* Deserialize a message to a value of |this| |Type|.
+*
+* In the default implementation, the method returns the
+* message unchanged.
+*/
+fromMsg: function default_fromMsg(msg) {
+return msg;
+},
+/**
+* Import a value from C.
+*
+* In this default implementation, return the value
+* unchanged.
+*/
+importFromC: function default_importFromC(value) {
+return value;
+},
+/**
+* A pointer/array used to pass data to the foreign function.
+*/
+get in_ptr() {
+delete this.in_ptr;
+let ptr_t = new PtrType(
+"[in] " + this.name + "*",
+this.implementation.ptr,
+this);
+Object.defineProperty(this, "in_ptr",
+{
+get: function() {
+return ptr_t;
+}
+});
+return ptr_t;
+},
+/**
+* A pointer/array used to receive data from the foreign function.
+*/
+get out_ptr() {
+delete this.out_ptr;
+let ptr_t = new PtrType(
+"[out] " + this.name + "*",
+this.implementation.ptr,
+this);
+Object.defineProperty(this, "out_ptr",
+{
+get: function() {
+return ptr_t;
+}
+});
+return ptr_t;
+},
+/**
+* A pointer/array used to both pass data to the foreign function
+* and receive data from the foreign function.
+*
+* Whenever possible, prefer using |in_ptr| or |out_ptr|, which
+* are generally faster.
+*/
+get inout_ptr() {
+delete this.inout_ptr;
+let ptr_t = new PtrType(
+"[inout] " + this.name + "*",
+this.implementation.ptr,
+this);
+Object.defineProperty(this, "inout_ptr",
+{
+get: function() {
+return ptr_t;
+}
+});
+return ptr_t;
+},
+/**
+* Attach a finalizer to a type.
+*/
+releaseWith: function releaseWith(finalizer) {
+let parent = this;
+let type = this.withName("[auto " + this.name + ", " + finalizer + "] ");
+type.importFromC = function importFromC(value, operation) {
+return ctypes.CDataFinalizer(
+parent.importFromC(value, operation),
+finalizer);
+};
+return type;
+},
+/**
+* Lazy variant of releaseWith.
+* Attach a finalizer lazily to a type.
+*
+* @param {function} getFinalizer The function that
+* returns finalizer lazily.
+*/
+releaseWithLazy: function releaseWithLazy(getFinalizer) {
+let parent = this;
+let type = this.withName("[auto " + this.name + ", (lazy)] ");
+type.importFromC = function importFromC(value, operation) {
+return ctypes.CDataFinalizer(
+parent.importFromC(value, operation),
+getFinalizer());
+};
+return type;
+},
+/**
+* Return an alias to a type with a different name.
+*/
+withName: function withName(name) {
+return Object.create(this, {name: {value: name}});
+},
+/**
+* Cast a C value to |this| type.
+*
+* Throw an error if the value cannot be casted.
+*/
+cast: function cast(value) {
+return ctypes.cast(value, this.implementation);
+},
+/**
+* Return the number of bytes in a value of |this| type.
+*
+* This may not be defined, e.g. for |void_t|, array types
+* without length, etc.
+*/
+get size() {
+return this.implementation.size;
+}
+};
+/**
+* Utility function used to determine whether an object is a typed array
+*/
+let isTypedArray = function isTypedArray(obj) {
+return typeof obj == "object"
+&& "byteOffset" in obj;
+};
+exports.isTypedArray = isTypedArray;
+/**
+* A |Type| of pointers.
+*
+* @param {string} name The name of this type.
+* @param {CType} implementation The type of this pointer.
+* @param {Type} targetType The target type.
+*/
+function PtrType(name, implementation, targetType) {
+Type.call(this, name, implementation);
+if (targetType == null || !targetType instanceof Type) {
+throw new TypeError("targetType must be an instance of Type");
+}
+/**
+* The type of values targeted by this pointer type.
+*/
+Object.defineProperty(this, "targetType", {
+value: targetType
+});
+}
+PtrType.prototype = Object.create(Type.prototype);
+/**
+* Convert a value to a pointer.
+*
+* Protocol:
+* - |null| returns |null|
+* - a string returns |{string: value}|
+* - a typed array returns |{ptr: address_of_buffer}|
+* - a C array returns |{ptr: address_of_buffer}|
+* everything else raises an error
+*/
+PtrType.prototype.toMsg = function ptr_toMsg(value) {
+if (value == null) {
+return null;
+}
+if (typeof value == "string") {
+return { string: value };
+}
+let normalized;
+if (isTypedArray(value)) { // Typed array
+normalized = Type.uint8_t.in_ptr.implementation(value.buffer);
+if (value.byteOffset != 0) {
+normalized = offsetBy(normalized, value.byteOffset);
+}
+} else if ("addressOfElement" in value) { // C array
+normalized = value.addressOfElement(0);
+} else if ("isNull" in value) { // C pointer
+normalized = value;
+} else {
+throw new TypeError("Value " + value +
+" cannot be converted to a pointer");
+}
+let cast = Type.uintptr_t.cast(normalized);
+return {ptr: cast.value.toString()};
+};
+/**
+* Convert a message back to a pointer.
+*/
+PtrType.prototype.fromMsg = function ptr_fromMsg(msg) {
+if (msg == null) {
+return null;
+}
+if ("string" in msg) {
+return msg.string;
+}
+if ("ptr" in msg) {
+let address = ctypes.uintptr_t(msg.ptr);
+return this.cast(address);
+}
+throw new TypeError("Message " + msg.toSource() +
+" does not represent a pointer");
+};
+exports.Type = Type;
+/*
+* Some values are large integers on 64 bit platforms. Unfortunately,
+* in practice, 64 bit integers cannot be manipulated in JS. We
+* therefore project them to regular numbers whenever possible.
+*/
+let projectLargeInt = function projectLargeInt(x) {
+let str = x.toString();
+let rv = parseInt(str, 10);
+if (rv.toString() !== str) {
+throw new TypeError("Number " + str + " cannot be projected to a double");
+}
+return rv;
+};
+let projectLargeUInt = function projectLargeUInt(x) {
+return projectLargeInt(x);
+};
+let projectValue = function projectValue(x) {
+if (!(x instanceof ctypes.CData)) {
+return x;
+}
+if (!("value" in x)) { // Sanity check
+throw new TypeError("Number " + x.toSource() + " has no field |value|");
+}
+return x.value;
+};
+function projector(type, signed) {
+LOG("Determining best projection for", type,
+"(size: ", type.size, ")", signed?"signed":"unsigned");
+if (type instanceof Type) {
+type = type.implementation;
+}
+if (!type.size) {
+throw new TypeError("Argument is not a proper C type");
+}
+// Determine if type is projected to Int64/Uint64
+if (type.size == 8           // Usual case
+// The following cases have special treatment in js-ctypes
+// Regardless of their size, the value getter returns
+// a Int64/Uint64
+|| type == ctypes.size_t // Special cases
+|| type == ctypes.ssize_t
+|| type == ctypes.intptr_t
+|| type == ctypes.uintptr_t
+|| type == ctypes.off_t) {
+if (signed) {
+LOG("Projected as a large signed integer");
+return projectLargeInt;
+} else {
+LOG("Projected as a large unsigned integer");
+return projectLargeUInt;
+}
+}
+LOG("Projected as a regular number");
+return projectValue;
+};
+exports.projectValue = projectValue;
+/**
+* Get the appropriate type for an unsigned int of the given size.
+*
+* This function is useful to define types such as |mode_t| whose
+* actual width depends on the OS/platform.
+*
+* @param {number} size The number of bytes requested.
+*/
+Type.uintn_t = function uintn_t(size) {
+switch (size) {
+case 1: return Type.uint8_t;
+case 2: return Type.uint16_t;
+case 4: return Type.uint32_t;
+case 8: return Type.uint64_t;
+default:
+throw new Error("Cannot represent unsigned integers of " + size + " bytes");
+}
+};
+/**
+* Get the appropriate type for an signed int of the given size.
+*
+* This function is useful to define types such as |mode_t| whose
+* actual width depends on the OS/platform.
+*
+* @param {number} size The number of bytes requested.
+*/
+Type.intn_t = function intn_t(size) {
+switch (size) {
+case 1: return Type.int8_t;
+case 2: return Type.int16_t;
+case 4: return Type.int32_t;
+case 8: return Type.int64_t;
+default:
+throw new Error("Cannot represent integers of " + size + " bytes");
+}
+};
+/**
+* Actual implementation of common C types.
+*/
+/**
+* The void value.
+*/
+Type.void_t =
+new Type("void",
+ctypes.void_t);
+/**
+* Shortcut for |void*|.
+*/
+Type.voidptr_t =
+new PtrType("void*",
+ctypes.voidptr_t,
+Type.void_t);
+// void* is a special case as we can cast any pointer to/from it
+// so we have to shortcut |in_ptr|/|out_ptr|/|inout_ptr| and
+// ensure that js-ctypes' casting mechanism is invoked directly
+["in_ptr", "out_ptr", "inout_ptr"].forEach(function(key) {
+Object.defineProperty(Type.void_t, key,
+{
+value: Type.voidptr_t
+});
+});
+/**
+* A Type of integers.
+*
+* @param {string} name The name of this type.
+* @param {CType} implementation The underlying js-ctypes implementation.
+* @param {bool} signed |true| if this is a type of signed integers,
+* |false| otherwise.
+*
+* @constructor
+*/
+function IntType(name, implementation, signed) {
+Type.call(this, name, implementation);
+this.importFromC = projector(implementation, signed);
+this.project = this.importFromC;
+};
+IntType.prototype = Object.create(Type.prototype);
+IntType.prototype.toMsg = function toMsg(value) {
+if (typeof value == "number") {
+return value;
+}
+return this.project(value);
+};
+/**
+* A C char (one byte)
+*/
+Type.char =
+new Type("char",
+ctypes.char);
+/**
+* A C wide char (two bytes)
+*/
+Type.jschar =
+new Type("jschar",
+ctypes.jschar);
+/**
+* Base string types.
+*/
+Type.cstring = Type.char.in_ptr.withName("[in] C string");
+Type.wstring = Type.jschar.in_ptr.withName("[in] wide string");
+Type.out_cstring = Type.char.out_ptr.withName("[out] C string");
+Type.out_wstring = Type.jschar.out_ptr.withName("[out] wide string");
+/**
+* A C integer (8-bits).
+*/
+Type.int8_t =
+new IntType("int8_t", ctypes.int8_t, true);
+Type.uint8_t =
+new IntType("uint8_t", ctypes.uint8_t, false);
+/**
+* A C integer (16-bits).
+*
+* Also known as WORD under Windows.
+*/
+Type.int16_t =
+new IntType("int16_t", ctypes.int16_t, true);
+Type.uint16_t =
+new IntType("uint16_t", ctypes.uint16_t, false);
+/**
+* A C integer (32-bits).
+*
+* Also known as DWORD under Windows.
+*/
+Type.int32_t =
+new IntType("int32_t", ctypes.int32_t, true);
+Type.uint32_t =
+new IntType("uint32_t", ctypes.uint32_t, false);
+/**
+* A C integer (64-bits).
+*/
+Type.int64_t =
+new IntType("int64_t", ctypes.int64_t, true);
+Type.uint64_t =
+new IntType("uint64_t", ctypes.uint64_t, false);
+/**
+* A C integer
+*
+* Size depends on the platform.
+*/
+Type.int = Type.intn_t(ctypes.int.size).
+withName("int");
+Type.unsigned_int = Type.intn_t(ctypes.unsigned_int.size).
+withName("unsigned int");
+/**
+* A C long integer.
+*
+* Size depends on the platform.
+*/
+Type.long =
+Type.intn_t(ctypes.long.size).withName("long");
+Type.unsigned_long =
+Type.intn_t(ctypes.unsigned_long.size).withName("unsigned long");
+/**
+* An unsigned integer with the same size as a pointer.
+*
+* Used to cast a pointer to an integer, whenever necessary.
+*/
+Type.uintptr_t =
+Type.uintn_t(ctypes.uintptr_t.size).withName("uintptr_t");
+/**
+* A boolean.
+* Implemented as a C integer.
+*/
+Type.bool = Type.int.withName("bool");
+Type.bool.importFromC = function projectBool(x) {
+return !!(x.value);
+};
+/**
+* A user identifier.
+*
+* Implemented as a C integer.
+*/
+Type.uid_t =
+Type.int.withName("uid_t");
+/**
+* A group identifier.
+*
+* Implemented as a C integer.
+*/
+Type.gid_t =
+Type.int.withName("gid_t");
+/**
+* An offset (positive or negative).
+*
+* Implemented as a C integer.
+*/
+Type.off_t =
+new IntType("off_t", ctypes.off_t, true);
+/**
+* A size (positive).
+*
+* Implemented as a C size_t.
+*/
+Type.size_t =
+new IntType("size_t", ctypes.size_t, false);
+/**
+* An offset (positive or negative).
+* Implemented as a C integer.
+*/
+Type.ssize_t =
+new IntType("ssize_t", ctypes.ssize_t, true);
+/**
+* Encoding/decoding strings
+*/
+Type.uencoder =
+new Type("uencoder", ctypes.StructType("uencoder"));
+Type.udecoder =
+new Type("udecoder", ctypes.StructType("udecoder"));
+/**
+* Utility class, used to build a |struct| type
+* from a set of field names, types and offsets.
+*
+* @param {string} name The name of the |struct| type.
+* @param {number} size The total size of the |struct| type in bytes.
+*/
+function HollowStructure(name, size) {
+if (!name) {
+throw new TypeError("HollowStructure expects a name");
+}
+if (!size || size < 0) {
+throw new TypeError("HollowStructure expects a (positive) size");
+}
+// A mapping from offsets in the struct to name/type pairs
+// (or nothing if no field starts at that offset).
+this.offset_to_field_info = [];
+// The name of the struct
+this.name = name;
+// The size of the struct, in bytes
+this.size = size;
+// The number of paddings inserted so far.
+// Used to give distinct names to padding fields.
+this._paddings = 0;
+}
+HollowStructure.prototype = {
+/**
+* Add a field at a given offset.
+*
+* @param {number} offset The offset at which to insert the field.
+* @param {string} name The name of the field.
+* @param {CType|Type} type The type of the field.
+*/
+add_field_at: function add_field_at(offset, name, type) {
+if (offset == null) {
+throw new TypeError("add_field_at requires a non-null offset");
+}
+if (!name) {
+throw new TypeError("add_field_at requires a non-null name");
+}
+if (!type) {
+throw new TypeError("add_field_at requires a non-null type");
+}
+if (type instanceof Type) {
+type = type.implementation;
+}
+if (this.offset_to_field_info[offset]) {
+throw new Error("HollowStructure " + this.name +
+" already has a field at offset " + offset);
+}
+if (offset + type.size > this.size) {
+throw new Error("HollowStructure " + this.name +
+" cannot place a value of type " + type +
+" at offset " + offset +
+" without exceeding its size of " + this.size);
+}
+let field = {name: name, type:type};
+this.offset_to_field_info[offset] = field;
+},
+/**
+* Create a pseudo-field that will only serve as padding.
+*
+* @param {number} size The number of bytes in the field.
+* @return {Object} An association field-name => field-type,
+* as expected by |ctypes.StructType|.
+*/
+_makePaddingField: function makePaddingField(size) {
+let field = ({});
+field["padding_" + this._paddings] =
+ctypes.ArrayType(ctypes.uint8_t, size);
+this._paddings++;
+return field;
+},
+/**
+* Convert this |HollowStructure| into a |Type|.
+*/
+getType: function getType() {
+// Contents of the structure, in the format expected
+// by ctypes.StructType.
+let struct = [];
+let i = 0;
+while (i < this.size) {
+let currentField = this.offset_to_field_info[i];
+if (!currentField) {
+// No field was specified at this offset, we need to
+// introduce some padding.
+// Firstly, determine how many bytes of padding
+let padding_length = 1;
+while (i + padding_length < this.size
+&& !this.offset_to_field_info[i + padding_length]) {
+++padding_length;
+}
+// Then add the padding
+struct.push(this._makePaddingField(padding_length));
+// And proceed
+i += padding_length;
+} else {
+// We have a field at this offset.
+// Firstly, ensure that we do not have two overlapping fields
+for (let j = 1; j < currentField.type.size; ++j) {
+let candidateField = this.offset_to_field_info[i + j];
+if (candidateField) {
+throw new Error("Fields " + currentField.name +
+" and " + candidateField.name +
+" overlap at position " + (i + j));
+}
+}
+// Then add the field
+let field = ({});
+field[currentField.name] = currentField.type;
+struct.push(field);
+// And proceed
+i += currentField.type.size;
+}
+}
+let result = new Type(this.name, ctypes.StructType(this.name, struct));
+if (result.implementation.size != this.size) {
+throw new Error("Wrong size for type " + this.name +
+": expected " + this.size +
+", found " + result.implementation.size +
+" (" + result.implementation.toSource() + ")");
+}
+return result;
+}
+};
+exports.HollowStructure = HollowStructure;
+/**
+* Representation of a native library.
+*
+* The native library is opened lazily, during the first call to its
+* field |library| or whenever accessing one of the methods imported
+* with declareLazyFFI.
+*
+* @param {string} name A human-readable name for the library. Used
+* for debugging and error reporting.
+* @param {string...} candidates A list of system libraries that may
+* represent this library. Used e.g. to try different library names
+* on distinct operating systems ("libxul", "XUL", etc.).
+*
+* @constructor
+*/
+function Library(name, ...candidates) {
+this.name = name;
+this._candidates = candidates;
+};
+Library.prototype = Object.freeze({
+/**
+* The native library as a js-ctypes object.
+*
+* @throws {Error} If none of the candidate libraries could be opened.
+*/
+get library() {
+let library;
+delete this.library;
+for (let candidate of this._candidates) {
+try {
+library = ctypes.open(candidate);
+break;
+} catch (ex) {
+LOG("Could not open library", candidate, ex);
+}
+}
+this._candidates = null;
+if (library) {
+Object.defineProperty(this, "library", {
+value: library
+});
+Object.freeze(this);
+return library;
+}
+let error = new Error("Could not open library " + this.name);
+Object.defineProperty(this, "library", {
+get: function() {
+throw error;
+}
+});
+Object.freeze(this);
+throw error;
+},
+/**
+* Declare a function, lazily.
+*
+* @param {object} The object containing the function as a field.
+* @param {string} The name of the field containing the function.
+* @param {string} symbol The name of the function, as defined in the
+* library.
+* @param {ctypes.abi} abi The abi to use, or |null| for default.
+* @param {Type} returnType The type of values returned by the function.
+* @param {...Type} argTypes The type of arguments to the function.
+*/
+declareLazyFFI: function(object, field, ...args) {
+let lib = this;
+Object.defineProperty(object, field, {
+get: function() {
+delete this[field];
+let ffi = declareFFI(lib.library, ...args);
+if (ffi) {
+return this[field] = ffi;
+}
+return undefined;
+},
+configurable: true,
+enumerable: true
+});
+},
+/**
+* Define a js-ctypes function lazily using ctypes method declare.
+*
+* @param {object} The object containing the function as a field.
+* @param {string} The name of the field containing the function.
+* @param {string} symbol The name of the function, as defined in the
+* library.
+* @param {ctypes.abi} abi The abi to use, or |null| for default.
+* @param {ctypes.CType} returnType The type of values returned by the function.
+* @param {...ctypes.CType} argTypes The type of arguments to the function.
+*/
+declareLazy: function(object, field, ...args) {
+let lib = this;
+Object.defineProperty(object, field, {
+get: function() {
+delete this[field];
+let ffi = lib.library.declare(...args);
+if (ffi) {
+return this[field] = ffi;
+}
+return undefined;
+},
+configurable: true,
+enumerable: true
+});
+},
+toString: function() {
+return "[Library " + this.name + "]";
+}
+});
+exports.Library = Library;
+/**
+* Declare a function through js-ctypes
+*
+* @param {ctypes.library} lib The ctypes library holding the function.
+* @param {string} symbol The name of the function, as defined in the
+* library.
+* @param {ctypes.abi} abi The abi to use, or |null| for default.
+* @param {Type} returnType The type of values returned by the function.
+* @param {...Type} argTypes The type of arguments to the function.
+*
+* @return null if the function could not be defined (generally because
+* it does not exist), or a JavaScript wrapper performing the call to C
+* and any type conversion required.
+*/
+let declareFFI = function declareFFI(lib, symbol, abi,
+returnType /*, argTypes ...*/) {
+LOG("Attempting to declare FFI ", symbol);
+// We guard agressively, to avoid any late surprise
+if (typeof symbol != "string") {
+throw new TypeError("declareFFI expects as first argument a string");
+}
+abi = abi || ctypes.default_abi;
+if (Object.prototype.toString.call(abi) != "[object CABI]") {
+// Note: This is the only known manner of checking whether an object
+// is an abi.
+throw new TypeError("declareFFI expects as second argument an abi or null");
+}
+if (!returnType.importFromC) {
+throw new TypeError("declareFFI expects as third argument an instance of Type");
+}
+let signature = [symbol, abi];
+let argtypes  = [];
+for (let i = 3; i < arguments.length; ++i) {
+let current = arguments[i];
+if (!current) {
+throw new TypeError("Missing type for argument " + ( i - 3 ) +
+" of symbol " + symbol);
+}
+if (!current.implementation) {
+throw new TypeError("Missing implementation for argument " + (i - 3)
++ " of symbol " + symbol
++ " ( " + current.name + " )" );
+}
+signature.push(current.implementation);
+}
+try {
+let fun = lib.declare.apply(lib, signature);
+let result = function ffi(...args) {
+for (let i = 0; i < args.length; i++) {
+if (typeof args[i] == "undefined") {
+throw new TypeError("Argument " + i + " of " + symbol + " is undefined");
+}
+}
+let result = fun.apply(fun, args);
+return returnType.importFromC(result, symbol);
+};
+LOG("Function", symbol, "declared");
+return result;
+} catch (x) {
+// Note: Not being able to declare a function is normal.
+// Some functions are OS (or OS version)-specific.
+LOG("Could not declare function ", symbol, x);
+return null;
+}
+};
+exports.declareFFI = declareFFI;
+/**
+* Define a lazy getter to a js-ctypes function using declareFFI.
+*
+* @param {object} The object containing the function as a field.
+* @param {string} The name of the field containing the function.
+* @param {ctypes.library} lib The ctypes library holding the function.
+* @param {string} symbol The name of the function, as defined in the
+* library.
+* @param {ctypes.abi} abi The abi to use, or |null| for default.
+* @param {Type} returnType The type of values returned by the function.
+* @param {...Type} argTypes The type of arguments to the function.
+*/
+function declareLazyFFI(object, field, ...declareFFIArgs) {
+Object.defineProperty(object, field, {
+get: function() {
+delete this[field];
+let ffi = declareFFI(...declareFFIArgs);
+if (ffi) {
+return this[field] = ffi;
+}
+return undefined;
+},
+configurable: true,
+enumerable: true
+});
+}
+exports.declareLazyFFI = declareLazyFFI;
+/**
+* Define a lazy getter to a js-ctypes function using ctypes method declare.
+*
+* @param {object} The object containing the function as a field.
+* @param {string} The name of the field containing the function.
+* @param {ctypes.library} lib The ctypes library holding the function.
+* @param {string} symbol The name of the function, as defined in the
+* library.
+* @param {ctypes.abi} abi The abi to use, or |null| for default.
+* @param {ctypes.CType} returnType The type of values returned by the function.
+* @param {...ctypes.CType} argTypes The type of arguments to the function.
+*/
+function declareLazy(object, field, lib, ...declareArgs) {
+Object.defineProperty(object, field, {
+get: function() {
+delete this[field];
+try {
+let ffi = lib.declare(...declareArgs);
+return this[field] = ffi;
+} catch (ex) {
+// The symbol doesn't exist
+return undefined;
+}
+},
+configurable: true
+});
+}
+exports.declareLazy = declareLazy;
+// A bogus array type used to perform pointer arithmetics
+let gOffsetByType;
+/**
+* Advance a pointer by a number of items.
+*
+* This method implements adding an integer to a pointer in C.
+*
+* Example:
+*   // ptr is a uint16_t*,
+*   offsetBy(ptr, 3)
+*  // returns a uint16_t* with the address ptr + 3 * 2 bytes
+*
+* @param {C pointer} pointer The start pointer.
+* @param {number} length The number of items to advance. Must not be
+* negative.
+*
+* @return {C pointer} |pointer| advanced by |length| items
+*/
+let offsetBy =
+function offsetBy(pointer, length) {
+if (length === undefined || length < 0) {
+throw new TypeError("offsetBy expects a positive number");
+}
+if (!("isNull" in pointer)) {
+throw new TypeError("offsetBy expects a pointer");
+}
+if (length == 0) {
+return pointer;
+}
+let type = pointer.constructor;
+let size = type.targetType.size;
+if (size == 0 || size == null) {
+throw new TypeError("offsetBy cannot be applied to a pointer without size");
+}
+let bytes = length * size;
+if (!gOffsetByType || gOffsetByType.size <= bytes) {
+gOffsetByType = ctypes.uint8_t.array(bytes * 2);
+}
+let addr = ctypes.cast(pointer, gOffsetByType.ptr).
+contents.addressOfElement(bytes);
+return ctypes.cast(addr, type);
+};
+exports.offsetBy = offsetBy;
+/**
+* Utility function used to normalize a Typed Array or C
+* pointer into a uint8_t C pointer.
+*
+* Future versions might extend this to other data structures.
+*
+* @param {Typed array | C pointer} candidate The buffer. If
+* a C pointer, it must be non-null.
+* @param {number} bytes The number of bytes that |candidate| should contain.
+* Used for sanity checking if the size of |candidate| can be determined.
+*
+* @return {ptr:{C pointer}, bytes:number} A C pointer of type uint8_t,
+* corresponding to the start of |candidate|.
+*/
+function normalizeToPointer(candidate, bytes) {
+if (!candidate) {
+throw new TypeError("Expecting  a Typed Array or a C pointer");
+}
+let ptr;
+if ("isNull" in candidate) {
+if (candidate.isNull()) {
+throw new TypeError("Expecting a non-null pointer");
+}
+ptr = Type.uint8_t.out_ptr.cast(candidate);
+if (bytes == null) {
+throw new TypeError("C pointer missing bytes indication.");
+}
+} else if (isTypedArray(candidate)) {
+// Typed Array
+ptr = Type.uint8_t.out_ptr.implementation(candidate.buffer);
+if (bytes == null) {
+bytes = candidate.byteLength;
+} else if (candidate.byteLength < bytes) {
+throw new TypeError("Buffer is too short. I need at least " +
+bytes +
+" bytes but I have only " +
+candidate.byteLength +
+"bytes");
+}
+} else {
+throw new TypeError("Expecting  a Typed Array or a C pointer");
+}
+return {ptr: ptr, bytes: bytes};
+};
+exports.normalizeToPointer = normalizeToPointer;
+///////////////////// OS interactions
+/**
+* An OS error.
+*
+* This class is provided mostly for type-matching. If you need more
+* details about an error, you should use the platform-specific error
+* codes provided by subclasses of |OS.Shared.Error|.
+*
+* @param {string} operation The operation that failed.
+* @param {string=} path The path of the file on which the operation failed,
+* or nothing if there was no file involved in the failure.
+*
+* @constructor
+*/
+function OSError(operation, path = "") {
+Error.call(this);
+this.operation = operation;
+this.path = path;
+}
+exports.OSError = OSError;
+///////////////////// Temporary boilerplate
+// Boilerplate, to simplify the transition to require()
+// Do not rely upon this symbol, it will disappear with
+// bug 883050.
+exports.OS = {
+Constants: exports.Constants,
+Shared: {
+LOG: LOG,
+clone: clone,
+Type: Type,
+HollowStructure: HollowStructure,
+Error: OSError,
+declareFFI: declareFFI,
+projectValue: projectValue,
+isTypedArray: isTypedArray,
+defineLazyGetter: defineLazyGetter,
+offsetBy: offsetBy
+}
+};
+Object.defineProperty(exports.OS.Shared, "DEBUG", {
+get: function() {
+return Config.DEBUG;
+},
+set: function(x) {
+return Config.DEBUG = x;
+}
+});
+Object.defineProperty(exports.OS.Shared, "TEST", {
+get: function() {
+return Config.TEST;
+},
+set: function(x) {
+return Config.TEST = x;
+}
+});
+///////////////////// Permanent boilerplate
+if (typeof Components != "undefined") {
+this.EXPORTED_SYMBOLS = EXPORTED_SYMBOLS;
+for (let symbol of EXPORTED_SYMBOLS) {
+this[symbol] = exports[symbol];
+}
+}

The Tor Browser / file comparison

comparison: toolkit/components/osfile/modules/osfile_shared_allthreads.jsm

toolkit/components/osfile/modules/osfile_shared_allthreads.jsm