iOS/Pods/Realm/include/core/realm/impl/cont_transact_hist.hpp

   1 /*************************************************************************
   2  *
   3  * Copyright 2016 Realm Inc.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  **************************************************************************/
  18
  19 #ifndef REALM_IMPL_CONT_TRANSACT_HIST_HPP
  20 #define REALM_IMPL_CONT_TRANSACT_HIST_HPP
  21
  22 #include <cstdint>
  23 #include <memory>
  24
  25 #include <realm/column_binary.hpp>
  26 #include <realm/version_id.hpp>
  27
  28 namespace realm {
  29
  30 class Group;
  31
  32 namespace _impl {
  33
  34 /// Read-only access to history of changesets as needed to enable continuous
  35 /// transactions.
  36 class History {
  37 public:
  38     using version_type = VersionID::version_type;
  39
  40     /// May be called during a read transaction to gain early access to the
  41     /// history as it appears in a new snapshot that succeeds the one bound in
  42     /// the current read transaction.
  43     ///
  44     /// May also be called at other times as long as the caller owns a read lock
  45     /// (SharedGroup::grab_read_lock()) on the Realm for the specified file size
  46     /// and top ref, and the allocator is in a 'free space clean' state
  47     /// (SlabAlloc::is_free_space_clean()).
  48     ///
  49     /// This function may cause a remapping of the Realm file
  50     /// (SlabAlloc::remap()) if it needs to make the new snapshot fully visible
  51     /// in memory.
  52     ///
  53     /// Note that this method of gaining early access to the history in a new
  54     /// snaphot only gives read access. It does not allow for modifications of
  55     /// the history or any other part of the new snapshot. For modifications to
  56     /// be allowed, `Group::m_top` (the parent of the history) would first have
  57     /// to be updated to reflect the new snapshot, but at that time we are no
  58     /// longer in an 'early access' situation.
  59     ///
  60     /// This is not a problem from the point of view of this history interface,
  61     /// as it only contains methods for reading from the history, but some
  62     /// implementations will want to also provide for ways to modify the
  63     /// history, but in those cases, modifications must occur only after the
  64     /// Group accessor has been fully updated to reflect the new snapshot.
  65     virtual void update_early_from_top_ref(version_type new_version, size_t new_file_size, ref_type new_top_ref) = 0;
  66
  67     virtual void update_from_parent(version_type current_version) = 0;
  68
  69     /// Get all changesets between the specified versions. References to those
  70     /// changesets will be made availble in successive entries of `buffer`. The
  71     /// number of retreived changesets is exactly `end_version -
  72     /// begin_version`. If this number is greater than zero, the changeset made
  73     /// avaialable in `buffer[0]` is the one that brought the database from
  74     /// `begin_version` to `begin_version + 1`.
  75     ///
  76     /// It is an error to specify a version (for \a begin_version or \a
  77     /// end_version) that is outside the range [V,W] where V is the version that
  78     /// immediately precedes the first changeset available in the history as the
  79     /// history appears in the **latest** available snapshot, and W is the
  80     /// versionm that immediately succeeds the last changeset available in the
  81     /// history as the history appears in the snapshot bound to the **current**
  82     /// transaction. This restriction is necessary to allow for different kinds
  83     /// of implementations of the history (separate standalone history or
  84     /// history as part of versioned Realm state).
  85     ///
  86     /// The calee retains ownership of the memory referenced by those entries,
  87     /// i.e., the memory referenced by `buffer[i].changeset` is **not** handed
  88     /// over to the caller.
  89     ///
  90     /// This function may be called only during a transaction (prior to
  91     /// initiation of commit operation), and only after a successfull invocation
  92     /// of update_early_from_top_ref(). In that case, the caller may assume that
  93     /// the memory references stay valid for the remainder of the transaction
  94     /// (up until initiation of the commit operation).
  95     virtual void get_changesets(version_type begin_version, version_type end_version, BinaryIterator* buffer) const
  96         noexcept = 0;
  97
  98     /// \brief Specify the version of the oldest bound snapshot.
  99     ///
 100     /// This function must be called by the associated SharedGroup object during
 101     /// each successfully committed write transaction. It must be called before
 102     /// the transaction is finalized (Replication::finalize_commit()) or aborted
 103     /// (Replication::abort_transact()), but after the initiation of the commit
 104     /// operation (Replication::prepare_commit()). This allows history
 105     /// implementations to add new history entries before triming off old ones,
 106     /// and this, in turn, guarantees that the history never becomes empty,
 107     /// except in the initial empty Realm state.
 108     ///
 109     /// The caller must pass the version (\a version) of the oldest snapshot
 110     /// that is currently (or was recently) bound via a transaction of the
 111     /// current session. This gives the history implementation an opportunity to
 112     /// trim off leading (early) history entries.
 113     ///
 114     /// Since this function must be called during a write transaction, there
 115     /// will always be at least one snapshot that is currently bound via a
 116     /// transaction.
 117     ///
 118     /// The caller must guarantee that the passed version (\a version) is less
 119     /// than or equal to `begin_version` in all future invocations of
 120     /// get_changesets().
 121     ///
 122     /// The caller is allowed to pass a version that is less than the version
 123     /// passed in a preceeding invocation.
 124     ///
 125     /// This function should be called as late as possible, to maximize the
 126     /// trimming opportunity, but at a time where the write transaction is still
 127     /// open for additional modifications. This is necessary because some types
 128     /// of histories are stored inside the Realm file.
 129     virtual void set_oldest_bound_version(version_type version) = 0;
 130
 131     /// Get the list of uncommited changes accumulated so far in the current
 132     /// write transaction.
 133     ///
 134     /// The callee retains ownership of the referenced memory. The ownership is
 135     /// not handed over the the caller.
 136     ///
 137     /// This function may be called only during a write transaction (prior to
 138     /// initiation of commit operation). In that case, the caller may assume that the
 139     /// returned memory reference stays valid for the remainder of the transaction (up
 140     /// until initiation of the commit operation).
 141     virtual BinaryData get_uncommitted_changes() noexcept = 0;
 142
 143     virtual void verify() const = 0;
 144
 145     virtual ~History() noexcept
 146     {
 147     }
 148 };
 149
 150 } // namespace _impl
 151 } // namespace realm
 152
 153 #endif // REALM_IMPL_CONTINUOUS_TRANSACTIONS_HISTORY_HPP