nucleus/library/application/singleton_application.h

   1 #ifndef SINGLETON_APPLICATION_CLASS
   2 #define SINGLETON_APPLICATION_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : singleton_application                                             *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2006-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 //! Implements an application lock to ensure only one is running at once.
  19 /*!
  20   This encapsulates the code used to ensure that only one copy of an
  21   application is running at a time.  It can either be made specific to a
  22   user (so that user can run only one at a time) or made global to the entire
  23   machine.
  24 */
  25
  26 #include <basis/astring.h>
  27 #include <basis/contracts.h>
  28 #include <processes/rendezvous.h>
  29
  30 namespace application {
  31
  32 class singleton_application
  33 {
  34 public:
  35   singleton_application(const basis::astring &application_name,
  36           const basis::astring &user_name = basis::astring::empty_string());
  37     //!< constructs a singleton guardian for the "application_name".
  38     /*!< if the "user_name" is non-empty, then it will be used as part of
  39     the lock name.  this ensures that separate users can still run the
  40     application at the same time, which is especially important for terminal
  41     servers.  for a lock that should affect the whole machine and ignore
  42     users, the "user_name" must be empty. */
  43
  44   virtual ~singleton_application();
  45
  46   DEFINE_CLASS_NAME("singleton_application");
  47
  48   bool already_tried() const;
  49     //!< returns true if the singleton has already tried to lock.
  50
  51   bool allow_this_instance();
  52     //!< the application must check this before starting up.
  53     /*!< if this returns false, then the application must exit immediately or
  54     it will be violating the singleton rule. */
  55
  56   bool already_running();
  57     //!< returns false if this program is not already running.
  58     /*!< this is just the opposite of the allow_this_instance() method. */
  59
  60   void release_lock();
  61     //!< let's go of the application lock, if we had previously gotten it.
  62     /*!< this should only be called when the application is about to exit. */
  63
  64 private:
  65   int c_initial_try;  //!< has the initial locking attempt been made?
  66     /* if c_initial_try is zero, no attempt made yet.  if it's 1, then tried
  67     and succeeded.  if it's greater than one, then tried and failed. */
  68   processes::rendezvous *_app_lock;  //!< used to lock out other instances.
  69   bool _got_lock;  //!< records whether we successfully got the lock or not.
  70 };
  71
  72 } //namespace.
  73
  74 #endif
  75