Helium: Initial proto and Syncable interface definition

blimp/net/helium/syncable.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BLIMP_NET_HELIUM_SYNCABLE_H_
+#define BLIMP_NET_HELIUM_SYNCABLE_H_
+
+#include <stdint.h>
+#include <memory>
+
+#include "base/callback.h"
+#include "base/macros.h"
+#include "blimp/net/helium/vector_clock.h"
+
+namespace blimp {
+
+namespace proto {
+class ChangesetMessage;
+}
+
+// Syncable is a base class interface that is used for both SyncableObject and
+// SyncableMember classes.
+//
+// Syncable is something that supports creating and restoring Changesets.
+// Objects exchange Changesets between the client and server to keep
+// their peer counterparts eventually synchronized.
+//
+// 1. Mapping: There is a one-to-one relationship between instances on the
+// client and instances on the engine.
+// 2. Consistency: The values stored in client-engine pairs should eventually be
+// equal.
+//
+// The main difference is that SyncableObject owns its lifetime, whereas
+// SyncableMember depends on its SyncableObject parent.
+//
+// An example for GeoLocation would be:
+// GeoLocation : SyncableObject {
+//   * Frequency : SyncableMember
+//   * Position : SyncableMember
+// }
+//
+// VectorClocks from a SyncableMember can be compared with the VectorClock from
+// the SyncableObject. This reduces the amount of state that needs to be kept.
+
+template <class ChangesetType>
+class Syncable {
+ public:
+  using CreateChangesetCallback =
+      base::Callback<void(std::unique_ptr<ChangesetType> changeset)>;
+
+  virtual ~Syncable() {}
+
+  // Constructs a changeset between the |from| revision and its current state.
+  // The Sync layer will encapsulate the changeset with details since |from|,
+  // but the Object is responsible for including any revision information
+  // additional to that expressed by the VectorClocks, that is necessary to
+  // detect and resolve conflicts.
+  // The computed changeset is returned asynchronously as a return parameter.
+  virtual std::unique_ptr<ChangesetType> CreateChangesetToCurrent(
+      const VectorClock& from) = 0;
+
+  // Asynchronous version of the CreateChangesetToCurrent.
+  // Subclasses are free to implement a more optimal implementation, for example
+  // if a SyncableObject contains |n| SyncableMembers, it can ask to create
+  // the changeset asynchronously from all the SyncableMembers instead of using
+  // the serialized version.
+  // The closure |response_callback| its called with the changeset when its
+  // ready.
+  virtual void CreateChangesetToCurrentAsync(
+      const VectorClock& from,
+      CreateChangesetCallback response_callback) {
+    std::unique_ptr<ChangesetType> changeset = CreateChangesetToCurrent(from);
+    response_callback.Run(std::move(changeset));
+  }
+
+  // Applies a |changeset| given as parameter to the contents of the
+  // Syncable.
+  // The VectorClocks |from| and |to| can be used to detect and resolve
+  // concurrent change conflicts.
+  // The closure |done| its called when the state is applied.
+  virtual void ApplyChangeset(const VectorClock& from,

[Kevin M, 2016/10/05 18:42:45]

I'm not very comfortable with exposing the sync and async Apply variants in the
same base class. We can adapt sync to async, but not the other way around. It
feels wrong to define a method in an abstract interface that is illegal for a
large swath of subclasses.

I recommend moving the sync Apply into SyncableMember, and the async Apply into
SyncableObject, and just removing Apply from here altogether.

Since this is a templated interface, it's not like we can refer to a Syncable
anyways.

+                              const VectorClock& to,
+                              std::unique_ptr<ChangesetType> changeset) = 0;
+
+  // Asynchronous version of ApplyChangeset.
+  // Subclasses are free to implement a more optimal implementation for example
+  // if a SyncableObject contains |n| SyncableMembers, it can ask to apply
+  // the changeset asynchronously from all the SyncableMembers instead of using
+  // the serialized version.
+  // The closure |done| its called when the changeset is applied.
+  virtual void ApplyChangesetAsync(const VectorClock& from,
+                                   const VectorClock& to,
+                                   std::unique_ptr<ChangesetType> changeset,
+                                   const base::Closure& done) {
+    ApplyChangeset(from, to, std::move(changeset));
+    done.Run();
+  }
+
+  // Gives a chance for the Syncable to delete any old data previous to the
+  // |checkpoint|. This is a pretty important method that will remove some
+  // memory pressure for example from the UniqueSet CRDTs. They need to keep
+  // a growing list of added/removed elements over time. With this checkpoint
+  // info they can delete those elements prior to the vector clock specified in
+  // |checkpoint|.
+  virtual void ReleaseCheckpointsBefore(const VectorClock& checkpoint) = 0;
+};
+
+class SyncableObject : public Syncable<proto::ChangesetMessage> {
+ public:
+  explicit SyncableObject(const VectorClock& clock);
+  ~SyncableObject() override {}
+
+  const VectorClock& clock() const { return clock_; }
+
+  VectorClock* mutable_clock() { return &clock_; }
+
+ protected:
+  // The clock is needed in order for the |SyncableMember| objects whenever
+  // they modify their state they update their |last_modified_| value.
+  // The rationale here is use a "global" per SyncableObject clock which makes
+  // state management a lot simpler.
+  VectorClock clock_;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(SyncableObject);
+};
+
+template <class ChangesetType>
+class SyncableMember : public Syncable<ChangesetType> {
+ public:
+  explicit SyncableMember(SyncableObject* parent);
+  ~SyncableMember() override {}
+
+  // Returns true if the object have been modified since |from|.
+  virtual bool ModifiedSince(const VectorClock& from) = 0;
+
+ protected:
+  // Increments the parent clock and returns the new value. Should be used
+  // whenever a SyncableMember updates its state.
+  VectorClock IncrementParentClock();

[perumaal, 2016/10/05 20:42:49]

Why is there an IncrementParentClock / parent_clock still in the member? I
thought the parent manages the members fully?

+
+  // Returns the current value of the vector clock of the parent object (aka
+  // SyncableObject).
+  const VectorClock& parent_clock() const;
+
+ private:
+  SyncableObject* parent_;
+  DISALLOW_COPY_AND_ASSIGN(SyncableMember);
+};
+
+SyncableObject::SyncableObject(const VectorClock& clock) : clock_(clock) {}
+
+template <class ChangesetType>
+SyncableMember<ChangesetType>::SyncableMember(SyncableObject* parent)
+    : parent_(parent) {}
+
+template <class ChangesetType>
+VectorClock SyncableMember<ChangesetType>::IncrementParentClock() {
+  parent_->mutable_clock()->IncrementLocal();
+  return parent_->clock();
+}
+
+template <class ChangesetType>
+const VectorClock& SyncableMember<ChangesetType>::parent_clock() const {
+  return parent_->clock();
+}
+
+}  // namespace blimp
+
+#endif  // BLIMP_NET_HELIUM_SYNCABLE_H_