ACE/ace/UUID.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file  UUID.h
   6  *
   7  *  @author Andrew T. Finnel <andrew@activesol.net>
   8  *  @author Yamuna Krishnmaurthy <yamuna@oomworks.com>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_UUID_H
  13 #define ACE_UUID_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/config-all.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Auto_Ptr.h"
  23 #include "ace/SString.h"
  24 #include "ace/Singleton.h"
  25 #include "ace/Synch_Traits.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 namespace ACE_Utils
  30 {
  31   /**
  32    * @class UUID_Node
  33    *
  34    * @brief Holds the MAC-address of the UUID.
  35    */
  36   class ACE_Export UUID_Node
  37   {
  38   public:
  39     /// Size of the node in bytes.
  40     enum {NODE_ID_SIZE = 6};
  41
  42     /// Type definition of the node.
  43     typedef u_char Node_ID[NODE_ID_SIZE];
  44
  45     /// Get the node id
  46     Node_ID & node_ID (void);
  47
  48     /**
  49      * @overload
  50      */
  51     const Node_ID & node_ID (void) const;
  52
  53     /// Test for equality.
  54     bool operator == (const UUID_Node & right) const;
  55
  56     /// Test for inequality.
  57     bool operator != (const UUID_Node & right) const;
  58
  59   private:
  60     /// The value of the node id.
  61     Node_ID node_ID_;
  62   };
  63
  64   /**
  65    * @class ACE_UUID
  66    *
  67    * ACE_UUID represents a Universally Unique IDentifier (UUID) as
  68    * described in (the expired) INTERNET-DRAFT specification entitled
  69    * UUIDs and GUIDs. All instances of UUID are of the time-based
  70    * variety. That is, the version number part of the timeHiAndVersion
  71    * field is 1.
  72    *
  73    * The default constructor creates a nil UUID.
  74    *
  75    * UUIDs have value semantics. In addition, they may be compared for
  76    * ordering and equality.
  77    *
  78    * Additionally in this implementation provisions have been made to include
  79    * process and thread ids to make the UUIDs more unique. The variant 0xc0
  80    * has been added to facilitate this.
  81    */
  82   class ACE_Export UUID
  83   {
  84   public:
  85     /// The size of a binary UUID.
  86     enum { BINARY_SIZE = 16 };
  87
  88     /// Constructor
  89     UUID (void);
  90
  91 #ifndef ACE_LACKS_SSCANF
  92     /// Constructs a UUID from a string representation.
  93     UUID (const ACE_CString& uuidString);
  94 #endif
  95
  96     UUID (const UUID &right);
  97
  98     // Destructor
  99     ~UUID (void);
 100
 101     ACE_UINT32 time_low (void) const;
 102     void time_low (ACE_UINT32);
 103
 104     ACE_UINT16 time_mid (void) const;
 105     void time_mid (ACE_UINT16);
 106
 107     ACE_UINT16 time_hi_and_version (void) const;
 108     void time_hi_and_version (ACE_UINT16);
 109
 110     u_char clock_seq_hi_and_reserved (void) const;
 111     void clock_seq_hi_and_reserved (u_char);
 112
 113     u_char clock_seq_low (void) const;
 114     void clock_seq_low (u_char);
 115
 116     UUID_Node & node (void);
 117     const UUID_Node & node (void) const;
 118
 119     void node (const UUID_Node & node);
 120
 121     ACE_CString* thr_id (void);
 122     void thr_id (char*);
 123
 124     ACE_CString* pid (void);
 125     void pid (char*);
 126
 127     /// Returns a string representation of the UUID
 128     const ACE_CString* to_string (void) const;
 129
 130 #ifndef ACE_LACKS_SSCANF
 131     /// Set the value using a string
 132     void from_string (const ACE_CString& uuid_string);
 133 #endif
 134
 135     /// NIL UUID
 136     static const UUID NIL_UUID;
 137
 138     /// Equality Operations
 139     bool operator == (const UUID &right) const;
 140     bool operator != (const UUID &right) const;
 141
 142     /// Compute a hash value for the UUID.
 143     unsigned long hash (void) const;
 144
 145     /// Assign an existing UUID to this UUID.
 146     const UUID & operator = (const UUID & rhs);
 147
 148     ACE_ALLOC_HOOK_DECLARE;
 149
 150   private:
 151     /// Initialize the UUID
 152     void init (void);
 153
 154     /**
 155      * Helper method to convert from a string UUID.
 156      *
 157      * @param[in]        uuid_string        String version of UUID.
 158      */
 159 #ifndef ACE_LACKS_SSCANF
 160     void from_string_i (const ACE_CString& uuid_string);
 161 #endif
 162
 163     /// Data Members for Class Attributes
 164     struct data
 165     {
 166       /// Time low.
 167       ACE_UINT32 time_low_;
 168
 169       /// Time mid.
 170       ACE_UINT16 time_mid_;
 171
 172       /// Time high and version.
 173       ACE_UINT16 time_hi_and_version_;
 174
 175       /// Clock sequence high and reserved space.
 176       u_char clock_seq_hi_and_reserved_;
 177
 178       /// Clock sequence low.
 179       u_char clock_seq_low_;
 180
 181       /// MAC-address within the UUID.
 182       UUID_Node node_;
 183     } uuid_;
 184
 185     ACE_CString thr_id_;
 186     ACE_CString pid_;
 187
 188     /// The string representation of the UUID. This is created and
 189     /// updated only on demand.
 190     mutable ACE_Auto_Ptr <ACE_CString> as_string_;
 191   };
 192
 193   /**
 194    * @class ACE_UUID_Generator
 195    *
 196    * Singleton class that generates UUIDs.
 197    *
 198    */
 199   class ACE_Export UUID_Generator
 200   {
 201   public:
 202
 203     enum {ACE_UUID_CLOCK_SEQ_MASK = 0x3FFF};
 204
 205     /// Default constructor.
 206     UUID_Generator(void);
 207
 208     /// Destructor.
 209     ~UUID_Generator();
 210
 211     /// Initialize the UUID generator
 212     /// @deprecated This method may go away in some future release.
 213     void init (void);
 214
 215     /// Format timestamp, clockseq, and nodeID into an UUID of the
 216     /// specified version and variant. For generating UUID's with
 217     /// thread and process ids use variant=0xc0
 218     void generate_UUID (UUID&, ACE_UINT16 version=0x0001, u_char variant=0x80);
 219
 220     /// Format timestamp, clockseq, and nodeID into a VI UUID. For
 221     /// generating UUID's with thread and process ids use variant=0xc0
 222     UUID* generate_UUID (ACE_UINT16 version=0x0001, u_char variant=0x80);
 223
 224     /// Type to represent UTC as a count of 100 nanosecond intervals
 225     /// since 00:00:00.00, 15 October 1582.
 226     typedef ACE_UINT64 UUID_Time;
 227
 228     /// The locking strategy prevents multiple generators from accessing
 229     /// the UUID_state at the same time. Get the locking strategy.
 230     ACE_SYNCH_MUTEX* lock (void);
 231
 232     /// Set a new locking strategy and return the old one.
 233     void lock (ACE_SYNCH_MUTEX* lock, bool release_lock);
 234
 235   private:
 236     /// The system time when that last uuid was generated.
 237     UUID_Time time_last_;
 238
 239     /// Type to contain the UUID generator persistent state. This will
 240     /// be kept in memory mapped shared memory
 241     struct UUID_State
 242     {
 243       UUID_Time timestamp;
 244       UUID_Node node;
 245       ACE_UINT16 clock_sequence;
 246     };
 247
 248     /// Obtain a UUID timestamp. Compensate for the fact that the time
 249     /// obtained from getSystem time has a resolution less than 100ns.
 250     void get_timestamp (UUID_Time& timestamp);
 251
 252     /// Obtain a UUID timestamp and clock sequence. Compensate for the
 253     /// fact that the time obtained from getSystem time has a
 254     /// resolution less than 100ns.
 255     void get_timestamp_and_clocksequence (UUID_Time& timestamp,
 256                                           ACE_UINT16& clockSequence);
 257
 258     /// Obtain the system time in UTC as a count of 100 nanosecond intervals
 259     /// since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to
 260     /// the Christian calendar).
 261     void get_systemtime( UUID_Time& timeNow);
 262
 263     /// The UUID generator persistent state.
 264     UUID_State uuid_state_;
 265
 266     ACE_SYNCH_MUTEX* lock_;
 267
 268     bool destroy_lock_;
 269
 270     /// Initialization state of the generator.
 271     bool is_init_;
 272   };
 273
 274   typedef ACE_Singleton <ACE_Utils::UUID_Generator, ACE_SYNCH_MUTEX>
 275           UUID_GENERATOR;
 276 }
 277
 278 ACE_SINGLETON_DECLARE (ACE_Singleton, ACE_Utils::UUID_Generator, ACE_SYNCH_MUTEX)
 279
 280 ACE_END_VERSIONED_NAMESPACE_DECL
 281
 282 #if defined (__ACE_INLINE__)
 283 #include "ace/UUID.inl"
 284 #endif /* __ACE_INLINE__ */
 285
 286 #include /**/ "ace/post.h"
 287 #endif // ACE_UUID_H