transaction.h

Go to the documentation of this file.

// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_TRANSACTION_H
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_TRANSACTION_H

#include "google/cloud/spanner/internal/transaction_impl.h"
#include "google/cloud/spanner/timestamp.h"
#include "google/cloud/spanner/version.h"
#include <google/spanner/v1/transaction.pb.h>
#include <chrono>
#include <memory>
#include <string>

namespace google {
namespace cloud {
namespace spanner {
inline namespace SPANNER_CLIENT_NS {

class Transaction;  // defined below

// Internal forward declarations to befriend.
namespace internal {
template <typename T>
Transaction MakeSingleUseTransaction(T&&);
template <typename Functor>
VisitInvokeResult<Functor> Visit(Transaction, Functor&&);
Transaction MakeTransactionFromIds(std::string session_id,
                                   std::string transaction_id);
}  // namespace internal

class Transaction {
 public:
  class ReadOnlyOptions {
   public:
    // Strong: Guarantees visibility of the effects of all transactions that
    // committed before the start of the reads.
    ReadOnlyOptions();

    // Exact Staleness: Executes all reads at `read_timestamp`.
    explicit ReadOnlyOptions(Timestamp read_timestamp);

    // Exact Staleness: Executes all reads at a timestamp `exact_staleness`
    // old. The actual timestamp is chosen soon after the reads are started.
    explicit ReadOnlyOptions(std::chrono::nanoseconds exact_staleness);

   private:
    friend Transaction;
    google::spanner::v1::TransactionOptions_ReadOnly ro_opts_;
  };

  class ReadWriteOptions {
   public:
    // There are currently no read-write options.
    ReadWriteOptions();

   private:
    friend Transaction;
    google::spanner::v1::TransactionOptions_ReadWrite rw_opts_;
  };

  class SingleUseOptions {
   public:
    // Strong or Exact Staleness: See ReadOnlyOptions.
    // NOLINTNEXTLINE(google-explicit-constructor)
    SingleUseOptions(ReadOnlyOptions opts);

    // Bounded Staleness: Executes all reads at a timestamp that is not
    // before `min_read_timestamp`.
    explicit SingleUseOptions(Timestamp min_read_timestamp);

    // Bounded Staleness: Executes all reads at a timestamp that is not
    // before `NOW - max_staleness`.
    explicit SingleUseOptions(std::chrono::nanoseconds max_staleness);

   private:
    friend Transaction;
    google::spanner::v1::TransactionOptions_ReadOnly ro_opts_;
  };


  explicit Transaction(ReadOnlyOptions opts);
  explicit Transaction(ReadWriteOptions opts);
  Transaction(Transaction const& txn, ReadWriteOptions opts);

  ~Transaction();

  Transaction(Transaction&&) = default;
  Transaction& operator=(Transaction&&) = default;
  Transaction(Transaction const&) = default;
  Transaction& operator=(Transaction const&) = default;

  friend bool operator==(Transaction const& a, Transaction const& b) {
    return a.impl_ == b.impl_;
  }
  friend bool operator!=(Transaction const& a, Transaction const& b) {
    return !(a == b);
  }

 private:
  // Friendship for access by internal helpers.
  template <typename T>
  friend Transaction internal::MakeSingleUseTransaction(T&&);
  template <typename Functor>
  friend internal::VisitInvokeResult<Functor> internal::Visit(Transaction,
                                                              Functor&&);
  friend Transaction internal::MakeTransactionFromIds(
      std::string session_id, std::string transaction_id);

  // Construction of a single-use transaction.
  explicit Transaction(SingleUseOptions opts);
  // Construction of a transaction with existing IDs.
  Transaction(std::string session_id, std::string transaction_id);

  std::shared_ptr<internal::TransactionImpl> impl_;
};

inline Transaction MakeReadOnlyTransaction(
    Transaction::ReadOnlyOptions opts = {}) {
  return Transaction(std::move(opts));
}

inline Transaction MakeReadWriteTransaction(
    Transaction::ReadWriteOptions opts = {}) {
  return Transaction(std::move(opts));
}

inline Transaction MakeReadWriteTransaction(
    Transaction const& txn, Transaction::ReadWriteOptions opts = {}) {
  return Transaction(txn, std::move(opts));
}

namespace internal {

template <typename T>
Transaction MakeSingleUseTransaction(T&& opts) {
  // Requires that `opts` is implicitly convertible to SingleUseOptions.
  Transaction::SingleUseOptions su_opts = std::forward<T>(opts);
  return Transaction(std::move(su_opts));
}

template <typename Functor>
// Pass `txn` by value, despite being used only once. This avoids the
// possibility of `txn` being destroyed by `f` before `Visit()` can
// return. Therefore, ...
// NOLINTNEXTLINE(performance-unnecessary-value-param)
VisitInvokeResult<Functor> Visit(Transaction txn, Functor&& f) {
  return txn.impl_->Visit(std::forward<Functor>(f));
}

}  // namespace internal
}  // namespace SPANNER_CLIENT_NS
}  // namespace spanner
}  // namespace cloud
}  // namespace google

#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_TRANSACTION_H