storage/mozIStorageService.idl
author Nicholas Nethercote <nnethercote@mozilla.com>
Fri, 16 Feb 2018 17:54:16 +1100
changeset 407868 32d6774930e55be5c03e8d631fc067a995623c1e
parent 244681 ad01543457e739b4eee7a245e16734a3ecfd10ad
permissions -rw-r--r--
Bug 1438678 - Pass early prefs via shared memory instead of the command line. r=bobowen,jld,glandium. This patch replaces the large -intPrefs/-boolPrefs/-stringPrefs flags with a short-lived, anonymous, shared memory segment that is used to pass the early prefs. Removing the bloat from the command line is nice, but more important is the fact that this will let us pass more prefs at content process start-up, which will allow us to remove the early/late prefs split (bug 1436911). Although this mechanism is only used for prefs, it's conceivable that it could be used for other data that must be received very early by children, and for which the command line isn't ideal. Notable details: - Much of the patch deals with the various platform-specific ways of passing handles/fds to children. - Linux and Mac: we use a fixed fd (8) in combination with the new GeckoChildProcessHost::AddFdToRemap() function (which ensures the child won't close the fd). - Android: like Linux and Mac, but the handles get passed via "parcels" and we use the new SetPrefsFd() function instead of the fixed fd. - Windows: there is no need to duplicate the handle because Windows handles are system-wide. But we do use the new GeckoChildProcessHost::AddHandleToShare() function to add it to the list of inheritable handles. We also ensure that list is processed on all paths (MOZ_SANDBOX with sandbox, MOZ_SANDBOX without sandbox, non-MOZ_SANDBOX) so that the handles are marked as inheritable. The handle is passed via the -prefsHandle flag. The -prefsLen flag is used on all platforms to indicate the size of the shared memory segment. - The patch also moves the serialization/deserialization of the prefs in/out of the shared memory into libpref, which is a better spot for it. (This means Preferences::MustSendToContentProcesses() can be removed.) MozReview-Commit-ID: 8fREEBiYFvc

/* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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/. */

#include "nsISupports.idl"

interface mozIStorageConnection;
interface nsIFile;
interface nsIFileURL;
interface nsIPropertyBag2;
interface nsIVariant;
interface mozIStorageCompletionCallback;

/**
 * The mozIStorageService interface is intended to be implemented by
 * a service that can create storage connections (mozIStorageConnection)
 * to either a well-known profile database or to a specific database file.
 *
 * This is the only way to open a database connection.
 *
 * @note The first reference to mozIStorageService must be made on the main
 * thread.
 */
[scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)]
interface mozIStorageService : nsISupports {
  /**
   * Open an asynchronous connection to a database.
   *
   * This method MUST be called from the main thread. The connection object
   * returned by this function is not threadsafe. You MUST use it only from
   * the main thread.
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * @param aDatabaseStore Either a nsIFile representing the file that contains
   * the database or a special string to open a special database. The special
   * string may be:
   * - "memory" to open an in-memory database.
   *
   * @param aOptions A set of options (may be null). Options may contain:
   * - bool shared (defaults to |false|).
   *   -- If |true|, opens the database with a shared-cache. The
   *     shared-cache mode is more memory-efficient when many
   *     connections to the same database are expected, though, the
   *     connections will contend the cache resource. In any cases
   *     where performance matter, working without a shared-cache will
   *     improve concurrency.  @see openUnsharedDatabase
   *
   * - int growthIncrement (defaults to none).
   *   -- Set the growth increment for the main database.  This hints SQLite to
   *      grow the database file by a given chunk size and may reduce
   *      filesystem fragmentation on large databases.
   *      @see mozIStorageConnection::setGrowthIncrement
   *
   * @param aCallback A callback that will receive the result of the operation.
   *  In case of error, it may receive as status:
   *  - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails.
   *  - NS_ERROR_FILE_CORRUPTED if the database file is corrupted.
   *  In case of success, it receives as argument the new database
   *  connection, as an instance of |mozIStorageAsyncConnection|.
   *
   * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor
   *         one of the special strings understood by this method, or if one of
   *         the options passed through |aOptions| does not have the right type.
   * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the
   *         main thread.
   */
  void openAsyncDatabase(in nsIVariant aDatabaseStore,
                         [optional] in nsIPropertyBag2 aOptions,
                         in mozIStorageCompletionCallback aCallback);
  /**
   * Get a connection to a named special database storage.
   *
   * @param aStorageKey a string key identifying the type of storage
   * requested.  Valid values include: "memory".
   *
   * @see openDatabase for restrictions on how database connections may be
   * used. For the profile database, you should only access it from the main
   * thread since other callers may also have connections.
   *
   * @returns a new mozIStorageConnection for the requested
   * storage database.
   *
   * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
   */
  mozIStorageConnection openSpecialDatabase(in string aStorageKey);

