toolkit/xre/MultiInstanceLock.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef MULTIINSTANCELOCK_H
   8 #define MULTIINSTANCELOCK_H
   9
  10 #ifdef XP_WIN
  11 #  include <windows.h>
  12 #endif
  13
  14 // These functions manage "multi-instance locks", which are a type of lock
  15 // specifically designed to allow instances of an application, process, or other
  16 // task to detect when other instances relevant to them are running. Each
  17 // instance opens a lock and holds it for the duration of the task of interest
  18 // (which may be the lifetime of the process, or a shorter period). Then while
  19 // the lock is open, it can be used to check whether any other instances of the
  20 // same task are currently running out of the same copy of the binary, in the
  21 // context of any OS user. A process can open any number of locks, so long as
  22 // they use different names. It is necessary for the process to have permission
  23 // to create files in /tmp/ on POSIX systems or ProgramData\[vendor]\ on
  24 // Windows, so this mechanism may not work for sandboxed processes.
  25
  26 // The implementation is based on file locking. An empty file is created in a
  27 // systemwide (not per-user) location, and a shared (read) lock is taken on that
  28 // file; the value that OpenMultiInstanceLock() returns is the file
  29 // handle/descriptor. When you call IsOtherInstanceRunning(), it will attempt to
  30 // convert that shared lock into an exclusive (write) lock. If that operation
  31 // would succeed, it means that there must not be any other shared locks
  32 // currently taken on that file, so we know there are no other instances
  33 // running. This is a more complex design than most file locks or most other
  34 // concurrency mechanisms, but it is necessary for this use case because of the
  35 // requirement that an instance must be able to detect other instances that were
  36 // started later than it was. If, say, a mutex were used, or another kind of
  37 // exclusive lock, then the first instance that tried to take it would succeed,
  38 // and be unable to tell that another instance had tried to take it later and
  39 // failed. This mechanism allows any number of instances started at any time in
  40 // relation to one another to always be able to detect that the others exist
  41 // (although it does not allow you to know how many others exist). The lock is
  42 // guaranteed to be released if the process holding it crashes or is exec'd into
  43 // something else, because the file is closed when that happens. The file itself
  44 // is not necessarily always deleted on POSIX, because it isn't possible (within
  45 // reason) to guarantee that unlink() is called, but the file is empty and
  46 // created in the /tmp directory, so should not be a serious problem.
  47
  48 namespace mozilla {
  49
  50 #ifdef XP_WIN
  51 using MultiInstLockHandle = HANDLE;
  52 #  define MULTI_INSTANCE_LOCK_HANDLE_ERROR INVALID_HANDLE_VALUE
  53 #else
  54 using MultiInstLockHandle = int;
  55 #  define MULTI_INSTANCE_LOCK_HANDLE_ERROR -1
  56 #endif
  57
  58 /*
  59  * nameToken should be a string very briefly naming the lock you are creating
  60  * creating, and it should be unique except for across multiple instances of the
  61  * same application. The vendor name is included in the generated path, so it
  62  * doesn't need to be present in your supplied name. Try to keep this name sort
  63  * of short, ideally under about 64 characters, because creating the lock will
  64  * fail if the final path string (the token + the path hash + the vendor name)
  65  * is longer than the platform's maximum path and/or path component length.
  66  *
  67  * installPath should be the path to the directory containing the application,
  68  * which will be used to form a path specific to that installation.
  69  *
  70  * Returns MULTI_INSTANCE_LOCK_HANDLE_ERROR upon failure, or a handle which can
  71  * later be passed to the other functions declared here upon success.
  72  */
  73 MultiInstLockHandle OpenMultiInstanceLock(const char* nameToken,
  74                                           const char16_t* installPath);
  75
  76 void ReleaseMultiInstanceLock(MultiInstLockHandle lock);
  77
  78 // aResult will be set to true if another instance *was* found, false if not.
  79 // Return value is true on success, false on error (and aResult won't be set).
  80 bool IsOtherInstanceRunning(MultiInstLockHandle lock, bool* aResult);
  81
  82 };  // namespace mozilla
  83
  84 #endif  // MULTIINSTANCELOCK_H