nucleus/library/processes/safe_roller.h

   1 #ifndef SAFE_ROLLER_CLASS
   2 #define SAFE_ROLLER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : safe_roller                                                       *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1998-$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/mutex.h>
  19 #include <structures/roller.h>
  20
  21 namespace processes {
  22
  23 //! Implements a thread-safe roller object.
  24 /*!
  25   Integers can be generated by this object without concern for corruption by
  26   multiple threads.
  27 */
  28
  29 class safe_roller
  30 {
  31 public:
  32   safe_roller(int start_of_range = 0, int end_of_range = MAXINT32);
  33     //!< Provides numbers between the start and end in a thread-safe way.
  34     /*!< constructs a roller that runs from the value "start_of_range" and
  35     will stay smaller than "end_of_range" (unless the initial parameters are
  36     screwed up; this class doesn't validate the start and end of range).
  37     when the roller hits the end of range, then its value is reset to the
  38     "start_of_range" again. */
  39
  40   ~safe_roller();
  41
  42   int next_id();
  43     //!< returns a unique (per instance of this type) id.
  44
  45   int current() const;
  46     //!< returns the current id to be used; be careful!
  47     /*!< this value will be the next one returned, so only look at the
  48     current id and don't use it unwisely.  this function is useful if you want
  49     to assign an id provisionally but might not want to complete the
  50     issuance of it. */
  51
  52   void set_current(int new_current);
  53     //!< allows the current id to be manipulated.
  54     /*!< this must be done with care lest existing ids be re-used. */
  55
  56 private:
  57   structures::int_roller *_rolling;  //!< the id generator.
  58   basis::mutex *_lock;  //!< thread synchronization.
  59
  60   // forbidden...
  61   safe_roller(const safe_roller &);
  62   safe_roller &operator =(const safe_roller &);
  63 };
  64
  65 //////////////
  66
  67 void safe_add(int &to_change, int addition);
  68   //!< thread-safe integer addition.
  69   /*!< the number passed in "addition" is atomically added to the number
  70   referenced in "to_change".  this allows thread-safe manipulation of
  71   a simple number. */
  72
  73 } //namespace.
  74
  75 #endif
  76