  /**
   * Open a connection to the specified file.
   *
   * Consumers should check mozIStorageConnection::connectionReady to ensure
   * that they can use the database.  If this value is false, it is strongly
   * recommended that the database be backed up with
   * mozIStorageConnection::backupDB so user data is not lost.
   *
   * ==========
   *   DANGER
   * ==========
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * The connection object returned by this function is not threadsafe. You must
   * use it only from the thread you created it from.
   *
   * @param aDatabaseFile
   *        A nsIFile that represents the database that is to be opened..
   *
   * @returns a mozIStorageConnection for the requested database file.
   *
   * @throws NS_ERROR_OUT_OF_MEMORY
   *         If allocating a new storage object fails.
   * @throws NS_ERROR_FILE_CORRUPTED
   *         If the database file is corrupted.
   */
  mozIStorageConnection openDatabase(in nsIFile aDatabaseFile);

  /**
   * Open a connection to the specified file that doesn't share a sqlite cache.
   *
   * Without a shared-cache, each connection uses its own pages cache, which
   * may be memory inefficient with a large number of connections, in such a
   * case so you should use openDatabase instead.  On the other side, if cache
   * contention may be an issue, for instance when concurrency is important to
   * ensure responsiveness, using unshared connections may be a performance win.
   *
   * ==========
   *   DANGER
   * ==========
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * The connection object returned by this function is not threadsafe. You must
   * use it only from the thread you created it from.
   *
   * @param aDatabaseFile
   *        A nsIFile that represents the database that is to be opened.
   *
   * @returns a mozIStorageConnection for the requested database file.
   *
   * @throws NS_ERROR_OUT_OF_MEMORY
   *         If allocating a new storage object fails.
   * @throws NS_ERROR_FILE_CORRUPTED
   *         If the database file is corrupted.
   */
  mozIStorageConnection openUnsharedDatabase(in nsIFile aDatabaseFile);

  /**
   * See openDatabase(). Exactly the same only initialized with a file URL.
   * Custom parameters can be passed to SQLite and VFS implementations through
   * the query part of the URL.
   *
   * @param aURL
   *        A nsIFileURL that represents the database that is to be opened.
   */
  mozIStorageConnection openDatabaseWithFileURL(in nsIFileURL aFileURL);

  /*
   * Utilities
   */

  /**
   * Copies the specified database file to the specified parent directory with
   * the specified file name.  If the parent directory is not specified, it
   * places the backup in the same directory as the current file.  This function
   * ensures that the file being created is unique.
   *
   * @param aDBFile
   *        The database file that will be backed up.
   * @param aBackupFileName
   *        The name of the new backup file to create.
   * @param [optional] aBackupParentDirectory
   *        The directory you'd like the backup file to be placed.
   * @return The nsIFile representing the backup file.
   */
  nsIFile backupDatabaseFile(in nsIFile aDBFile, in AString aBackupFileName,
                             [optional] in nsIFile aBackupParentDirectory);
};

%{C++

#define MOZ_STORAGE_MEMORY_STORAGE_KEY    "memory"

%}