nucleus/library/processes/rendezvous.h

   1 #ifndef RENDEZVOUS_CLASS
   2 #define RENDEZVOUS_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : rendezvous                                                        *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2001-$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 #include <basis/astring.h>
  19 #include <basis/contracts.h>
  20
  21 namespace processes {
  22
  23 //! An inter-process synchronization primitive.
  24 /*!
  25   A lock can be created that only one process owns at a time; those that do
  26   not acquire the lock can either return immediately or wait until the current
  27   lock owner releases the rendezvous.  This is unlike the mutex object in
  28   basis, since mutexes only synchronize within the same application.  The
  29   rendezvous can instead allow synchronization of resources between
  30   applications, but this comes at a higher cost per usage.
  31 */
  32
  33 class rendezvous : public virtual basis::base_synchronizer
  34 {
  35 public:
  36   rendezvous(const basis::astring &root_name);
  37     //!< the healthy() method should be checked to ensure creation succeeded.
  38
  39   virtual ~rendezvous();
  40     //!< any lock held is released and the lower level structures freed.
  41
  42   DEFINE_CLASS_NAME("rendezvous");
  43
  44   bool healthy() const;
  45     //!< returns true if the rendezvous object is operable.
  46     /*!< there are cases where creation of the rendezvous might fail; they
  47     can be trapped here. */
  48
  49   //! different ways that the lock() attempt can be made.
  50   enum locking_methods { NO_LOCKING, ENDLESS_WAIT, IMMEDIATE_RETURN };
  51
  52   bool lock(locking_methods how = ENDLESS_WAIT);
  53     //!< grab the lock, if possible.
  54     /*!< if this is not the first time locking the same rendezvous, that's
  55     fine as long as the number of unlocks matches the number of locks. */
  56
  57   void unlock();
  58     //!< releases a previously acquired lock.
  59
  60   // these two methods implement the synchronizer_base interface.
  61   virtual void establish_lock();
  62   virtual void repeal_lock();
  63
  64   const basis::astring &root_name() const;
  65     //!< returns the root name passed in the constructor.
  66
  67 private:
  68   void *_handle;  //!< the real OS version of the inter-app lock.
  69   bool _locked;  //!< true if the lock was successful and still locked.
  70   basis::astring *_root_name;  //!< the identifier for this rendezvous.
  71 };
  72
  73 } //namespace.
  74
  75 #endif
  76