Helium: Initial proto and Syncable interface definition

blimp/net/helium/syncable.h

Index: blimp/net/helium/syncable.h
diff --git a/blimp/net/helium/syncable.h b/blimp/net/helium/syncable.h
new file mode 100644
index 0000000000000000000000000000000000000000..3ef4c4be8f024c812f9abc79e2842442a9c4a42d
--- /dev/null
+++ b/blimp/net/helium/syncable.h
@@ -0,0 +1,116 @@
+// 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"
+#include "blimp/net/helium/vector_clock_generator.h"
+
+namespace blimp {
+
+namespace proto {
+class ChangesetMessage;
+}
+
+// Syncable is something that supports creating and restoring Changesets.
+// These objects exchange Changesets between the client and server to keep
+// their peer counterparts eventually synchronized.
+//
+// It provides the following things:
+// 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.
+//
+// Syncable is a base interface that is used for both self contained
+// objects (i.e. Simple register) or objects that the actual truth lives

[Kevin M, 2016/10/05 23:41:30]

or => and

objects which are disconnected replicas of external state?

[scf, 2016/10/06 19:47:16]

Done.

+// externally.
+//
+// Example of self contained objects are the CRDTs for example: LwwRegister,

[Kevin M, 2016/10/05 23:41:29]

Not sure if this is necessary, a cross reference in Code Search can answer this.

[scf, 2016/10/06 19:47:17]

Done.

+// UniqueSet, Fifo, MutableReplicatedSet, etc.
+//
+// Example of an object where the truth resides somewhere else would be:
+// TabList, TabState, GeoLocation, etc.
+//
+
+template <class ChangesetType>
+class Syncable {
+ public:
+  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 Syncable is responsible for including any revision information
+  // additional to that expressed by the VectorClocks, that is necessary to
+  // detect and resolve conflicts.
+  // The changeset is returned as a return value.
+  virtual std::unique_ptr<ChangesetType> CreateChangesetToCurrent(
+      const VectorClock& from) = 0;
+
+  // 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.
+  virtual void ApplyChangeset(const VectorClock& from,
+                              const VectorClock& to,
+                              std::unique_ptr<ChangesetType> changeset) = 0;
+
+  // 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

[Kevin M, 2016/10/05 23:41:30]

The "pretty important method" sentence reads too conversationally and probably
belongs in a doc or in an intro comment block at the top. The interface comments
should be concise and declarative.

[scf, 2016/10/06 19:47:16]

Done.

+  // memory pressure for example from the UniqueSet CRDT. 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;
+
+  // Returns true if the object have been modified since |from|.

[Kevin M, 2016/10/05 23:41:29]

have => has

[scf, 2016/10/06 19:47:17]

Done.

+  virtual bool ModifiedSince(const VectorClock& from) = 0;

[steimel, 2016/10/06 17:44:33]

Should this be const, or will there be CDRTs for which ModifiedSince will change
state?

[scf, 2016/10/06 19:47:17]

good catch, should be const

+};
+
+// Extends the Syncable interface by adding support to synchronize with some

[Kevin M, 2016/10/05 23:41:29]

synchronize => "asynchronously replicate state" ?

[scf, 2016/10/06 19:47:17]

Done.

+// external entity.
+//
+// TwoPhaseSyncable name derives from the fact that the state is both created
+// and applied in two stages:
+//
+// 1. Creation
+// 1.1) PreCreateChangesetToCurrent is called which retrieves the state
+// from an external object and saves locally.
+// 1.2) CreateChangesetToCurrent is called to actually create the changeset.
+//
+// 2. Updating
+// 2.1) ApplyChangeset is called which updates the local state.
+// 2.2) PostApplyChangeset is called to apply the state from the local
+// object into the external object.
+class TwoPhaseSyncable : public Syncable<proto::ChangesetMessage> {
+ public:
+  ~TwoPhaseSyncable() override {}
+
+  // This is before calling CreateChangesetToCurrent to give a change for the
+  // TwoPhaseSyncable to pull the latest changes into its local state.
+  //
+  // The callback |done| should be called once the local instance is ready
+  // to accept the call to CreateChangesetToCurrent.
+  virtual void PreCreateChangesetToCurrent(const VectorClock& from,
+                                           const base::Closure& done) = 0;

[Kevin M, 2016/10/05 23:41:30]

You can use MandatoryCallback<void(void)> now. Or soon. Ugh, I just now realized
that I need to fix the template type signature of that to match the
base::Callback style... will have a CL out for that shortly.

[Kevin M, 2016/10/06 18:16:05]

OK, fixed. Now you can take a MandatoryCallback<void(void)>&&.

[scf, 2016/10/06 19:47:16]

Done.

+
+  // This is called after calling ApplyChangeset to allow the changes to
+  // propagate to the actual external object.
+  //
+  // The callback |done| should be called once the external world object is
+  // updated.
+  virtual void PostApplyChangeset(const VectorClock& from,
+                                  const VectorClock& to,
+                                  const base::Closure& done) = 0;

[Kevin M, 2016/10/06 18:16:06]

Use MandatoryCallback<void(void)>&&?

+};
+
+}  // namespace blimp
+
+#endif  // BLIMP_NET_HELIUM_SYNCABLE_H_