From f9858e21031c44e39440a016faeed00550b8c6ea Mon Sep 17 00:00:00 2001 From: Siyuan Date: Sat, 7 Mar 2020 22:12:14 -0800 Subject: [PATCH] uniform comments style --- 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 a27a5c41a9f..64ceccc0cc7 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 519aa64d464..b2496d9aa92 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* 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* 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* 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& object_ids); diff --git a/cpp/src/plasma/fling.h b/cpp/src/plasma/fling.h index d5afc9f84f4..d1582c3c823 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 a081190b3ef..92d6537e948 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 0710e34c275..6f38951fbf9 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 CreateObjectInfoBuffer(fb::ObjectInfoT* object_info) { diff --git a/cpp/src/plasma/plasma.h b/cpp/src/plasma/plasma.h index 79e33c2f0c3..dbfd43d7de2 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 CreateObjectInfoBuffer(flatbuf::ObjectInfoT* object_info); diff --git a/cpp/src/plasma/quota_aware_policy.h b/cpp/src/plasma/quota_aware_policy.h index fb7eade87f7..953f0bcddf3 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 d02765f41cf..81e3c173f06 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 31588a5aa1d..608349b9fed 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& 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& 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& object_ids, const std::vector& 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 560c1de10db..96c3760090f 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 read_message_from_file(int fd, MessageType message_type) {