# UUIDs

UUIDs are 128-bit identifiers that can be used to uniquely identify information
without requiring central coordination. These are often used in ScyllaDB/Cassandra
for primary and clustering keys. There are two types of UUIDs supported by
the driver (and ScyllaDB/Cassandra), version 1 which is time-based and version 4 which
is randomly generated. Version 1 can be used with ScyllaDB/Cassandra’s `timeuuid` type
and can be used as a timestamp for data.  Timestamp information can be
extracted from the time part of a version 1 UUID using [`cass_uuid_timestamp()`](https://cpp-rs-driver.docs.scylladb.com/stable/api/struct.CassUuid#1a3980467a0bb6642054ecf37d49aebf1a).
Version 4 can be used with ScyllaDB/Cassandra’s `uuid` type for unique identification.

## Generator

A UUID generator object is used to create new UUIDs. The [`CassUuidGen`](https://cpp-rs-driver.docs.scylladb.com/stable/api/struct.CassUuidGen) object
is thread-safe. It should only be created once per application and reused.

Within one wall-clock millisecond, one generator can allocate 10,000 distinct
version 1 UUID timestamps. When the generated timestamp is in the current
millisecond and this capacity is exhausted, calls to `cass_uuid_gen_time()`
busy-wait until the system clock advances, consuming CPU and adding latency.

If the system clock moves backward, or a thread uses a stale clock sample after
another thread advances the timestamp, the generator preserves monotonicity by
incrementing the last timestamp. Generated timestamps can therefore move ahead
of wall time. At sustained rates above 10 million UUIDs per second, this drift
can grow indefinitely. See [issue #507](https://github.com/scylladb/cpp-rs-driver/issues/507) for possible improvements.

```c
CassUuidGen* uuid_gen = cass_uuid_gen_new();

CassUuid uuid;

/* Generate a version 1 UUID */
cass_uuid_gen_time(uuid_gen, &uuid);

/* Generate a version 1 UUID from an existing timestamp */
cass_uuid_gen_from_time(uuid_gen, 1234, &uuid);

/* Generate a version 4 UUID */
cass_uuid_gen_random(uuid_gen, &uuid);

cass_uuid_gen_free(uuid_gen);
```

A [`CassUuidGen`](https://cpp-rs-driver.docs.scylladb.com/stable/api/struct.CassUuidGen) can also be created with user provided information for the
node part of the UUID. This only affects version 1 UUIDs.

```c
/* Only the 48 least signficant bits of the node are considered */
cass_uint64_t node = 0x0000AAAABBBBCCCC;

CassUuidGen* uuid_gen = cass_uuid_gen_new_with_node(node);

/* Generate UUIDs */

cass_uuid_gen_free(uuid_gen);
```

## Extracting information

Information such as the timestamp (for version 1 only) and the version can be
extracted from UUIDs. They can also be converted to and created from the their
hexadecimal string representation e.g. “550e8400-e29b-41d4-a716-446655440000”.

```c
CassUuid uuid;
cass_uuid_from_string("550e8400-e29b-41d4-a716-446655440000", &uuid);

/* Extract timestamp and version */
cass_uint64_t timestamp = cass_uuid_timestamp(uuid);
cass_uint8_t version = cass_uuid_version(uuid);

/* Get string representation of the UUID */
char uuid_str[CASS_UUID_STRING_LENGTH];
cass_uuid_string(uuid, uuid_str);
```