You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by ko...@apache.org on 2020/03/08 20:36:31 UTC
[arrow] branch master updated: ARROW-8030: [Plasma] Uniform
comments style
This is an automated email from the ASF dual-hosted git repository.
kou 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 e728316 ARROW-8030: [Plasma] Uniform comments style
e728316 is described below
commit e728316c50be7e1312e24c947523110c82f7329d
Author: Siyuan <su...@gmail.com>
AuthorDate: Mon Mar 9 05:36:03 2020 +0900
ARROW-8030: [Plasma] Uniform comments style
The comments in the plasma are a mixture of '@params' and '\params'. The reviewers required me to unify the style when I was trying to add windows support. I think it would be better to address it using a different PR. This is a blocking issue of a few refactoring and the windows support pr, so hopefully the review process is fast.
Closes #6559 from suquark/fix_comments and squashes the following commits:
f9858e210 <Siyuan> uniform comments style
Authored-by: Siyuan <su...@gmail.com>
Signed-off-by: Sutou Kouhei <ko...@clear-code.com>
---
cpp/src/plasma/client.h | 2 +-
cpp/src/plasma/eviction_policy.h | 46 ++++++++++++-------------
cpp/src/plasma/fling.h | 10 +++---
cpp/src/plasma/malloc.h | 4 +--
cpp/src/plasma/plasma.cc | 4 +--
cpp/src/plasma/plasma.h | 12 +++----
cpp/src/plasma/quota_aware_policy.h | 4 +--
cpp/src/plasma/store.cc | 4 +--
cpp/src/plasma/store.h | 54 +++++++++++++++---------------
cpp/src/plasma/test/serialization_tests.cc | 6 ++--
10 files changed, 73 insertions(+), 73 deletions(-)
diff --git a/cpp/src/plasma/client.h b/cpp/src/plasma/client.h
index a27a5c4..64ceccc 100644
--- a/cpp/src/plasma/client.h
+++ b/cpp/src/plasma/client.h
@@ -207,7 +207,7 @@ class ARROW_EXPORT PlasmaClient {
/// object is present, has been sealed and not used by another client. Otherwise,
/// it is a no operation.
///
- /// @todo We may want to allow the deletion of objects that are not present or
+ /// \todo We may want to allow the deletion of objects that are not present or
/// haven't been sealed.
///
/// \param object_id The ID of the object to delete.
diff --git a/cpp/src/plasma/eviction_policy.h b/cpp/src/plasma/eviction_policy.h
index 519aa64..b2496d9 100644
--- a/cpp/src/plasma/eviction_policy.h
+++ b/cpp/src/plasma/eviction_policy.h
@@ -95,9 +95,9 @@ class EvictionPolicy {
public:
/// Construct an eviction policy.
///
- /// @param store_info Information about the Plasma store that is exposed
+ /// \param store_info Information about the Plasma store that is exposed
/// to the eviction policy.
- /// @param max_size Max size in bytes total of objects to store.
+ /// \param max_size Max size in bytes total of objects to store.
explicit EvictionPolicy(PlasmaStoreInfo* store_info, int64_t max_size);
/// Destroy an eviction policy.
@@ -108,38 +108,38 @@ class EvictionPolicy {
/// store calls begin_object_access, we can remove the object from the LRU
/// cache.
///
- /// @param object_id The object ID of the object that was created.
- /// @param client The pointer to the client.
- /// @param is_create Whether we are creating a new object (vs reading an object).
+ /// \param object_id The object ID of the object that was created.
+ /// \param client The pointer to the client.
+ /// \param is_create Whether we are creating a new object (vs reading an object).
virtual void ObjectCreated(const ObjectID& object_id, Client* client, bool is_create);
/// Set quota for a client.
///
- /// @param client The pointer to the client.
- /// @param output_memory_quota Set the quota for this client. This can only be
+ /// \param client The pointer to the client.
+ /// \param output_memory_quota Set the quota for this client. This can only be
/// called once per client. This is effectively the equivalent of giving
/// the client its own LRU cache instance. The memory for this is taken
/// out of the capacity of the global LRU cache for the client lifetime.
///
- /// @return True if enough space can be reserved for the given client quota.
+ /// \return True if enough space can be reserved for the given client quota.
virtual bool SetClientQuota(Client* client, int64_t output_memory_quota);
/// Determine what objects need to be evicted to enforce the given client's quota.
///
- /// @param client The pointer to the client creating the object.
- /// @param size The size of the object to create.
- /// @param is_create Whether we are creating a new object (vs reading an object).
- /// @param objects_to_evict The object IDs that were chosen for eviction will
+ /// \param client The pointer to the client creating the object.
+ /// \param size The size of the object to create.
+ /// \param is_create Whether we are creating a new object (vs reading an object).
+ /// \param objects_to_evict The object IDs that were chosen for eviction will
/// be stored into this vector.
///
- /// @return True if enough space could be freed and false otherwise.
+ /// \return True if enough space could be freed and false otherwise.
virtual bool EnforcePerClientQuota(Client* client, int64_t size, bool is_create,
std::vector<ObjectID>* objects_to_evict);
/// Called to clean up any resources allocated by this client. This merges any
/// per-client LRU queue created by SetClientQuota into the global LRU queue.
///
- /// @param client The pointer to the client.
+ /// \param client The pointer to the client.
virtual void ClientDisconnected(Client* client);
/// This method will be called when the Plasma store needs more space, perhaps
@@ -147,11 +147,11 @@ class EvictionPolicy {
/// policy will assume that the objects chosen to be evicted will in fact be
/// evicted from the Plasma store by the caller.
///
- /// @param size The size in bytes of the new object, including both data and
+ /// \param size The size in bytes of the new object, including both data and
/// metadata.
- /// @param objects_to_evict The object IDs that were chosen for eviction will
+ /// \param objects_to_evict The object IDs that were chosen for eviction will
/// be stored into this vector.
- /// @return True if enough space can be freed and false otherwise.
+ /// \return True if enough space can be freed and false otherwise.
virtual bool RequireSpace(int64_t size, std::vector<ObjectID>* objects_to_evict);
/// This method will be called whenever an unused object in the Plasma store
@@ -159,7 +159,7 @@ class EvictionPolicy {
/// assume that the objects chosen to be evicted will in fact be evicted from
/// the Plasma store by the caller.
///
- /// @param object_id The ID of the object that is now being used.
+ /// \param object_id The ID of the object that is now being used.
virtual void BeginObjectAccess(const ObjectID& object_id);
/// This method will be called whenever an object in the Plasma store that was
@@ -167,7 +167,7 @@ class EvictionPolicy {
/// eviction policy will assume that the objects chosen to be evicted will in
/// fact be evicted from the Plasma store by the caller.
///
- /// @param object_id The ID of the object that is no longer being used.
+ /// \param object_id The ID of the object that is no longer being used.
virtual void EndObjectAccess(const ObjectID& object_id);
/// Choose some objects to evict from the Plasma store. When this method is
@@ -177,16 +177,16 @@ class EvictionPolicy {
/// @note This method is not part of the API. It is exposed in the header file
/// only for testing.
///
- /// @param num_bytes_required The number of bytes of space to try to free up.
- /// @param objects_to_evict The object IDs that were chosen for eviction will
+ /// \param num_bytes_required The number of bytes of space to try to free up.
+ /// \param objects_to_evict The object IDs that were chosen for eviction will
/// be stored into this vector.
- /// @return The total number of bytes of space chosen to be evicted.
+ /// \return The total number of bytes of space chosen to be evicted.
virtual int64_t ChooseObjectsToEvict(int64_t num_bytes_required,
std::vector<ObjectID>* objects_to_evict);
/// This method will be called when an object is going to be removed
///
- /// @param object_id The ID of the object that is now being used.
+ /// \param object_id The ID of the object that is now being used.
virtual void RemoveObject(const ObjectID& object_id);
virtual void RefreshObjects(const std::vector<ObjectID>& object_ids);
diff --git a/cpp/src/plasma/fling.h b/cpp/src/plasma/fling.h
index d5afc9f..d1582c3c 100644
--- a/cpp/src/plasma/fling.h
+++ b/cpp/src/plasma/fling.h
@@ -40,13 +40,13 @@ void init_msg(struct msghdr* msg, struct iovec* iov, char* buf, size_t buf_len);
// Send a file descriptor over a unix domain socket.
//
-// @param conn Unix domain socket to send the file descriptor over.
-// @param fd File descriptor to send over.
-// @return Status code which is < 0 on failure.
+// \param conn Unix domain socket to send the file descriptor over.
+// \param fd File descriptor to send over.
+// \return Status code which is < 0 on failure.
int send_fd(int conn, int fd);
// Receive a file descriptor over a unix domain socket.
//
-// @param conn Unix domain socket to receive the file descriptor from.
-// @return File descriptor or a value < 0 on failure.
+// \param conn Unix domain socket to receive the file descriptor from.
+// \return File descriptor or a value < 0 on failure.
int recv_fd(int conn);
diff --git a/cpp/src/plasma/malloc.h b/cpp/src/plasma/malloc.h
index a081190..92d6537 100644
--- a/cpp/src/plasma/malloc.h
+++ b/cpp/src/plasma/malloc.h
@@ -35,8 +35,8 @@ void GetMallocMapinfo(void* addr, int* fd, int64_t* map_length, ptrdiff_t* offse
/// Get the mmap size corresponding to a specific file descriptor.
///
-/// @param fd The file descriptor to look up.
-/// @return The size of the corresponding memory-mapped file.
+/// \param fd The file descriptor to look up.
+/// \return The size of the corresponding memory-mapped file.
int64_t GetMmapSize(int fd);
struct MmapRecord {
diff --git a/cpp/src/plasma/plasma.cc b/cpp/src/plasma/plasma.cc
index 0710e34..6f38951 100644
--- a/cpp/src/plasma/plasma.cc
+++ b/cpp/src/plasma/plasma.cc
@@ -54,8 +54,8 @@ int WarnIfSigpipe(int status, int client_sock) {
* of this buffer are the length of the remaining message and the
* remaining message is a serialized version of the object info.
*
- * @param object_info The object info to be serialized
- * @return The object info buffer. It is the caller's responsibility to free
+ * \param object_info The object info to be serialized
+ * \return The object info buffer. It is the caller's responsibility to free
* this buffer with "delete" after it has been used.
*/
std::unique_ptr<uint8_t[]> CreateObjectInfoBuffer(fb::ObjectInfoT* object_info) {
diff --git a/cpp/src/plasma/plasma.h b/cpp/src/plasma/plasma.h
index 79e33c2..dbfd43d 100644
--- a/cpp/src/plasma/plasma.h
+++ b/cpp/src/plasma/plasma.h
@@ -145,9 +145,9 @@ struct PlasmaStoreInfo {
/// Get an entry from the object table and return NULL if the object_id
/// is not present.
///
-/// @param store_info The PlasmaStoreInfo that contains the object table.
-/// @param object_id The object_id of the entry we are looking for.
-/// @return The entry associated with the object_id or NULL if the object_id
+/// \param store_info The PlasmaStoreInfo that contains the object table.
+/// \param object_id The object_id of the entry we are looking for.
+/// \return The entry associated with the object_id or NULL if the object_id
/// is not present.
ObjectTableEntry* GetObjectTableEntry(PlasmaStoreInfo* store_info,
const ObjectID& object_id);
@@ -161,11 +161,11 @@ ObjectTableEntry* GetObjectTableEntry(PlasmaStoreInfo* store_info,
/// have not, then we should get a SIGPIPE. If we write to a TCP socket that
/// isn't connected yet, then we should get an ECONNRESET.
///
-/// @param status The status to check. If it is less less than zero, we will
+/// \param status The status to check. If it is less less than zero, we will
/// print a warning.
-/// @param client_sock The client socket. This is just used to print some extra
+/// \param client_sock The client socket. This is just used to print some extra
/// information.
-/// @return The errno set.
+/// \return The errno set.
int WarnIfSigpipe(int status, int client_sock);
std::unique_ptr<uint8_t[]> CreateObjectInfoBuffer(flatbuf::ObjectInfoT* object_info);
diff --git a/cpp/src/plasma/quota_aware_policy.h b/cpp/src/plasma/quota_aware_policy.h
index fb7eade..953f0bc 100644
--- a/cpp/src/plasma/quota_aware_policy.h
+++ b/cpp/src/plasma/quota_aware_policy.h
@@ -57,9 +57,9 @@ class QuotaAwarePolicy : public EvictionPolicy {
public:
/// Construct a quota-aware eviction policy.
///
- /// @param store_info Information about the Plasma store that is exposed
+ /// \param store_info Information about the Plasma store that is exposed
/// to the eviction policy.
- /// @param max_size Max size in bytes total of objects to store.
+ /// \param max_size Max size in bytes total of objects to store.
explicit QuotaAwarePolicy(PlasmaStoreInfo* store_info, int64_t max_size);
void ObjectCreated(const ObjectID& object_id, Client* client, bool is_create) override;
bool SetClientQuota(Client* client, int64_t output_memory_quota) override;
diff --git a/cpp/src/plasma/store.cc b/cpp/src/plasma/store.cc
index d02765f..81e3c17 100644
--- a/cpp/src/plasma/store.cc
+++ b/cpp/src/plasma/store.cc
@@ -785,8 +785,8 @@ void PlasmaStore::DisconnectClient(int client_fd) {
/// invalidated, which is why we return a valid iterator to the next client to
/// be used in PushNotification.
///
-/// @param it Iterator that points to the client to send the notification to.
-/// @return Iterator pointing to the next client.
+/// \param it Iterator that points to the client to send the notification to.
+/// \return Iterator pointing to the next client.
PlasmaStore::NotificationMap::iterator PlasmaStore::SendNotifications(
PlasmaStore::NotificationMap::iterator it) {
int client_fd = it->first;
diff --git a/cpp/src/plasma/store.h b/cpp/src/plasma/store.h
index 31588a5..608349b 100644
--- a/cpp/src/plasma/store.h
+++ b/cpp/src/plasma/store.h
@@ -71,17 +71,17 @@ class PlasmaStore {
/// Create a new object. The client must do a call to release_object to tell
/// the store when it is done with the object.
///
- /// @param object_id Object ID of the object to be created.
- /// @param data_size Size in bytes of the object to be created.
- /// @param metadata_size Size in bytes of the object metadata.
- /// @param device_num The number of the device where the object is being
+ /// \param object_id Object ID of the object to be created.
+ /// \param data_size Size in bytes of the object to be created.
+ /// \param metadata_size Size in bytes of the object metadata.
+ /// \param device_num The number of the device where the object is being
/// created.
/// device_num = 0 corresponds to the host,
/// device_num = 1 corresponds to GPU0,
/// device_num = 2 corresponds to GPU1, etc.
- /// @param client The client that created the object.
- /// @param result The object that has been created.
- /// @return One of the following error codes:
+ /// \param client The client that created the object.
+ /// \param result The object that has been created.
+ /// \return One of the following error codes:
/// - PlasmaError::OK, if the object was created successfully.
/// - PlasmaError::ObjectExists, if an object with this ID is already
/// present in the store. In this case, the client should not call
@@ -96,16 +96,16 @@ class PlasmaStore {
/// Abort a created but unsealed object. If the client is not the
/// creator, then the abort will fail.
///
- /// @param object_id Object ID of the object to be aborted.
- /// @param client The client who created the object. If this does not
+ /// \param object_id Object ID of the object to be aborted.
+ /// \param client The client who created the object. If this does not
/// match the creator of the object, then the abort will fail.
- /// @return 1 if the abort succeeds, else 0.
+ /// \return 1 if the abort succeeds, else 0.
int AbortObject(const ObjectID& object_id, Client* client);
/// Delete a specific object by object_id that have been created in the hash table.
///
- /// @param object_id Object ID of the object to be deleted.
- /// @return One of the following error codes:
+ /// \param object_id Object ID of the object to be deleted.
+ /// \return One of the following error codes:
/// - PlasmaError::OK, if the object was delete successfully.
/// - PlasmaError::ObjectNonexistent, if ths object isn't existed.
/// - PlasmaError::ObjectInUse, if the object is in use.
@@ -113,7 +113,7 @@ class PlasmaStore {
/// Evict objects returned by the eviction policy.
///
- /// @param object_ids Object IDs of the objects to be evicted.
+ /// \param object_ids Object IDs of the objects to be evicted.
void EvictObjects(const std::vector<ObjectID>& object_ids);
/// Process a get request from a client. This method assumes that we will
@@ -124,47 +124,47 @@ class PlasmaStore {
/// For each object, the client must do a call to release_object to tell the
/// store when it is done with the object.
///
- /// @param client The client making this request.
- /// @param object_ids Object IDs of the objects to be gotten.
- /// @param timeout_ms The timeout for the get request in milliseconds.
+ /// \param client The client making this request.
+ /// \param object_ids Object IDs of the objects to be gotten.
+ /// \param timeout_ms The timeout for the get request in milliseconds.
void ProcessGetRequest(Client* client, const std::vector<ObjectID>& object_ids,
int64_t timeout_ms);
/// Seal a vector of objects. The objects are now immutable and can be accessed with
/// get.
///
- /// @param object_ids The vector of Object IDs of the objects to be sealed.
- /// @param digests The vector of digests of the objects. This is used to tell if two
+ /// \param object_ids The vector of Object IDs of the objects to be sealed.
+ /// \param digests The vector of digests of the objects. This is used to tell if two
/// objects with the same object ID are the same.
void SealObjects(const std::vector<ObjectID>& object_ids,
const std::vector<std::string>& digests);
/// Check if the plasma store contains an object:
///
- /// @param object_id Object ID that will be checked.
- /// @return OBJECT_FOUND if the object is in the store, OBJECT_NOT_FOUND if
+ /// \param object_id Object ID that will be checked.
+ /// \return OBJECT_FOUND if the object is in the store, OBJECT_NOT_FOUND if
/// not
ObjectStatus ContainsObject(const ObjectID& object_id);
/// Record the fact that a particular client is no longer using an object.
///
- /// @param object_id The object ID of the object that is being released.
- /// @param client The client making this request.
+ /// \param object_id The object ID of the object that is being released.
+ /// \param client The client making this request.
void ReleaseObject(const ObjectID& object_id, Client* client);
/// Subscribe a file descriptor to updates about new sealed objects.
///
- /// @param client The client making this request.
+ /// \param client The client making this request.
void SubscribeToUpdates(Client* client);
/// Connect a new client to the PlasmaStore.
///
- /// @param listener_sock The socket that is listening to incoming connections.
+ /// \param listener_sock The socket that is listening to incoming connections.
void ConnectClient(int listener_sock);
/// Disconnect a client from the PlasmaStore.
///
- /// @param client_fd The client file descriptor that is disconnected.
+ /// \param client_fd The client file descriptor that is disconnected.
void DisconnectClient(int client_fd);
NotificationMap::iterator SendNotifications(NotificationMap::iterator it);
@@ -183,12 +183,12 @@ class PlasmaStore {
/// Remove a GetRequest and clean up the relevant data structures.
///
- /// @param get_request The GetRequest to remove.
+ /// \param get_request The GetRequest to remove.
void RemoveGetRequest(GetRequest* get_request);
/// Remove all of the GetRequests for a given client.
///
- /// @param client The client whose GetRequests should be removed.
+ /// \param client The client whose GetRequests should be removed.
void RemoveGetRequestsForClient(Client* client);
void ReturnFromGet(GetRequest* get_req);
diff --git a/cpp/src/plasma/test/serialization_tests.cc b/cpp/src/plasma/test/serialization_tests.cc
index 560c1de..96c3760 100644
--- a/cpp/src/plasma/test/serialization_tests.cc
+++ b/cpp/src/plasma/test/serialization_tests.cc
@@ -40,10 +40,10 @@ using arrow::internal::TemporaryDir;
/**
* Seek to the beginning of a file and read a message from it.
*
- * @param fd File descriptor of the file.
- * @param message_type Message type that we expect in the file.
+ * \param fd File descriptor of the file.
+ * \param message_type Message type that we expect in the file.
*
- * @return Pointer to the content of the message. Needs to be freed by the
+ * \return Pointer to the content of the message. Needs to be freed by the
* caller.
*/
std::vector<uint8_t> read_message_from_file(int fd, MessageType message_type) {