docs: Added timestamp generator docs

Author: smoczy123

docs/source/SUMMARY.md

@@ -27,6 +27,7 @@
     - [USE keyspace](queries/usekeyspace.md)
     - [Schema agreement](queries/schema-agreement.md)
     - [Query timeouts](queries/timeouts.md)
+    - [Timestamp generators](queries/timestamp-generators.md)
 
 - [Execution profiles](execution-profiles/execution-profiles.md)
     - [Creating a profile and setting it](execution-profiles/create-and-use.md)

docs/source/queries/queries.md

@@ -3,7 +3,7 @@
 Driver supports all kinds of statements supported by ScyllaDB. The following tables aim to bridge between DB concepts and driver's API.
 They include recommendations on which API to use in what cases.
 
-## Kinds of CQL statements (from the CQL protocol point of view):
+## Kinds of CQL statements (from the CQL protocol point of view)
 
 | Kind of CQL statement | Single              | Batch                                    |
 |-----------------------|---------------------|------------------------------------------|
@@ -59,7 +59,7 @@ This is **NOT** strictly related to content of the CQL query string.
 | Load balancing       | advanced if prepared, else primitive                  | advanced if prepared **and ALL** statements in the batch target the same partition, else primitive                                                                                   |
 | Suitable operations  | most of operations                                    | - a list of operations that needs to be executed atomically (batch LightWeight Transaction)</br> - a batch of operations targetting the same partition (as an advanced optimisation) |
 
-## CQL statements - operations (based on what the CQL string contains):
+## CQL statements - operations (based on what the CQL string contains)
 
 | CQL data manipulation statement                | Recommended statement kind                                                                                                               | Recommended Session operation                                                                               |
 |------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
@@ -86,9 +86,10 @@ This is **NOT** strictly related to content of the CQL query string.
 
 For more detailed comparison and more best practices, see [doc page about paging](paged.md).
 
-### Queries are fully asynchronous - you can run as many of them in parallel as you wish.
+### Queries are fully asynchronous - you can run as many of them in parallel as you wish
+
+## `USE KEYSPACE`
 
-## `USE KEYSPACE`:
 There is a special functionality to enable [USE keyspace](usekeyspace.md).
 
 ```{eval-rst}
@@ -106,4 +107,5 @@ There is a special functionality to enable [USE keyspace](usekeyspace.md).
    schema-agreement
    lwt
    timeouts
+   timestamp-generators
 ```

docs/source/queries/timestamp-generators.md

@@ -0,0 +1,54 @@
+# Timestamp generators
+
+If you want to generate timestamps on the client side you can provide
+a TimestampGenerator to a SessionBuilder when creating a Session. Then
+every executed statement will have attached a new timestamp generated
+by the provided TimestampGenerator.
+Timestamps are set according to precendence:
+
+1. ```USING TIMESTAMP``` in the query itself
+2. Manually using ```set_timestamp``` on the query
+3. Timestamp generated by the generator
+
+## Simple Timestamp Generator
+
+Most basic client-side timestamp generator. Generates timestamp
+based on system clock. Provides no guarantees and panics when the system clock
+provides timestamp before the unix epoch.
+
+## Monotonic Timestamp Generator
+
+Client-side timestamp generator. Guarantees monotonic timestamps
+based on the system clock, with automatic timestamp incrementation
+if the system clock timestamp would not be monotonic. If the clock skew
+exceeds `warning_threshold` of the generator (can be changed with `with_warning_times`, 1s by default)
+user will be warned with timestamp generation with `warning_interval` cooldown period
+(can be changed with `with_warning_times`, 1s by default) to not spam the user. If user does not want to 
+be warned about the clock skew, the warnings can be turned off with `without_warnings` function.
+
+``` rust
+# extern crate scylla;
+# use std::error::Error;
+# async fn check_only_compiles() -> Result<(), Box<dyn std::error::Error>> {
+use scylla::client::session::Session;
+use scylla::client::session_builder::SessionBuilder;
+use scylla::policies::timestamp_generator::MonotonicTimestampGenerator;
+use scylla::query::Query;
+use std::sync::Arc;
+
+let session: Session = SessionBuilder::new()
+    .known_node("127.0.0.1:9042")
+    .timestamp_generator(Arc::new(MonotonicTimestampGenerator::new()))
+    .build()
+    .await?;
+
+// This query will have a timestamp generated 
+// by the monotonic timestamp generator
+let my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)");
+let to_insert: i32 = 12345;
+session.query_unpaged(my_query, (to_insert,)).await?;
+# Ok(())
+# }
+```
+
+