Repository: ceph/go-ceph
Pull request #706 (2022-06-13 17:51:09)

rados: stabilze some APIs
No issues raised for these apis during the preview period so making the apis stable in their expected stable version.


phlogistonjohn: @mergifyio rebase
mergify[bot]: > rebase

#### ✅ Branch has been successfully rebased



<!--
DO NOT EDIT
-*- Mergify Payload -*-
{"command": "rebase", "conclusion": "success"}
-*- Mergify Payload End -*-
-->

phlogistonjohn: @mergifyio rebase
mergify[bot]: > rebase

#### ✅ Branch has been successfully rebased



<!--
DO NOT EDIT
-*- Mergify Payload -*-
{"command": "rebase", "conclusion": "success"}
-*- Mergify Payload End -*-
-->

phlogistonjohn: @Mergifyio requeue
mergify[bot]: > requeue

#### ✅ The queue state of this pull request has been cleaned. It can be re-embarked automatically



<!--
DO NOT EDIT
-*- Mergify Payload -*-
{"command": "requeue", "conclusion": "success"}
-*- Mergify Payload End -*-
-->


Patch:
diff --git a/docs/api-status.json b/docs/api-status.json
index aa84b61..4065c68 100644
--- a/docs/api-status.json
+++ b/docs/api-status.json
@@ -937,117 +937,81 @@
       {
         "name": "WriteOp.CmpExt",
         "comment": "CmpExt ensures that given object range (extent) satisfies comparison.\n\nImplements:\n void rados_write_op_cmpext(rados_write_op_t write_op,\n                            const char * cmp_buf,\n                            size_t cmp_len,\n                            uint64_t off,\n                            int * prval);\n"
-      }
-    ],
-    "preview_api": [
-      {
-        "name": "ReadOp.Read",
-        "comment": "Read bytes from offset into buffer.\nlen(buffer) is the maximum number of bytes read from the object.\nbuffer[:ReadOpReadStep.BytesRead] then contains object data.\n\nImplements:\n void rados_read_op_read(rados_read_op_t read_op,\n                         uint64_t offset,\n                         size_t len,\n                         char * buffer,\n                         size_t * bytes_read,\n                         int * prval)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
       },
       {
-        "name": "WriteOp.Remove",
-        "comment": "Remove object.\n\nImplements:\n void rados_write_op_remove(rados_write_op_t write_op)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "IOContext.Watch",
+        "comment": "Watch creates a Watcher for the specified object.\n\nA Watcher receives all notifications that are sent to the object on which it\nhas been created. It exposes two read-only channels: Events() receives all\nthe NotifyEvents and Errors() receives all occuring errors. A typical code\ncreating a Watcher could look like this:\n\n watcher, err := ioctx.Watch(oid)\n go func() { // event handler\n   for ne := range watcher.Events() {\n     ...\n     ne.Ack([]byte(\"response data...\"))\n     ...\n   }\n }()\n go func() { // error handler\n   for err := range watcher.Errors() {\n     ... handle err ...\n   }\n }()\n\nCAUTION: the Watcher references the IOContext in which it has been created.\nTherefore all watchers must be deleted with the Delete() method before the\nIOContext is being destroyed.\n\nImplements:\n int rados_watch2(rados_ioctx_t io, const char* o, uint64_t* cookie,\n   rados_watchcb2_t watchcb, rados_watcherrcb_t watcherrcb, void* arg)\n"
       },
       {
-        "name": "ReadOp.AssertVersion",
-        "comment": "Ensure that the object exists and that its internal version number is equal\nto \"ver\" before reading. \"ver\" should be a version number previously\nobtained with IOContext.GetLastVersion().\n\nImplements:\n void rados_read_op_assert_version(rados_read_op_t read_op,\n                                   uint64_t ver)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "IOContext.WatchWithTimeout",
+        "comment": "WatchWithTimeout creates a watcher on an object. Same as Watcher(), but\ndifferent timeout than the default can be specified.\n\nImplements:\n int rados_watch3(rados_ioctx_t io, const char *o, uint64_t *cookie,\n\t  rados_watchcb2_t watchcb, rados_watcherrcb_t watcherrcb, uint32_t timeout,\n\t  void *arg);\n"
       },
       {
-        "name": "WriteOp.AssertVersion",
-        "comment": "Ensure that the object exists and that its internal version number is equal\nto \"ver\" before writing. \"ver\" should be a version number previously\nobtained with IOContext.GetLastVersion().\n\nImplements:\n void rados_read_op_assert_version(rados_read_op_t read_op,\n                                   uint64_t ver)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Watcher.ID",
+        "comment": "ID returns the WatcherId of the Watcher\n"
       },
       {
-        "name": "WriteOp.SetXattr",
-        "comment": "Set an xattr.\n\nImplements:\n void rados_write_op_setxattr(rados_write_op_t write_op,\n                              const char * name,\n                              const char * value,\n                              size_t value_len)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Watcher.Events",
+        "comment": "Events returns a read-only channel, that receives all notifications that are\nsent to the object of the Watcher.\n"
       },
       {
-        "name": "ReadOpOmapGetValsByKeysStep.Next",
-        "comment": "Next gets the next omap key/value pair referenced by\nReadOpOmapGetValsByKeysStep's internal iterator.\nIf there are no more elements to retrieve, (nil, nil) is returned.\nMay be called only after Operate() finished.\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Watcher.Errors",
+        "comment": "Errors returns a read-only channel, that receives all errors for the Watcher.\n"
       },
       {
-        "name": "ReadOp.GetOmapValuesByKeys",
-        "comment": "GetOmapValuesByKeys starts iterating over specific key/value pairs.\n\nImplements:\n void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op,\n                                           char const * const * keys,\n                                           size_t num_keys,\n                                           const size_t * key_lens,\n                                           rados_omap_iter_t * iter,\n                                           int * prval)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Watcher.Check",
+        "comment": "Check on the status of a Watcher.\n\nReturns the time since it was last confirmed. If there is an error, the\nWatcher is no longer valid, and should be destroyed with the Delete() method.\n\nImplements:\n int rados_watch_check(rados_ioctx_t io, uint64_t cookie)\n"
       },
       {
-        "name": "IOContext.Watch",
-        "comment": "Watch creates a Watcher for the specified object.\n\nA Watcher receives all notifications that are sent to the object on which it\nhas been created. It exposes two read-only channels: Events() receives all\nthe NotifyEvents and Errors() receives all occuring errors. A typical code\ncreating a Watcher could look like this:\n\n watcher, err := ioctx.Watch(oid)\n go func() { // event handler\n   for ne := range watcher.Events() {\n     ...\n     ne.Ack([]byte(\"response data...\"))\n     ...\n   }\n }()\n go func() { // error handler\n   for err := range watcher.Errors() {\n     ... handle err ...\n   }\n }()\n\nCAUTION: the Watcher references the IOContext in which it has been created.\nTherefore all watchers must be deleted with the Delete() method before the\nIOContext is being destroyed.\n\nImplements:\n int rados_watch2(rados_ioctx_t io, const char* o, uint64_t* cookie,\n   rados_watchcb2_t watchcb, rados_watcherrcb_t watcherrcb, void* arg)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Watcher.Delete",
+        "comment": "Delete the watcher. This closes both the event and error channel.\n\nImplements:\n int rados_unwatch2(rados_ioctx_t io, uint64_t cookie)\n"
       },
       {
-        "name": "IOContext.WatchWithTimeout",
-        "comment": "WatchWithTimeout creates a watcher on an object. Same as Watcher(), but\ndifferent timeout than the default can be specified.\n\nImplements:\n int rados_watch3(rados_ioctx_t io, const char *o, uint64_t *cookie,\n\t  rados_watchcb2_t watchcb, rados_watcherrcb_t watcherrcb, uint32_t timeout,\n\t  void *arg);\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "IOContext.Notify",
+        "comment": "Notify sends a notification with the provided data to all Watchers of the\nspecified object.\n\nCAUTION: even if the error is not nil. the returned slices\nmight still contain data.\n"
       },
       {
-        "name": "Watcher.ID",
-        "comment": "ID returns the WatcherId of the Watcher\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "IOContext.NotifyWithTimeout",
+        "comment": "NotifyWithTimeout is like Notify() but with a different timeout than the\ndefault.\n\nImplements:\n int rados_notify2(rados_ioctx_t io, const char* o, const char* buf, int buf_len,\n   uint64_t timeout_ms, char** reply_buffer, size_t* reply_buffer_len)\n"
       },
       {
-        "name": "Watcher.Events",
-        "comment": "Events returns a read-only channel, that receives all notifications that are\nsent to the object of the Watcher.\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "NotifyEvent.Ack",
+        "comment": "Ack sends an acknowledgement with the specified response data to the notfier\nof the NotifyEvent. If a notify is not ack'ed, the originating Notify() call\nblocks and eventiually times out.\n\nImplements:\n int rados_notify_ack(rados_ioctx_t io, const char *o, uint64_t notify_id,\n   uint64_t cookie, const char *buf, int buf_len)\n"
       },
       {
-        "name": "Watcher.Errors",
-        "comment": "Errors returns a read-only channel, that receives all errors for the Watcher.\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "Conn.WatcherFlush",
+        "comment": "WatcherFlush flushes all pending notifications of the cluster.\n\nImplements:\n int rados_watch_flush(rados_t cluster)\n"
       },
       {
-        "name": "Watcher.Check",
-        "comment": "Check on the status of a Watcher.\n\nReturns the time since it was last confirmed. If there is an error, the\nWatcher is no longer valid, and should be destroyed with the Delete() method.\n\nImplements:\n int rados_watch_check(rados_ioctx_t io, uint64_t cookie)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "ReadOp.AssertVersion",
+        "comment": "AssertVersion ensures that the object exists and that its internal version\nnumber is equal to \"ver\" before reading. \"ver\" should be a version number\npreviously obtained with IOContext.GetLastVersion().\n\nImplements:\n void rados_read_op_assert_version(rados_read_op_t read_op,\n                                   uint64_t ver)\n"
       },
       {
-        "name": "Watcher.Delete",
-        "comment": "Delete the watcher. This closes both the event and error channel.\n\nImplements:\n int rados_unwatch2(rados_ioctx_t io, uint64_t cookie)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "WriteOp.AssertVersion",
+        "comment": "AssertVersion ensures that the object exists and that its internal version\nnumber is equal to \"ver\" before writing. \"ver\" should be a version number\npreviously obtained with IOContext.GetLastVersion().\n\nImplements:\n void rados_read_op_assert_version(rados_read_op_t read_op,\n                                   uint64_t ver)\n"
       },
       {
-        "name": "IOContext.Notify",
-        "comment": "Notify sends a notification with the provided data to all Watchers of the\nspecified object.\n\nCAUTION: even if the error is not nil. the returned slices\nmight still contain data.\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "WriteOp.Remove",
+        "comment": "Remove object.\n\nImplements:\n void rados_write_op_remove(rados_write_op_t write_op)\n"
       },
       {
-        "name": "IOContext.NotifyWithTimeout",
-        "comment": "NotifyWithTimeout is like Notify() but with a different timeout than the\ndefault.\n\nImplements:\n int rados_notify2(rados_ioctx_t io, const char* o, const char* buf, int buf_len,\n   uint64_t timeout_ms, char** reply_buffer, size_t* reply_buffer_len)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "WriteOp.SetXattr",
+        "comment": "SetXattr sets an xattr.\n\nImplements:\n void rados_write_op_setxattr(rados_write_op_t write_op,\n                              const char * name,\n                              const char * value,\n                              size_t value_len)\n"
       },
       {
-        "name": "NotifyEvent.Ack",
-        "comment": "Ack sends an acknowledgement with the specified response data to the notfier\nof the NotifyEvent. If a notify is not ack'ed, the originating Notify() call\nblocks and eventiually times out.\n\nImplements:\n int rados_notify_ack(rados_ioctx_t io, const char *o, uint64_t notify_id,\n   uint64_t cookie, const char *buf, int buf_len)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "ReadOpOmapGetValsByKeysStep.Next",
+        "comment": "Next gets the next omap key/value pair referenced by\nReadOpOmapGetValsByKeysStep's internal iterator.\nIf there are no more elements to retrieve, (nil, nil) is returned.\nMay be called only after Operate() finished.\n"
       },
       {
-        "name": "Conn.WatcherFlush",
-        "comment": "WatcherFlush flushes all pending notifications of the cluster.\n\nImplements:\n int rados_watch_flush(rados_t cluster)\n",
-        "added_in_version": "v0.14.0",
-        "expected_stable_version": "v0.16.0"
+        "name": "ReadOp.GetOmapValuesByKeys",
+        "comment": "GetOmapValuesByKeys starts iterating over specific key/value pairs.\n\nImplements:\n void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op,\n                                           char const * const * keys,\n                                           size_t num_keys,\n                                           const size_t * key_lens,\n                                           rados_omap_iter_t * iter,\n                                           int * prval)\n"
       },
+      {
+        "name": "ReadOp.Read",
+        "comment": "Read bytes from offset into buffer.\nlen(buffer) is the maximum number of bytes read from the object.\nbuffer[:ReadOpReadStep.BytesRead] then contains object data.\n\nImplements:\n void rados_read_op_read(rados_read_op_t read_op,\n                         uint64_t offset,\n                         size_t len,\n                         char * buffer,\n                         size_t * bytes_read,\n                         int * prval)\n"
+      }
+    ],
+    "preview_api": [
       {
         "name": "IOContext.SetLocator",
         "comment": "SetLocator sets the key for mapping objects to pgs within an io context.\nUntil a different locator key is set, all objects in this io context will be placed in the same pg.\nTo reset the locator, an empty string must be set.\n\nImplements:\n void rados_ioctx_locator_set_key(rados_ioctx_t io, const char *key);\n",
diff --git a/docs/api-status.md b/docs/api-status.md
index bdb34ba..55ffacd 100644
--- a/docs/api-status.md
+++ b/docs/api-status.md
@@ -25,24 +25,6 @@ FSAdmin.DisableModule | v0.14.0 | v0.16.0 |
 
 Name | Added in Version | Expected Stable Version | 
 ---- | ---------------- | ----------------------- | 
-ReadOp.Read | v0.14.0 | v0.16.0 | 
-WriteOp.Remove | v0.14.0 | v0.16.0 | 
-ReadOp.AssertVersion | v0.14.0 | v0.16.0 | 
-WriteOp.AssertVersion | v0.14.0 | v0.16.0 | 
-WriteOp.SetXattr | v0.14.0 | v0.16.0 | 
-ReadOpOmapGetValsByKeysStep.Next | v0.14.0 | v0.16.0 | 
-ReadOp.GetOmapValuesByKeys | v0.14.0 | v0.16.0 | 
-IOContext.Watch | v0.14.0 | v0.16.0 | 
-IOContext.WatchWithTimeout | v0.14.0 | v0.16.0 | 
-Watcher.ID | v0.14.0 | v0.16.0 | 
-Watcher.Events | v0.14.0 | v0.16.0 | 
-Watcher.Errors | v0.14.0 | v0.16.0 | 
-Watcher.Check | v0.14.0 | v0.16.0 | 
-Watcher.Delete | v0.14.0 | v0.16.0 | 
-IOContext.Notify | v0.14.0 | v0.16.0 | 
-IOContext.NotifyWithTimeout | v0.14.0 | v0.16.0 | 
-NotifyEvent.Ack | v0.14.0 | v0.16.0 | 
-Conn.WatcherFlush | v0.14.0 | v0.16.0 | 
 IOContext.SetLocator | v0.15.0 | v0.17.0 | 
 
 ## Package: rbd
diff --git a/rados/rados_read_op_assert_version.go b/rados/rados_read_op_assert_version.go
index 4aace1c..e58cd18 100644
--- a/rados/rados_read_op_assert_version.go
+++ b/rados/rados_read_op_assert_version.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/rados_write_op_assert_version.go b/rados/rados_write_op_assert_version.go
index 4ad3e99..0a4d510 100644
--- a/rados/rados_write_op_assert_version.go
+++ b/rados/rados_write_op_assert_version.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/rados_write_op_remove.go b/rados/rados_write_op_remove.go
index 7d630e0..ce6b1bf 100644
--- a/rados/rados_write_op_remove.go
+++ b/rados/rados_write_op_remove.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/rados_write_op_setxattr.go b/rados/rados_write_op_setxattr.go
index f851f1b..828d2d5 100644
--- a/rados/rados_write_op_setxattr.go
+++ b/rados/rados_write_op_setxattr.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/read_op_omap_get_vals_by_keys.go b/rados/read_op_omap_get_vals_by_keys.go
index 4e536ef..8ca9a32 100644
--- a/rados/read_op_omap_get_vals_by_keys.go
+++ b/rados/read_op_omap_get_vals_by_keys.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/read_op_read.go b/rados/read_op_read.go
index da62c2a..47e0298 100644
--- a/rados/read_op_read.go
+++ b/rados/read_op_read.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 // #cgo LDFLAGS: -lrados
diff --git a/rados/watcher.go b/rados/watcher.go
index e2559a9..0fc362c 100644
--- a/rados/watcher.go
+++ b/rados/watcher.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 /*


Test patch:
diff --git a/rados/rados_read_op_assert_version_test.go b/rados/rados_read_op_assert_version_test.go
index fea9383..43d412e 100644
--- a/rados/rados_read_op_assert_version_test.go
+++ b/rados/rados_read_op_assert_version_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/rados_write_op_assert_version_test.go b/rados/rados_write_op_assert_version_test.go
index 854d624..a9dfe1d 100644
--- a/rados/rados_write_op_assert_version_test.go
+++ b/rados/rados_write_op_assert_version_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/rados_write_op_remove_test.go b/rados/rados_write_op_remove_test.go
index 600bd2d..51378a4 100644
--- a/rados/rados_write_op_remove_test.go
+++ b/rados/rados_write_op_remove_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/rados_write_op_setxattr_test.go b/rados/rados_write_op_setxattr_test.go
index 670d5cd..80fbfb0 100644
--- a/rados/rados_write_op_setxattr_test.go
+++ b/rados/rados_write_op_setxattr_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/read_op_omap_get_vals_by_keys_test.go b/rados/read_op_omap_get_vals_by_keys_test.go
index 8cfc3b8..eb25793 100644
--- a/rados/read_op_omap_get_vals_by_keys_test.go
+++ b/rados/read_op_omap_get_vals_by_keys_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/read_op_read_test.go b/rados/read_op_read_test.go
index 1d15b31..1a6f0c5 100644
--- a/rados/read_op_read_test.go
+++ b/rados/read_op_read_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (
diff --git a/rados/watcher_test.go b/rados/watcher_test.go
index c0a5d6b..b7d5def 100644
--- a/rados/watcher_test.go
+++ b/rados/watcher_test.go
@@ -1,6 +1,3 @@
-//go:build ceph_preview
-// +build ceph_preview
-
 package rados
 
 import (