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/SString.h"
  23 #include "ace/Singleton.h"
  24 #include "ace/Synch_Traits.h"
  25 #include <memory>
  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 ();
  47
  48     /**
  49      * @overload
  50      */
  51     const Node_ID & node_ID () 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 ();
  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 () = default;
 100
 101     ACE_UINT32 time_low () const;
 102     void time_low (ACE_UINT32);
 103
 104     ACE_UINT16 time_mid () const;
 105     void time_mid (ACE_UINT16);
 106
 107     ACE_UINT16 time_hi_and_version () const;
 108     void time_hi_and_version (ACE_UINT16);
 109
 110     u_char clock_seq_hi_and_reserved () const;
 111     void clock_seq_hi_and_reserved (u_char);
 112
 113     u_char clock_seq_low () const;
 114     void clock_seq_low (u_char);
 115
 116     UUID_Node & node ();
 117     const UUID_Node & node () const;
 118
 119     void node (const UUID_Node & node);
 120
 121     ACE_CString* thr_id ();
 122     void thr_id (char*);
 123
 124     ACE_CString* pid ();
 125     void pid (char*);
 126
 127     /// Returns a string representation of the UUID
 128     const ACE_CString* to_string () 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 () 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 ();
 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 std::unique_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     enum {ACE_UUID_CLOCK_SEQ_MASK = 0x3FFF};
 203
 204     /// Default constructor.
 205     UUID_Generator();
 206
 207     /// Destructor.
 208     ~UUID_Generator();
 209
 210     /// Initialize the UUID generator
 211     /// @deprecated This method may go away in some future release.
 212     void init ();
 213
 214     /// Format timestamp, clockseq, and nodeID into an UUID of the
 215     /// specified version and variant. For generating UUID's with
 216     /// thread and process ids use variant=0xc0
 217     void generate_UUID (UUID&, ACE_UINT16 version=0x0001, u_char variant=0x80);
 218
 219     /// Format timestamp, clockseq, and nodeID into a VI UUID. For
 220     /// generating UUID's with thread and process ids use variant=0xc0
 221     UUID* generate_UUID (ACE_UINT16 version=0x0001, u_char variant=0x80);
 222
 223     /// Type to represent UTC as a count of 100 nanosecond intervals
 224     /// since 00:00:00.00, 15 October 1582.
 225     typedef ACE_UINT64 UUID_Time;
 226
 227     /// The locking strategy prevents multiple generators from accessing
 228     /// the UUID_state at the same time. Get the locking strategy.
 229     ACE_SYNCH_MUTEX* lock ();
 230
 231     /// Set a new locking strategy and return the old one.
 232     void lock (ACE_SYNCH_MUTEX* lock, bool release_lock);
 233
 234   private:
 235     /// The system time when that last uuid was generated.
 236     UUID_Time time_last_;
 237
 238     /// Type to contain the UUID generator persistent state. This will
 239     /// be kept in memory mapped shared memory
 240     struct UUID_State
 241     {
 242       UUID_Time timestamp;
 243       UUID_Node node;
 244       ACE_UINT16 clock_sequence;
 245     };
 246
 247     /// Obtain a UUID timestamp. Compensate for the fact that the time
 248     /// obtained from getSystem time has a resolution less than 100ns.
 249     void get_timestamp (UUID_Time& timestamp);
 250
 251     /// Obtain a UUID timestamp and clock sequence. Compensate for the
 252     /// fact that the time obtained from getSystem time has a
 253     /// resolution less than 100ns.
 254     void get_timestamp_and_clocksequence (UUID_Time& timestamp,
 255                                           ACE_UINT16& clockSequence);
 256
 257     /// Obtain the system time in UTC as a count of 100 nanosecond intervals
 258     /// since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to
 259     /// the Christian calendar).
 260     void get_systemtime( UUID_Time& timeNow);
 261
 262     /// The UUID generator persistent state.
 263     UUID_State uuid_state_;
 264
 265     ACE_SYNCH_MUTEX* lock_;
 266
 267     bool destroy_lock_;
 268
 269     /// Initialization state of the generator.
 270     bool is_init_;
 271   };
 272 }
 273
 274 ACE_SINGLETON_DECLARE (ACE_Singleton, ACE_Utils::UUID_Generator, ACE_SYNCH_MUTEX)
 275
 276 namespace ACE_Utils
 277 {
 278   typedef ACE_Singleton <ACE_Utils::UUID_Generator, ACE_SYNCH_MUTEX> UUID_GENERATOR;
 279 }
 280
 281 ACE_END_VERSIONED_NAMESPACE_DECL
 282
 283 #if defined (__ACE_INLINE__)
 284 #include "ace/UUID.inl"
 285 #endif /* __ACE_INLINE__ */
 286
 287 #include /**/ "ace/post.h"
 288 #endif // ACE_UUID_H