Add comment

Author: hipudding

ggml/src/ggml-cann/acl_tensor.h

@@ -44,6 +44,7 @@
  */
 aclDataType ggml_cann_type_mapping(ggml_type type);
 
+// Deleter for aclTensor.
 struct acl_tensor_deleter {
     void operator()(aclTensor * ptr) const noexcept {
         if (ptr != nullptr) {
@@ -52,8 +53,7 @@ struct acl_tensor_deleter {
     }
 };
 
-using acl_tensor_ptr = std::unique_ptr<aclTensor, acl_tensor_deleter>;
-
+// Deleter for aclIntArray.
 struct acl_int_array_deleter {
     void operator()(aclIntArray * ptr) const noexcept {
         if (ptr != nullptr) {
@@ -62,8 +62,7 @@ struct acl_int_array_deleter {
     }
 };
 
-using acl_int_array_ptr = std::unique_ptr<aclIntArray, acl_int_array_deleter>;
-
+// Deleter for aclScalar.
 struct acl_scalar_deleter {
     void operator()(aclScalar * ptr) const noexcept {
         if (ptr != nullptr) {
@@ -72,8 +71,7 @@ struct acl_scalar_deleter {
     }
 };
 
-using acl_scalar_ptr = std::unique_ptr<aclScalar, acl_scalar_deleter>;
-
+// Deleter for aclTensorList.
 struct acl_tensor_list_deleter {
     void operator()(aclTensorList * ptr) const noexcept {
         if (ptr != nullptr) {
@@ -82,6 +80,9 @@ struct acl_tensor_list_deleter {
     }
 };
 
+using acl_tensor_ptr      = std::unique_ptr<aclTensor, acl_tensor_deleter>;
+using acl_int_array_ptr   = std::unique_ptr<aclIntArray, acl_int_array_deleter>;
+using acl_scalar_ptr      = std::unique_ptr<aclScalar, acl_scalar_deleter>;
 using acl_tensor_list_ptr = std::unique_ptr<aclTensorList, acl_tensor_list_deleter>;
 
 /**
@@ -161,9 +162,61 @@ acl_tensor_ptr ggml_cann_create_tensor(void *      data_ptr,
     return acl_tensor_ptr(raw);
 }
 
+/**
+ * @brief Create an ACL int array resource wrapped in a smart pointer.
+ *
+ * This function constructs an aclIntArray from the provided int64_t values
+ * and returns it as an acl_int_array_ptr (a std::unique_ptr with a custom
+ * deleter). The returned pointer owns the ACL resource and will automatically
+ * destroy it via aclDestroyIntArray().
+ *
+ * @param value  Pointer to the int64_t elements.
+ * @param size   Number of elements in value.
+ *
+ * @return A smart pointer managing the created ACL int array.
+ */
 acl_int_array_ptr ggml_cann_create_int_array(const int64_t * value, uint64_t size);
-acl_scalar_ptr    ggml_cann_create_scalar(void * value, aclDataType dataType);
 
+/**
+ * @brief Create an ACL scalar resource wrapped in a smart pointer.
+ *
+ * This function constructs an aclScalar from the raw value pointer and ACL
+ * data type, then returns it as an acl_scalar_ptr (a std::unique_ptr with
+ * a custom deleter). The returned pointer owns the ACL scalar and will
+ * automatically destroy it via aclDestroyScalar().
+ *
+ * @param value     Pointer to the raw scalar memory.
+ * @param dataType  ACL data type of the scalar.
+ *
+ * @return A smart pointer managing the created ACL scalar.
+ */
+acl_scalar_ptr ggml_cann_create_scalar(void * value, aclDataType dataType);
+
+/**
+ * @brief Create an ACL tensor list from multiple tensor smart pointers.
+ *
+ * This function accepts a variadic list of acl_tensor_ptr (a unique_ptr with
+ * custom deleter) and produces an aclTensorList using aclCreateTensorList().
+ *
+ * The lifecycle management of the tensor objects changes as follows:
+ *  - aclCreateTensorList() takes ownership of the tensors
+ *  - Each input smart pointer releases ownership using release()
+ *  - As a result, the tensors will NOT be destroyed by unique_ptr
+ *  - Instead, they will be destroyed when aclDestroyTensorList() is called
+ *
+ * This ensures correct ownership transfer and prevents double-free situations.
+ *
+ * @param acl_tensor_ptr  Variadic template parameter; each argument must be
+ *                         a unique_ptr-like type supporting get() and release().
+ *
+ * @param tensors  Variadic list of acl_tensor_ptr objects. Ownership of
+ *                         each tensor is transferred away from these smart pointers.
+ *
+ * @return A smart pointer (acl_tensor_list_ptr) owning the created ACL tensor list.
+ *
+ * @note This implementation is C++11 compatible. The ownership-release process is
+ *       executed using a pack expansion inside an initializer list.
+ */
 template <typename... acl_tensor_ptr> acl_tensor_list_ptr ggml_cann_create_tensor_list(acl_tensor_ptr &&... tensors) {
     aclTensor *     raw_tensors[] = { tensors.get()... };
     aclTensorList * raw           = aclCreateTensorList(raw_tensors, sizeof...(tensors));

ggml/src/ggml-cann/aclnn_ops.cpp

@@ -900,7 +900,7 @@ void ggml_cann_dup(ggml_backend_cann_context & ctx, ggml_tensor * dst) {
  * @param dims The number of dimensions of the tensor.
  * @param type The data type of the tensor.
  * @param type_size The size of each element in the tensor data type.
- * @return An ACL tensor initialized with zeros.
+ * @return A tensor smart pointer initialized with zeros.
  */
 static acl_tensor_ptr aclnn_zero(ggml_backend_cann_context & ctx,
                                  void *                      buffer,
@@ -937,7 +937,7 @@ static acl_tensor_ptr aclnn_zero(ggml_backend_cann_context & ctx,
  * @param type_size The size of each element in the tensor data type.
  * @param value The value to be used for initializing the tensor (default
  * is 1.0).
- * @return An ACL tensor initialized with value.
+ * @return A tensor smart pointer initialized with value.
  */
 static acl_tensor_ptr aclnn_values(ggml_backend_cann_context & ctx,
                                    void *                      buffer,
@@ -990,7 +990,7 @@ static void aclnn_fill_scalar(ggml_backend_cann_context & ctx, float scalar, acl
  * @param dims          The number of tensor dimensions.
  * @param value         The scalar value used to fill the tensor (supports zero
  *                      initialization via memset or arbitrary values via fill_scalar).
- * @return              An aclTensor pointer created from the cached buffer.
+ * @return              A tensor smart pointer created from the cached buffer.
  */
 static acl_tensor_ptr get_cache_acl_tensor(ggml_backend_cann_context & ctx,
                                            void **                     buffer,

ggml/src/ggml-cann/aclnn_ops.h

@@ -993,7 +993,7 @@ template <auto binary_op> void ggml_cann_binary_op(ggml_backend_cann_context & c
  * and stores the result in the destination tensor.
  *
  * @tparam unary_op A callable with the signature:
- *         void(ggml_backend_cann_context&, acl_tensor_ptr, acl_tensor_ptr)
+ *         void(ggml_backend_cann_context&, aclTensor *, aclTensor *)
  *         where the first aclTensor is the source and the second is the destination.
  * @param ctx The CANN backend context for managing resources and execution.
  * @param dst The destination tensor. Its src[0] is treated as the input tensor.