objclass-sdk: create SDK for Ceph object classes

Creates an installable version of "src/include/rados/objclass.h" that allows
object classes to be built outside of the Ceph tree. cls_sdk is an example
of such an object class.

Signed-off-by: Neha Ojha <nojha@redhat.com>

ceph.spec.in

@@ -718,6 +718,15 @@ This package contains the Java libraries for the Ceph File System.
 
 %endif
 
+%package -n rados-objclass-devel
+Summary:        RADOS object class development kit
+Group:          Development/Libraries
+License:        LGPL-2.0
+Requires:       librados2-devel = %{epoch}:%{version}-%{release}
+%description -n rados-objclass-devel
+This package contains libraries and headers needed to develop RADOS object
+class plugins.
+
 %if 0%{with selinux}
 
 %package selinux
@@ -1642,6 +1651,11 @@ ln -sf %{_libdir}/librbd.so.1 /usr/lib64/qemu/librbd.so.1
 %{_javadir}/libcephfs-test.jar
 %endif
 
+%files -n rados-objclass-devel
+%defattr(-,root,root,-)
+%dir %{_includedir}/rados
+%{_includedir}/rados/objclass.h
+
 %if 0%{with selinux}
 %files selinux
 %defattr(-,root,root,-)

debian/control

@@ -824,3 +824,11 @@ Section: java
 Depends: libcephfs2 (= ${binary:Version}), ${java:Depends},
          ${misc:Depends}, ${shlibs:Depends}
 Description: Java Native Interface library for CephFS Java bindings
+
+Package: rados-objclass-dev
+Architecture: linux-any
+Section: libdevel
+Depends: librados-dev (= ${binary:Version}) ${misc:Depends}
+Description: RADOS object class development kit.
+ .
+ This package contains development files needed for building RADOS object class plugins.

debian/rados-objclass-dev.install

@@ -0,0 +1 @@
+usr/include/rados/objclass.h

doc/rados/api/index.rst

@@ -18,4 +18,5 @@ Ceph, your own interface to Ceph, etc.).
    Introduction to librados <librados-intro>
    librados (C) <librados>
    librados (C++) <libradospp>
-   librados (Python) <python>
+   librados (Python) <python>
+   object class <objclass-sdk>

doc/rados/api/objclass-sdk.rst

@@ -0,0 +1,37 @@
+===========================
+SDK for Ceph Object Classes
+===========================
+
+`Ceph` can be extended by creating shared object classes called `Ceph Object 
+Classes`. The existing framework to build these object classes has dependencies 
+on the internal functionality of `Ceph`, which restricts users to build object 
+classes within the tree. The aim of this project is to create an independent 
+object class interface, which can be used to build object classes outside the 
+`Ceph` tree. This allows us to have two types of object classes, 1) those that 
+have in-tree dependencies and reside in the tree and 2) those that can make use 
+of the `Ceph Object Class SDK framework` and can be built outside of the `Ceph` 
+tree because they do not depend on any internal implementation of `Ceph`. This 
+project decouples object class development from Ceph and encourages creation 
+and distribution of object classes as packages.
+
+In order to demonstrate the use of this framework, we have provided an example 
+called ``cls_sdk``, which is a very simple object class that makes use of the 
+SDK framework. This object class resides in the ``src/cls`` directory. 
+
+Installing objclass.h
+---------------------
+
+The object class interface that enables out-of-tree development of object 
+classes resides in ``src/include/rados/`` and gets installed with `Ceph` 
+installation. After running ``make install``, you should be able to see it 
+in ``<prefix>/include/rados``. ::
+
+        ls /usr/local/include/rados
+
+Using the SDK example
+---------------------
+
+The ``cls_sdk`` object class resides in ``src/cls/sdk/``. This gets built and 
+loaded into Ceph, with the Ceph build process. You can run the 
+``ceph_test_cls_sdk`` unittest, which resides in ``src/test/cls_sdk/``, 
+to test this class.

qa/workunits/cls/test_cls_sdk.sh

@@ -0,0 +1,5 @@
+#!/bin/sh -e
+
+ceph_test_cls_sdk
+
+exit 0

src/cls/CMakeLists.txt

@@ -3,6 +3,11 @@
 set(cls_dir ${CMAKE_INSTALL_LIBDIR}/rados-classes)
 set(cls_embedded_srcs)
 
