# Transactions

> UStore for C++

`#include <ustore/db.hpp>`

`#include <ustore/types.hpp>`

## transaction_t

A transaction, which owns its handle and serves one call at a time.

```cpp
class transaction_t
```

It never commits on destruction, never copies, and holds its database open until destroyed, so it may outlive its `[database_t](https://www.unum.cloud/docs/ustore/cpp/quickstart.md#database_t)`.

## read_stamp_t

The stamp a transaction or a snapshot reads at, which a commit validates against.

```cpp
enum read_stamp_t
```

## commit_stamp_t

A commit's position in commit order, visible to every snapshot reading at or above it.

```cpp
enum commit_stamp_t
```

## transaction_ref_t

A transaction, as the calls on one executor see it, without owning either.

```cpp
class transaction_ref_t
```

Batched writes are buffered in the layout the engine prefers until the commit, so a transaction also saves preprocessing.

## transaction_ref_t

```cpp
transaction_ref_t() noexcept=default;
```

```cpp
transaction_ref_t(receiver_t receiver) noexcept;
```

## on

The same transaction, running every call on `executor`.

```cpp
transaction_ref_t on(ustore_executor_t executor) const noexcept;
```

## deferred

The same transaction, whose verbs submit to `executor` and answer deferred calls.

```cpp
deferred_transaction_t deferred(
    ustore_executor_t executor) const noexcept;
```

## contains

Whether a collection named `name` exists at the head.

```cpp
expected<bool> contains(std::string_view name) noexcept;
```

## find

Opens a view of one collection that follows this transaction.

```cpp
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> find(std::string_view name) noexcept;
```

## reset

Opens the transaction, or clears it for reuse, keeping its memory and starting a new generation.

```cpp
status_t reset() noexcept;
```

## stage

Stages the transaction as the first phase of a two-phase commit, answering the stamp it reads at.

```cpp
expected<read_stamp_t> stage() noexcept;
```

## rollback

Withdraws a stage, releasing what it claimed while keeping the reads and writes, so the transaction can stage or commit again.

```cpp
status_t rollback() noexcept;
```

## commit

Commits every update of the transaction, or none of them if any one fails, answering the commit's position in commit order.

```cpp
expected<commit_stamp_t> commit(
    ustore_durability_t durability = ustore_durability_buffered_k) noexcept;
```

- `durability` (in): Whether the call returns only after the data reaches the disk.