| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <title>Uuid Library</title> |
| <style type="text/css"> |
| pre { margin: 1em; padding: 1em; border: 1px solid #ddd; } |
| </style> |
| </head> |
| <body> |
| <h1><img src="../../boost.png" alt="Boost" WIDTH="277" HEIGHT="86">Uuid</h1> |
| |
| <h2><a name="Contents">Contents</a></h2> |
| |
| <ol> |
| <li><a href="#Introduction">Introduction</a></li> |
| <li><a href="#Examples">Examples</a></li> |
| <ul> |
| <li><a href="#Tagging">Tagging</a></li> |
| <li><a href="#POD Efficiencies">POD Efficiencies</a></li> |
| <li><a href="#Byte Extraction">Byte Extraction</a></li> |
| </ul |
| <li><a href="#Reference">Reference</a></li> |
| <ul> |
| <li><a href="#boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis">Synopsis</a></li> |
| <li><a href="#Size">Size</a></li> |
| <li><a href="#Iteration">Iteration</a></li> |
| <li><a href="#Nil">Nil uuid</a></li> |
| <li><a href="#Variant">Variant</a></li> |
| <li><a href="#Version">Version</a></li> |
| <li><a href="#Swap">Swap</a></li> |
| <li><a href="#Operators">Operators</a></li> |
| <li><a href="#Hash">Hash</a></li> |
| </ul> |
| <li><a href="#boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_generators">Synopsis</a></li> |
| </ul> |
| <li><a href="#boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_nil_generator">Synopsis</a></li> |
| <li><a href="#Nil Generator">Nil Generator</a></li> |
| </ul> |
| <li><a href="#boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_string_generator">Synopsis</a></li> |
| <li><a href="#String Generator">String Generator</a></li> |
| </ul> |
| <li><a href="#boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_name_generator">Synopsis</a></li> |
| <li><a href="#Name Generator">Name Generator</a></li> |
| </ul> |
| <li><a href="#boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_random_generator">Synopsis</a></li> |
| <li><a href="#Random Generator">Random Generator</a></li> |
| </ul> |
| <li><a href="#boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_io">Synopsis</a></li> |
| <li><a href="#Stream_operators">Stream Operators</a></li> |
| <li><a href="#to_string">To String</a></li> |
| </ul> |
| <li><a href="#boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></li> |
| <ul> |
| <li><a href="#Synopsis_serialize">Synopsis</a></li> |
| <li><a href="#Serialization">Serialization</a></li> |
| </ul> |
| </ul> |
| <li><a href="#Design notes">Design notes</a></li> |
| <li><a href="#History and Acknowledgements">History and Acknowledgements</a></li> |
| </ol> |
| |
| <h2><a name="Introduction">Introduction</a></h2> |
| <p> |
| A UUID, or Universally unique identifier, is intended to uniquely identify |
| information in a distributed environment without significant central |
| coordination. It can be used to tag objects with very short lifetimes, or |
| to reliably identify very persistent objects across a network. |
| <p> |
| UUIDs have many applications. Some examples follow: Databases may use UUIDs |
| to identify rows or records in order to ensure that they are unique across |
| different databases, or for publication/subscription services. Network messages |
| may be identified with a UUID to ensure that different parts of a message are put |
| back together again. Distributed computing may use UUIDs to identify a remote |
| procedure call. Transactions and classes involved in serialization may be |
| identified by UUIDs. Microsoft's component object model (COM) uses UUIDs to |
| distinguish different software component interfaces. UUIDs are inserted into |
| documents from Microsoft Office programs. UUIDs identify audio or |
| video streams in the Advanced Systems Format (ASF). UUIDs are also a basis |
| for OIDs (object identifiers), and URNs (uniform resource name). |
| |
| <p> |
| An attractive feature of UUIDs when compared to alternatives is their relative |
| small size, of 128-bits, or 16-bytes. Another is that the creation of UUIDs |
| does not require a centralized authority. |
| |
| <p>When UUIDs are generated by one of the defined |
| mechanisms, they are either guaranteed to be unique, different from all other |
| generated UUIDs (that is, it has never been generated before and it will |
| never be generated again), or it is extremely likely to be unique (depending |
| on the mechanism). |
| |
| <h2><a name="Examples">Examples</a></h2> |
| <h3><a name="Tagging">Tagging</a></h3> |
| <pre> |
| // example of tagging an object with a uuid |
| // see <a href="./test/test_tagging.cpp"><tt>boost/libs/uuid/test/test_tagging.cpp</tt></a> |
| |
| #include <<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>> |
| #include <<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>> |
| |
| class object |
| { |
| public: |
| object() |
| : tag(boost::uuids::random_generator()()) |
| , state(0) |
| {} |
| |
| explicit object(int state) |
| : tag(boost::uuids::random_generator()()) |
| , state(state) |
| {} |
| |
| object(object const& rhs) |
| : tag(rhs.tag) |
| , state(rhs.state) |
| {} |
| |
| bool operator==(object const& rhs) const { |
| return tag == rhs.tag; |
| } |
| |
| object& operator=(object const& rhs) { |
| tag = rhs.tag; |
| state = rhs.state; |
| } |
| |
| int get_state() const { return state; } |
| void set_state(int new_state) { state = new_state; } |
| |
| private: |
| boost::uuids::uuid tag; |
| |
| int state; |
| }; |
| |
| object o1(1); |
| object o2 = o1; |
| o2.set_state(2); |
| assert(o1 == o2); |
| |
| object o3(3); |
| assert(o1 != o3); |
| assert(o2 != o3); |
| </pre> |
| |
| <h3><a name="POD Efficiencies">POD Efficiencies</a></h3> |
| <p> |
| This library implements a UUID as a POD allowing a UUID |
| to be used in the most efficient ways, including using memcpy, |
| and aggregate initializers. A drawback is that a POD can |
| not have any constructors, and thus declaring a UUID will not |
| initialize it to a value generated by one of the defined |
| mechanisms. But a class based on a UUID can be defined |
| that does initialize itself to a value generated by one of |
| the defined mechanisms. |
| <p> |
| Note that <tt>boost::is_pod</tt> is specialized for <tt>boost::uuids::uuid</tt> |
| and depends on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>. |
| Define <tt>BOOST_UUID_NO_TYPE_TRAITS</tt> before including <a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a> |
| to remove the dependency on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>. |
| <pre> |
| // example using memcpy and aggregate initializers |
| // example of a class uuid see <a href="./test/test_uuid_class.cpp"><tt>boost/libs/uuid/test/test_uuid_class.cpp</tt></a> |
| |
| #include <<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>> |
| #include <<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>> |
| |
| { // example using memcpy |
| unsigned char uuid_data[16]; |
| // fill uuid_data |
| |
| boost::uuids::uuid u; |
| |
| memcpy(&u, uuid_data, 16); |
| } |
| |
| { // example using aggregate initializers |
| boost::uuids::uuid u = |
| { 0x12 ,0x34, 0x56, 0x78 |
| , 0x90, 0xab |
| , 0xcd, 0xef |
| , 0x12, 0x34 |
| , 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef |
| }; |
| } |
| |
| // example of creating a uuid class that |
| // initializes the uuid in the constructor |
| // using a defined mechanism |
| |
| class uuid_class : public boost::uuids::uuid |
| { |
| public: |
| uuid_class() |
| : boost::uuids::uuid(boost::uuids::random_generator()()) |
| {} |
| |
| explicit uuid_class(boost::uuids::uuid const& u) |
| : boost::uuids::uuid(u) |
| {} |
| |
| operator boost::uuids::uuid() { |
| return static_cast<boost::uuids::uuid&>(*this); |
| } |
| |
| operator boost::uuids::uuid() const { |
| return static_cast<boost::uuids::uuid const&>(*this); |
| } |
| }; |
| |
| uuid_class u1; |
| uuid_class u2; |
| |
| assert(u1 != u2); |
| </pre> |
| |
| <h3><a name="Byte Extraction">Byte Extraction</a></h3> |
| <p>It is sometimes useful to get at the 16 bytes of a <b>uuid</b> directly. |
| Typical use is as follows: |
| |
| <pre> |
| boost::uuids::uuid u; |
| std::vector<char> v(u.size()); |
| std::copy(u.begin(), u.end(), v.begin()); |
| </pre> |
| |
| <p>Note: <tt>boost::uuids::uuid::size()</tt> always returns 16. |
| |
| <h2><a name="Reference">Reference</a></h2> |
| <h3><a name="boost/uuid/uuid.hpp" href="./../../boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></h3> |
| <h4><a name="Synopsis">Synopsis</a></h4> |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| class uuid { |
| public: |
| typedef uint8_t value_type; |
| typedef uint8_t& reference; |
| typedef uint8_t const& const_reference; |
| typedef uint8_t* iterator; |
| typedef uint8_t const* const_iterator; |
| typedef std::size_t size_type; |
| typedef std::ptrdiff_t difference_type; |
| |
| static size_type static_size(); |
| |
| // iteration |
| iterator begin(); |
| iterator end(); |
| const_iterator begin() const; |
| const_iterator end() const; |
| |
| size_type size() const; |
| |
| bool is_nil() const; |
| |
| enum variant_type { |
| variant_ncs, // NCS backward compatibility |
| variant_rfc_4122, // defined in RFC 4122 document |
| variant_microsoft, // Microsoft Corporation backward compatibility |
| variant_future // future definition |
| }; |
| variant_type variant() const; |
| |
| enum version_type { |
| version_unknown = -1, |
| version_time_based = 1, |
| version_dce_security = 2, |
| version_name_based_md5 = 3, |
| version_random_number_based = 4, |
| version_name_based_sha1 = 5 |
| }; |
| version_type version() const; |
| |
| // Swap function |
| void swap(uuid& rhs); |
| |
| uint8_t data[static_size()]; |
| }; |
| |
| // standard operators |
| bool operator==(uuid const& lhs, uuid const& rhs); |
| bool operator!=(uuid const& lhs, uuid const& rhs); |
| bool operator<(uuid const& lhs, uuid const& rhs); |
| bool operator>(uuid const& lhs, uuid const& rhs); |
| bool operator<=(uuid const& lhs, uuid const& rhs); |
| bool operator>=(uuid const& lhs, uuid const& rhs); |
| |
| void swap(uuid& lhs, uuid& rhs); |
| |
| std::size_t hash_value(uuid const& u); |
| |
| }} // namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Size">Size</a></h4> |
| |
| <p>The size of a <b>uuid</b> (in bytes) can be obtained either by |
| calling the function <tt>boost::uuids::uuid::size()</tt> or by |
| calling the static function <tt>boost::uuids::uuid::static_size()</tt>, |
| both always return 16. |
| <pre> |
| boost::uuids::uuid u; |
| assert(16 == u.size()); |
| assert(16 == boost::uuids::uuid::static_size()); |
| </pre> |
| |
| <h4><a name="Iteration">Iteration</a></h4> |
| |
| <p>Both iterators and constant iterators are provided. |
| <pre> |
| boost::uuids::uuid u; |
| for (boost::uuids::uuid::const_iterator it=u.begin(); it!=u.end(); ++it) { |
| boost::uuids::uuid::value_type v = *it; |
| } |
| for (boost::uuids::uuid::iterator it=u.begin(); it!=u.end(); ++it) { |
| *it = 0; |
| } |
| </pre> |
| |
| <h4><a name="Nil">Nil uuid</a></h4> |
| <p>The function, <tt>boost::uuids::uuid::is_null()</tt> returns true if and |
| only if the <b>uuid</b> is equal to {00000000-0000-0000-0000-000000000000}. |
| </p> |
| |
| <h4><a name="Variant">Variant</a></h4> |
| <p>Three bits of a <b>uuid</b> determine the variant.</p> |
| <pre> |
| boost::uuids::uuid u; |
| boost::uuids::uuid::variant_type v = u.variant(); |
| </pre> |
| |
| <h4><a name="Version">Version</a></h4> |
| <p>Four bits of a <b>uuid</b> determine the variant, that is the mechanism |
| used to generate the <b>uuid</b>. |
| </p> |
| <pre> |
| boost::uuids::uuid u; |
| boost::uuids::uuid::version_type v = u.version(); |
| </pre> |
| |
| <h4><a name="Swap">Swap</a></h4> |
| <p>Both <tt>boost::uuids::uuid::swap()</tt> and <tt>boost::uuids::swap()</tt> |
| are provided. |
| </p> |
| <pre> |
| boost::uuids::uuid u1, u2; |
| u1.swap(u2); |
| swap(u1, u2); |
| </pre> |
| |
| <h4><a name="Operators">Operators</a></h4> |
| <p> |
| All of the standard numeric operators are defined for the <b>uuid</b> |
| class. These include: |
| <pre> |
| operator== |
| operator!= |
| operator< |
| operator> |
| operator<= |
| operator>= |
| </pre> |
| |
| <h4><a name="Hash">Hash Function</a></h4> |
| <p> |
| This function allows <b>uuid</b>s to be used with |
| <a href="http://www.boost.org/doc/html/hash.html"><b>boost::hash</b></a> |
| |
| <pre> |
| boost::hash<boost::uuids::uuid> uuid_hasher; |
| std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid()); |
| </pre> |
| |
| <h3><a name="boost/uuid/uuid_generators.hpp" href="./../../boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></h3> |
| <h4><a name="Synopsis_generators">Synopsis</a></h4> |
| This file includes all the <b>uuid</b> generators for convenience. |
| <pre> |
| #include <<a href="./../../boost/uuid/nil_generator.hpp"><tt>boost/uuid/nil_generator.hpp</tt></a>> |
| #include <<a href="./../../boost/uuid/string_generator.hpp"><tt>boost/uuid/string_generator.hpp</tt></a>> |
| #include <<a href="./../../boost/uuid/name_generator.hpp"><tt>boost/uuid/name_generator.hpp</tt></a>> |
| #include <<a href="./../../boost/uuid/random_generator.hpp"><tt>boost/uuid/random_generator.hpp</tt></a>> |
| </pre> |
| |
| <h3><a name="boost/uuid/nil_generator.hpp" href="./../../boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></h3> |
| <h4><a name="Synopsis_nil_generator">Synopsis</a></h4> |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| struct nil_generator { |
| typedef uuid result_type; |
| |
| uuid operator()() const; |
| }; |
| uuid nil_uuid(); |
| |
| }} //namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Nil Generator">Nil Generator</a></h4> |
| <p>The <tt>boost::uuids::nil_generator</tt> class always generates a nil <b>uuid</b>. |
| <pre> |
| boost::uuids::nil_generator gen; |
| boost::uuids::uuid u = gen(); |
| assert(u.is_nil() == true); |
| |
| // or for convenience |
| boost::uuids::uuid u = boost::uuids::nil_uuid(); |
| assert(u.is_nil() == true); |
| </pre> |
| |
| <h3><a name="boost/uuid/string_generator.hpp" href="./../../boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></h3> |
| <h4><a name="Synopsis_string_generator">Synopsis</a></h4> |
| |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| struct string_generator { |
| typedef uuid result_type; |
| |
| template <typename ch, typename char_traits, typename alloc> |
| uuid operator()(std::basic_string<ch, char_traits, alloc> const& s) const; |
| }; |
| |
| }} //namespace boost::uuids |
| </pre> |
| |
| <h4><a name="String Generator">String Generator</a></h4> |
| <p>The <tt>boost::uuids::string_generator</tt> class generates a <b>uuid</b> from a string. |
| <pre> |
| boost::uuids::string_generator gen; |
| boost::uuids::uuid u1 = gen("{01234567-89ab-cdef-0123-456789abcdef}"); |
| boost::uuids::uuid u2 = gen(L"01234567-89ab-cdef-0123-456789abcdef"); |
| boost::uuids::uuid u3 = gen(std::string("0123456789abcdef0123456789abcdef")); |
| boost::uuids::uuid u4 = gen(std::wstring(L"01234567-89ab-cdef-0123-456789abcdef")); |
| </pre> |
| |
| <h3><a name="boost/uuid/name_generator.hpp" href="./../../boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></h3> |
| <h4><a name="Synopsis_name_generator">Synopsis</a></h4> |
| |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| class name_generator { |
| public: |
| typedef uuid result_type; |
| |
| explicit name_generator(uuid const& namespace_uuid); |
| |
| uuid operator()(const char* name) const; |
| uuid operator()(const wchar_t* name) const; |
| tempate <typename ch, typename char_traits, typename alloc> |
| uuid operator()(std::basic_string<ch, char_traits, alloc> const& name) const; |
| uuid operator()(void const* buffer, std::size_t byte_count) const; |
| }; |
| |
| }} //namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Name Generator">Name Generator</a></h4> |
| <p> |
| The <tt>boost::uuids::name_generator</tt> class generates a name based <b>uuid</b> from a |
| namespace uuid and a name. |
| <pre> |
| boost::uuids::uuid dns_namespace_uuid; // initialize to {6ba7b810-9dad-11d1-80b4-00c04fd430c8} |
| |
| boost::uuids::name_generator gen(dns_namespace_uuid); |
| boost::uuids::uuid u = gen("boost.org"); |
| </pre> |
| |
| <h3><a name="boost/uuid/random_generator.hpp" href="./../../boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></h3> |
| <h4><a name="Synopsis_random_generator">Synopsis</a></h4> |
| |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| template <typename UniformRandomNumberGenerator> |
| class basic_random_generator { |
| public: |
| typedef uuid result_type; |
| |
| basic_random_generator(); |
| explicit basic_random_generator(UniformRandomNumberGenerator& gen); |
| explicit basic_random_generator(UniformRandomNumberGenerator* pGen); |
| |
| uuid operator()(); |
| }; |
| typedef basic_random_generator<mt19937> random_generator; |
| |
| }} // namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Random Generator">Random Generator</a></h4> |
| <p> |
| The <tt>boost::uuids::basic_random_generator</tt> class generates a random number |
| based uuid from a random number generator (one that conforms to the |
| <a href="http://www.boost.org/libs/random/random-concepts.html#uniform-rng">UniformRandomNumberGenerator</a> |
| concept). |
| <pre> |
| //default construct the random number generator and seed it |
| boost::uuids::basic_random_generator<boost::mt19937> gen; |
| boost::uuids::uuid u = gen(); |
| |
| //for convenience boost::uuids::random_generator |
| //is equivalent to boost::uuids::basic_random_generator<boost::mt19937> |
| boost::uuids::random_generator gen; |
| boost::uuids::uuid u = gen(); |
| |
| //use an existing random number generator |
| //pass either a reference or a pointer to the random number generator |
| boost::mt19937 ran; |
| boost::uuids::basic_random_generator<boost::mt19937> gen(&ran); |
| boost::uuids::uuid u = gen(); |
| </pre> |
| |
| <h3><a name="boost/uuid/uuid_io.hpp" href="./../../boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></h3> |
| <h4><a name="Synopsis_io">Synopsis</a></h4> |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| template <typename ch, typename char_traits> |
| std::basic_ostream<ch, char_traits>& operator<<(std::basic_ostream<ch, char_traits> &os, uuid const& u); |
| |
| template <typename ch, typename char_traits> |
| std::basic_istream<ch, char_traits>& operator>>(std::basic_istream<ch, char_traits> &is, uuid &u); |
| |
| std::string to_string(uuid const& u); |
| std::wstring to_wstring(uuid const& u); |
| |
| }} // namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Stream_operators">Stream Operators</a></h4> |
| <p> |
| The standard input and output stream operators <tt><<</tt> and <tt>>></tt> |
| are provided by including <a href="../../boost/uuid/uuid_io.hpp"><tt>boost/uuid/uuid_io.hpp</tt></a>. |
| The string representation of a <b>uuid</b> is <tt>hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh</tt> |
| where <tt>h</tt> is a hexidecimal digit. |
| <pre> |
| boost::uuids::uuid u1; // initialize uuid |
| |
| std::stringstream ss; |
| ss << u1; |
| |
| boost::uuids::uuid u2; |
| ss >> u2; |
| |
| assert(u1, u2); |
| </pre> |
| |
| <p> |
| One can also use <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>. |
| <pre> |
| boost::uuids::uuid u1; // initialize uuid |
| |
| std::string s = boost::lexical_cast<std::string>(u); |
| boost::uuids::uuid u2 = boost::lexical_cast<boost::uuids::uuid>(s); |
| |
| assert(u1 == u2); |
| </pre> |
| |
| <h4><a name="to_string">To String</a></h4> |
| <p> |
| The functions <tt>to_string</tt> and <tt>to_wstring</tt> are provided as a |
| convenience to convert a <b>uuid</b> to a string. They are also likely faster than |
| the stream operators or using <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>. |
| <pre> |
| boost::uuids::uuid u; // initialize uuid |
| |
| std::string s1 = to_string(u); |
| |
| std::wstring s2 = to_wstring(u); |
| </pre> |
| |
| <h3><a name="boost/uuid/uuid_serialize.hpp" href="./../../boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></h3> |
| <h4><a name="Synopsis_serialize">Synopsis</a></h4> |
| <pre> |
| namespace boost { |
| namespace uuids { |
| |
| BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type) |
| |
| }} // namespace boost::uuids |
| </pre> |
| |
| <h4><a name="Serialization">Serialization</a></h4> |
| <p> |
| Serialization is accomplished with the <a href="http://www.boost.org/libs/serialization/doc/index.html"> |
| Boost Serialization</a> library. A <b>uuid</b> is serialized as a |
| <a href="http://www.boost.org/libs/serialization/doc/serialization.html#primitiveoperators"> |
| primitive type</a>, thus only the <b>uuid</b> value will be saved to/loaded from an archive. |
| <p> |
| Include <a href="../../boost/uuid/uuid_serialize.hpp"><tt>boost/uuid/uuid_serialize.hpp</tt></a> to enable serialization for <b>uuid</b>s. |
| |
| <h2><a name="Design notes">Design notes</a></h2> |
| <p> |
| The document, <a href="http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf"> |
| http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf</a>, was used to design |
| and implement the <b>boost::uuids::uuid</b> struct. |
| |
| <p>The <tt>boost::uuids::basic_random_generator</tt> class' default constructor |
| seeds the random number generator with a SHA-1 hash of a number of different |
| values including <tt>std::time(0)</tt>, <tt>std::clock()</tt>, uninitialized |
| data, value return from <tt>new unsigned int</tt>, etc.. |
| |
| <p>Using <a href="http://valgrind.org/">Valgrind</a> produces a number of false |
| positives with the default constructor of <tt>boost::uuids::basic_random_generator</tt>. |
| One solution is to suppress the errors as described in |
| <a href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress">Valgrind's documentation</a>. |
| Another solution is to use a different constructor of <tt>boost::uuids::basic_random_generator</tt> |
| and explicitly pass in a random number generator. |
| <pre> |
| boost::mt19937 ran; |
| ran.seed(time(NULL)); // one should likely seed in a better way |
| boost::uuids::basic_random_generator<boost::mt19937> gen(&ran); |
| boost::uuids::uuid u = gen(); |
| </pre> |
| |
| <p>The <tt>boost::uuids::name_generator</tt> class uses the SHA-1 hash function to |
| compute the <b>uuid</b>. |
| |
| <p>All functions are re-entrant. Classes are as thread-safe as an int. That is an |
| instance can not be shared between threads without proper synchronization. |
| |
| <h2><a name="History and Acknowledgements">History and Acknowledgements</a></h2> |
| <p> |
| A number of people on the <a href="http://www.boost.org/">boost.org</a> |
| mailing list provided useful comments and greatly helped to shape the library. |
| |
| <p>Revised February 6, 2010</p> |
| |
| <hr> |
| <p>© Copyright Andy Tompkins, 2006</p> |
| <p> Distributed under the Boost Software |
| License, Version 1.0. (See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
| www.boost.org/LICENSE_1_0.txt</a>)</p> |
| </body> |
| </html> |