toolkit/mozapps/defaultagent/nsIWindowsMutex.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6  #include "nsISupports.idl"
   7
   8 /**
   9 * Interact with Windows named mutexes.
  10 *
  11 * Generally you don't want a Windows named mutex, you want one of the many Gecko
  12 * locking primitives. But when you do want cross-application instance or even
  13 * cross-installation coordination, a Windows named mutex might be an
  14 * appropriate tool.
  15 */
  16 [scriptable, uuid(26f09999-c26e-4b72-8747-5adaefa0914c)]
  17 interface nsIWindowsMutex : nsISupports
  18 {
  19   /**
  20   * Locks the mutex.
  21   *
  22   * Note that this will not block waiting to lock. It attempts to lock the mutex
  23   * and if it can't immediately, NS_ERROR_NOT_AVAILABLE will be thrown.
  24   *
  25   * This function succeeds when an abandoned mutex is found, therefore is
  26   * inappropriate for use if an abandoned mutex might imply the locked resource
  27   * is in a corrupt state.
  28   *
  29   * @throws NS_ERROR_NOT_AVAILABLE
  30   *         If unable to lock the mutex.
  31   */
  32   void tryLock();
  33
  34   /**
  35   * Returns whether the mutex is locked.
  36   *
  37   * @return {boolean} true if locked, false if unlocked.
  38   */
  39   bool isLocked();
  40
  41   /**
  42   * Unlocks the mutex.
  43   * @throws NS_ERROR_UNEXPECTED
  44   *         If unable to release mutex.
  45   */
  46   void unlock();
  47 };
  48
  49 [scriptable, uuid(d54fe2b7-438f-4629-9706-1acda5b51088)]
  50 interface nsIWindowsMutexFactory : nsISupports {
  51   /**
  52   * Creates a Windows named mutex.
  53   *
  54   * @param {AString} aName
  55   *        The system-wide name of the mutex.
  56   * @return {nsIWindowsMutex}
  57   *         The created Windows mutex.
  58   * @throws NS_ERROR_NOT_AVAILABLE
  59   *         If unable to create mutex.
  60   */
  61   nsIWindowsMutex createMutex(in AString aName);
  62 };