You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by we...@apache.org on 2018/08/30 18:55:33 UTC
[arrow] branch master updated: ARROW-3018: [Plasma][FOLLOWUP]
Update plasma documentation
This is an automated email from the ASF dual-hosted git repository.
wesm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 927bd34 ARROW-3018: [Plasma][FOLLOWUP] Update plasma documentation
927bd34 is described below
commit 927bd34aaad875e82beca2584d5d777839fa8bb0
Author: Philipp Moritz <pc...@gmail.com>
AuthorDate: Thu Aug 30 14:55:25 2018 -0400
ARROW-3018: [Plasma][FOLLOWUP] Update plasma documentation
Small fix for the documentation regarding ARROW-3018 (will also be needed for https://github.com/apache/arrow/pull/2481)
Author: Philipp Moritz <pc...@gmail.com>
Closes #2482 from pcmoritz/update-plasma-doc and squashes the following commits:
279277d0 <Philipp Moritz> fix
29276bf3 <Philipp Moritz> fix
be3efaae <Philipp Moritz> make plasma/test-util.h not depend on arrow/test-util.h
69bd2cbf <Philipp Moritz> fix
f00609e5 <Philipp Moritz> update plasma documentation
---
cpp/apidoc/tutorials/plasma.md | 24 +++++++++++++++++-------
cpp/src/plasma/CMakeLists.txt | 1 +
cpp/src/plasma/{test-common.h => test-util.h} | 17 +++++++++++------
cpp/src/plasma/test/client_tests.cc | 5 ++++-
cpp/src/plasma/test/serialization_tests.cc | 3 ++-
5 files changed, 35 insertions(+), 15 deletions(-)
diff --git a/cpp/apidoc/tutorials/plasma.md b/cpp/apidoc/tutorials/plasma.md
index 2875d55..472d479 100644
--- a/cpp/apidoc/tutorials/plasma.md
+++ b/cpp/apidoc/tutorials/plasma.md
@@ -113,11 +113,18 @@ stored in shared memory. Each object in the Plasma store should be associated
with a unique ID. The Object ID is then a key that can be used by **any** client
to fetch that object from the Plasma store.
-Random generation of Object IDs is often good enough to ensure unique IDs:
+Random generation of Object IDs is often good enough to ensure unique IDs.
+For test purposes, you can use the function `random_object_id` from the header
+`plasma/test-util.h` to generate random Object IDs, which uses a global random
+number generator. In your own applications, we recommend to generate a string of
+`ObjectID::size()` many random bytes using your own random number generator
+and pass them to `ObjectID::from_bytes` to generate the ObjectID.
```cpp
+#include <plasma/test-util.h>
+
// Randomly generate an Object ID.
-ObjectID object_id = ObjectID::from_random();
+ObjectID object_id = random_object_id();
```
Now, any connected client that knows the object's Object ID can access the
@@ -142,11 +149,12 @@ Here is a test program you can run:
#include <iostream>
#include <string>
#include <plasma/client.h>
+#include <plasma/test-util.h>
using namespace plasma;
int main(int argc, char** argv) {
- ObjectID object_id1 = ObjectID::from_random();
+ ObjectID object_id1 = random_object_id();
std::cout << "object_id1 is " << object_id1.hex() << std::endl;
std::string id_string = object_id1.binary();
@@ -222,12 +230,13 @@ int main(int argc, char** argv) {
// Create an object with a fixed ObjectID.
ObjectID object_id = ObjectID::from_binary("00000000000000000000");
int64_t data_size = 1000;
- uint8_t *data;
+ std::shared_ptr<Buffer> data;
std::string metadata = "{'author': 'john'}";
ARROW_CHECK_OK(client.Create(object_id, data_size, (uint8_t*) metadata.data(), metadata.size(), &data));
// Write some data into the object.
+ auto d = data->mutable_data();
for (int64_t i = 0; i < data_size; i++) {
- data[i] = static_cast<uint8_t>(i % 4);
+ d[i] = static_cast<uint8_t>(i % 4);
}
// Seal the object.
ARROW_CHECK_OK(client.Seal(object_id));
@@ -329,8 +338,9 @@ int main(int argc, char** argv) {
ARROW_CHECK_OK(client.Get(&object_id, 1, -1, &object_buffer));
// Retrieve object data.
- uint8_t* data = object_buffer.data;
- int64_t data_size = object_buffer.data_size;
+ auto buffer = object_buffer.data;
+ const uint8_t* data = buffer->data();
+ int64_t data_size = buffer->size();
// Check that the data agrees with what was written in the other process.
for (int64_t i = 0; i < data_size; i++) {
diff --git a/cpp/src/plasma/CMakeLists.txt b/cpp/src/plasma/CMakeLists.txt
index a068951..88644b7 100644
--- a/cpp/src/plasma/CMakeLists.txt
+++ b/cpp/src/plasma/CMakeLists.txt
@@ -143,6 +143,7 @@ install(FILES
compat.h
client.h
events.h
+ test-util.h
DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/plasma")
# Plasma store
diff --git a/cpp/src/plasma/test-common.h b/cpp/src/plasma/test-util.h
similarity index 70%
rename from cpp/src/plasma/test-common.h
rename to cpp/src/plasma/test-util.h
index 66b8c24..6bd501b 100644
--- a/cpp/src/plasma/test-common.h
+++ b/cpp/src/plasma/test-util.h
@@ -15,11 +15,12 @@
// specific language governing permissions and limitations
// under the License.
-#ifndef PLASMA_TEST_COMMON_H
-#define PLASMA_TEST_COMMON_H
+#ifndef PLASMA_TEST_UTIL_H
+#define PLASMA_TEST_UTIL_H
-#include "arrow/test-util.h"
-#include "gtest/gtest.h"
+#include <algorithm>
+#include <limits>
+#include <random>
#include "plasma/common.h"
@@ -27,11 +28,15 @@ namespace plasma {
ObjectID random_object_id() {
static uint32_t random_seed = 0;
+ std::mt19937 gen(random_seed++);
+ std::uniform_int_distribution<uint32_t> d(0, std::numeric_limits<uint8_t>::max());
ObjectID result;
- arrow::random_bytes(kUniqueIDSize, random_seed++, result.mutable_data());
+ uint8_t* data = result.mutable_data();
+ std::generate(data, data + kUniqueIDSize,
+ [&d, &gen] { return static_cast<uint8_t>(d(gen)); });
return result;
}
} // namespace plasma
-#endif // PLASMA_TEST_COMMON_H
+#endif // PLASMA_TEST_UTIL_H
diff --git a/cpp/src/plasma/test/client_tests.cc b/cpp/src/plasma/test/client_tests.cc
index a1d43dc..d391cd9 100644
--- a/cpp/src/plasma/test/client_tests.cc
+++ b/cpp/src/plasma/test/client_tests.cc
@@ -26,12 +26,15 @@
#include <random>
#include <thread>
-#include "plasma/test-common.h"
+#include <gtest/gtest.h>
+
+#include "arrow/test-util.h"
#include "plasma/client.h"
#include "plasma/common.h"
#include "plasma/plasma.h"
#include "plasma/protocol.h"
+#include "plasma/test-util.h"
namespace plasma {
diff --git a/cpp/src/plasma/test/serialization_tests.cc b/cpp/src/plasma/test/serialization_tests.cc
index d910334..085ae97 100644
--- a/cpp/src/plasma/test/serialization_tests.cc
+++ b/cpp/src/plasma/test/serialization_tests.cc
@@ -18,12 +18,13 @@
#include <sys/types.h>
#include <unistd.h>
-#include "plasma/test-common.h"
+#include <gtest/gtest.h>
#include "plasma/common.h"
#include "plasma/io.h"
#include "plasma/plasma.h"
#include "plasma/protocol.h"
+#include "plasma/test-util.h"
namespace fb = plasma::flatbuf;