.. uuid_doc documentation master file, created by
   sphinx-quickstart on Fri Feb  6 18:39:23 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

What is the UUID generator
====================================

The ``UUID`` generator is a **client-side** function generating a unique 16-byte ``UUID`` value.
Its algorithm is based on the MySQL Server ``uuid()`` function, but with some differences that take into acccount the distribution of the clients that do not necessary run on the same host.

Nevertheless, it must provide a close to impossible chance of repeating the same value disregard of any conditions such as:

* two or more generators run on same or different hosts
* two or more generators run within same or different processes
* generators run concurrently or separated in time

UUID structure
====================================

UUID has the following structure:

 .. uml::

    object NODE
    object CLOCK_SEQ
    object TIME_HI_VER
    object TIME_MID
    object TIME_LOW

    NODE : 48-bit
    CLOCK_SEQ : 16-bit
    TIME_HI_VER : 16-bit
    TIME_MID : 16-bit
    TIME_LOW : 32-bit


    NODE -down-> CLOCK_SEQ
    CLOCK_SEQ -down-> TIME_HI_VER
    TIME_HI_VER -down-> TIME_MID
    TIME_MID -down-> TIME_LOW

    note right of NODE
      <b>6 bytes randomly generated using a user-provided seed.
      The same node values are used within a process.
      Changing the random generator seed causes generating of
      new node.
    end note

    note right of CLOCK_SEQ
      <b>randomly generated 16-bit value also containing the
      UUID variant. This value changes on setting a new seed
      for the generator or if two time values within the same
      process have same time values.
    end note

    note right of TIME_HI_VER
      <b>represents the higher 16 bits of system timestamp
      <b>and UUID version
      system timestamp is considered a 64-bit structure,
      so this component is obtained as
      <b>timestamp >> 48 | UUID_VERSION   
    end note

    note right of TIME_MID
      <b>represents the medium 16 bits of system timestamp
      this component changes when TIME_LOW reaches its maximum
    end note

    note right of TIME_LOW
      <b>represents the lower 32 bits of system timestamp
      in order not to generate the same value the lower bits
      can be "borrowed" from the future when two UUIDs generate
      within the clock granularity

      this protects against generating similar values within
      the same process
    end note

How to use UUID generator
=========================
UUID data type
--------------
To start using the ``UUID`` generator the client code has to use the header:

.. code-block:: c

  #include <uuid_gen.h>

The classes and declarations for the ``UUID`` generator are inside ``uuid`` name space.

The header file contains the definitions for ``uuid_type`` as:

.. code-block:: c

  #define UUID_LENGTH_BIN 16
  typedef unsigned char uuid_type[UUID_LENGTH_BIN];


UUID structures
---------------

.. |vspace| raw:: latex

   \vspace{5mm}

* ``Uuid`` - a static structure with automatically called constructor and destructor
  initializing/freeing mutexes etc. The user code is not supposed to create instances of
  this structure.

|vspace|  

* ``Uuid::set_seed(uint16_t seed)`` - Setting the seed for the UUID generator.
  The seed has to be set before generator can be used. Otherwise it throws
  an exception.
  
* ``Uuid::set_seed_from_time_pid()`` - Converience function for setting the seed
   for the UUID generator using the current machine time and the process id.
  
* ``Uuid::generate_uuid(uuid_type& uuid)`` - generator returning the result into `uuid` parameter.
  Could be called many times, sequentially or concurrently from different threads.


Usage example
-------------

.. code-block:: c

#include "uuid_gen.h"
  ...
  uuid::uuid_type uuid;
  /* 
    Use the generator.
    The result formatted and converted to text could look as:
     4c6b00268312fb20-4e44-d011-bf17975b
  */
  uuid::set_seed(set_seed((uint16_t)(time(0) ^ process_id));
  uuid::generate_uuid(uuid);


Contents:

.. toctree::
   :maxdepth: 2



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