+# cls_sdk
+add_library(cls_sdk SHARED sdk/cls_sdk.cc)
+set_target_properties(cls_sdk PROPERTIES VERSION "1.0.0" SOVERSION "1")
+install(TARGETS cls_sdk DESTINATION ${cls_dir})
+
 # cls_hello
 set(cls_hello_srcs hello/cls_hello.cc)
 add_library(cls_hello SHARED ${cls_hello_srcs})

src/cls/sdk/cls_sdk.cc

@@ -0,0 +1,131 @@
+/*
+ * This is an example RADOS object class built using only the Ceph SDK interface.
+ */
+#include "include/rados/objclass.h"
+
+CLS_VER(1,0)
+CLS_NAME(sdk)
+
+cls_handle_t h_class;
+cls_method_handle_t h_test_coverage_write;
+cls_method_handle_t h_test_coverage_replay;
+
+/**
+ * test_coverage_write - a "write" method that creates an object
+ *
+ * This method modifies the object by making multiple write calls (write,
+ * setxattr and set_val).
+ */
+static int test_coverage_write(cls_method_context_t hctx, bufferlist *in, bufferlist *out)
+{
+  // create the object
+  int ret = cls_cxx_create(hctx, false);
+  if (ret < 0) {
+    CLS_LOG(0, "ERROR: %s(): cls_cxx_create returned %d", __func__, ret);	  
+    return ret;
+  }
+
+  uint64_t size;
+  // get the size of the object
+  ret = cls_cxx_stat(hctx, &size, NULL);
+  if (ret < 0)
+    return ret;
+
+  std::string c = "test";
+  bufferlist bl;
+  bl.append(c);
+
+  // write to the object
+  ret = cls_cxx_write(hctx, 0, bl.length(), &bl);
+  if (ret < 0)
+    return ret;
+
+  uint64_t new_size;
+  // get the new size of the object
+  ret = cls_cxx_stat(hctx, &new_size, NULL);
+  if (ret < 0)
+    return ret;
+
+  // make some change to the xattr
+  ret = cls_cxx_setxattr(hctx, "foo", &bl);
+  if (ret < 0)
+    return ret;
+
+  // make some change to the omap
+  ret = cls_cxx_map_set_val(hctx, "foo", &bl);
+  if (ret < 0)
+    return ret;
+
+  return 0;
+}
+
+/**
+ * test_coverage_replay - a "read" method to retrieve previously written data
+ *
+ * This method reads the object by making multiple read calls (read, getxattr 
+ * and get_val). It also removes the object after reading.
+ */
+
+static int test_coverage_replay(cls_method_context_t hctx, bufferlist *in, bufferlist *out)
+{
+  CLS_LOG(0, "reading already written object");
+  uint64_t size;
+  // get the size of the object
+  int ret = cls_cxx_stat(hctx, &size, NULL);
+  if (ret < 0)
+    return ret;
+
+  bufferlist bl;
+  // read the object entry
+  ret = cls_cxx_read(hctx, 0, size, &bl);
+  if (ret < 0)
+    return ret;
+
+  // if the size is incorrect 
+  if (bl.length() != size)
+    return -EIO;
+
+  bl.clear();
+
+  // read xattr entry
+  ret = cls_cxx_getxattr(hctx, "foo", &bl);
+  if (ret < 0)
+    return ret;
+
+  // if the size is incorrect
+  if (bl.length() != size)
+    return -EIO;
+
+  bl.clear();
+
+  // read omap entry
+  ret = cls_cxx_map_get_val(hctx, "foo", &bl);
+  if (ret < 0)
+    return ret;
+
+  // if the size is incorrect
+  if (bl.length() != size)
+    return -EIO;
+
+  // remove the object
+  ret = cls_cxx_remove(hctx);
+  if (ret < 0)
+    return ret;
+
+  return 0;
+}
+
+void __cls_init()
+{
+  CLS_LOG(0, "loading cls_sdk");
+
+  cls_register("sdk", &h_class);
+
+  cls_register_cxx_method(h_class, "test_coverage_write",
+      CLS_METHOD_RD|CLS_METHOD_WR,
+      test_coverage_write, &h_test_coverage_write);
+
+  cls_register_cxx_method(h_class, "test_coverage_replay",
+      CLS_METHOD_RD|CLS_METHOD_WR,
+      test_coverage_replay, &h_test_coverage_replay);
+}

src/include/CMakeLists.txt

@@ -8,6 +8,7 @@ install(FILES rados/librados.h
   memory.h
   page.h
   crc32c.h
+  rados/objclass.h
   DESTINATION include/rados)
 install(FILES
   radosstriper/libradosstriper.h