cls_replica_log: add client with user documentation

Signed-off-by: Greg Farnum <greg@inktank.com>

3 files changed, 178 insertions, 1 deletions

diff --git a/src/Makefile.am b/src/Makefile.am
index b497d6605b4..728cee31754 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -626,7 +626,8 @@ noinst_LIBRARIES += libcls_statelog_client.a
 
 libcls_replica_log_client_a_SOURCES = \
 	cls/replica_log/cls_replica_log_types.cc \
-	cls/replica_log/cls_replica_log_ops.cc
+	cls/replica_log/cls_replica_log_ops.cc \
+	cls/replica_log/cls_replica_log_client.cc
 noinst_LIBRARIES += libcls_replica_log_client.a
 
 libcls_rgw_client_a_SOURCES =  \
diff --git a/src/cls/replica_log/cls_replica_log_client.cc b/src/cls/replica_log/cls_replica_log_client.cc
new file mode 100644
index 00000000000..5591389c78a
--- /dev/null
+++ b/src/cls/replica_log/cls_replica_log_client.cc
@@ -0,0 +1,92 @@
+/*
+ * Ceph - scalable distributed file system
+ *
+ * This is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License version 2.1, as published by the Free Software
+ * Foundation.  See file COPYING.
+ */
+
+#include <errno.h>
+
+#include "cls/replica_log/cls_replica_log_ops.h"
+#include "include/rados/librados.hpp"
+
+using namespace librados;
+
+void cls_replica_log_prepare_marker(cls_replica_log_progress_marker& progress,
+                                    const string& entity, const string& marker,
+                                    const utime_t& time,
+                                    const list<pair<string, utime_t> > *entries)
+{
+  progress.entity_id = entity;
+  progress.position_marker = marker;
+  progress.position_time = time;
+  if (entries) {
+    list<pair<string, utime_t> >::const_iterator i;
+    for (i = entries->begin(); i != entries->end(); ++i) {
+      cls_replica_log_item_marker item(i->first, i->second);
+      progress.items.push_back(item);
+    }
+  }
+}
+
+void cls_replica_log_extract_marker(const cls_replica_log_progress_marker& progress,
+                                    string& entity, string& marker,
+                                    utime_t& time,
+                                    list<pair<string, utime_t> >& entries)
+{
+  entity = progress.entity_id;
+  marker = progress.position_marker;
+  time = progress.position_time;
+  list<cls_replica_log_item_marker>::const_iterator i;
+  for (i = progress.items.begin(); i != progress.items.end(); ++i) {
+    entries.push_back(make_pair(i->item_name, i->item_timestamp));
+  }
+}
+
+void cls_replica_log_update_bound(librados::ObjectWriteOperation& o,
+                                  const cls_replica_log_progress_marker& progress)
+{
+  cls_replica_log_set_marker_op op(progress);
+  bufferlist in;
+  ::encode(op, in);
+  o.exec("replica_log", "set", in);
+}
+
+void cls_replica_log_delete_bound(librados::ObjectWriteOperation& o,
+                                  const string& entity)
+{
+  cls_replica_log_delete_marker_op op(entity);
+  bufferlist in;
+  ::encode(op, in);
+  o.exec("replica_log", "delete", in);
+}
+
+int cls_replica_log_get_bounds(librados::IoCtx& io_ctx, const string& oid,
+                                string& position_marker,
+                                utime_t& oldest_time,
+                                list<cls_replica_log_progress_marker>& markers)
+{
+  bufferlist in;
+  bufferlist out;
+  cls_replica_log_get_bounds_op op;
+  ::encode(op, in);
+  int r = io_ctx.exec(oid, "replica_log", "get", in, out);
+  if (r < 0)
+    return r;
+
+  cls_replica_log_get_bounds_ret ret;
+  try {
+    bufferlist::iterator i = out.begin();
+    ::decode(ret, i);
+  } catch (buffer::error& err) {
+    return -EIO;
+  }
+
+  position_marker = ret.position_marker;
+  oldest_time = ret.oldest_time;
+  markers = ret.markers;
+
+  return 0;
+}
diff --git a/src/cls/replica_log/cls_replica_log_client.h b/src/cls/replica_log/cls_replica_log_client.h
new file mode 100644
index 00000000000..d1a83e08ff6
--- /dev/null
+++ b/src/cls/replica_log/cls_replica_log_client.h
@@ -0,0 +1,84 @@
+/*
+ * Ceph - scalable distributed file system
+ *
+ * This is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License version 2.1, as published by the Free Software
+ * Foundation.  See file COPYING.
+ *
+ * Copyright 2013 Inktank
+ */
+
+#ifndef CLS_REPLICA_LOG_CLIENT_H_
+#define CLS_REPLICA_LOG_CLIENT_H_
+
+#include "include/rados/librados.hpp"
+#include "cls_replica_log_types.h"
+
+/**
+ * Prepare a progress marker object to send out.
+ *
+ * @param progress The marker object to prepare
+ * @param entity The ID of the entity setting the progress
+ * @param marker The marker key the entity has gotten to
+ * @param time The timestamp associated with the marker
+ * param entries A list of in-progress entries prior to the marker
+ */
+void cls_replica_log_prepare_marker(cls_replica_log_progress_marker& progress,
+                                    const string& entity, const string& marker,
+                                    const utime_t& time,
+                                    const list<pair<string, utime_t> > *entries);
+
+/**
+ * Extract a progress marker object into its components.
+ *
+ * @param progress The marker object to extract data from
+ * @param entity [out] The ID of the entity the progress is associated with
+ * @param marker [out] The marker key the entity has gotten to
+ * @param time [out] The timestamp associated with the marker
+ * @param entries [out] List of in-progress entries prior to the marker
+ */
+void cls_replica_log_extract_marker(const cls_replica_log_progress_marker& progress,
+                                    string& entity, string& marker,
+                                    utime_t& time,
+                                    list<pair<string, utime_t> >& entries);
+
+/**
+ * Add a progress marker update to a write op. The op will return 0 on
+ * success, -EEXIST if the marker conflicts with an existing one, or
+ * -EINVAL if the marker is in conflict (ie, before) the daemon's existing
+ * marker.
+ *
+ * @param op The op to add the update to
+ * @param progress The progress marker to send
+ */
+void cls_replica_log_update_bound(librados::ObjectWriteOperation& op,
+                                  const cls_replica_log_progress_marker& progress);
+
+/**
+ * Remove an entity's progress marker from the replica log. The op will return
+ * 0 on success, -ENOENT if the entity does not exist on the replica log, or
+ * -ENOTEMPTY if the items list on the marker is not empty.
+ *
+ * @param op The op to add the delete to
+ * @param entity The entity whose progress should be removed
+ */
+void cls_replica_log_delete_bound(librados::ObjectWriteOperation& op,
+                                  const string& entity);
+
+/**
+ * Read the bounds on a replica log.
+ *
+ * @param io_ctx The IoCtx to use for the read
+ * @param oid The oid to direct the read to
+ * @param position_marker [out] The lowest marker key that has been reached
+ * @param oldest_time [out] Timestamp corresponding to the position marker or
+ * oldest in-progress item.
+ * @param markers [out] List of progress markers for individual daemons
+ */
+int cls_replica_log_get_bounds(librados::IoCtx& io_ctx, const string& oid,
+                                string& position_marker,
+                                utime_t& oldest_time,
+                                list<cls_replica_log_progress_marker>& markers);
+
+#endif /* CLS_REPLICA_LOG_CLIENT_H_ */