Skip to content

GitLab

Unverified Commit 6c53f351 authored by Hongzhi (Steve), Chen's avatar Hongzhi (Steve), Chen Committed by GitHub
Browse files

Replace \xxx with @XXX in structured comment. (#4815) 



* replace

* more

* file

* change
Co-authored-by: default avatarSteve <ubuntu@ip-172-31-34-29.ap-northeast-1.compute.internal>
parent 33a2d9e1
Hide whitespace changes
Inline Side-by-side
Showing with 635 additions and 635 deletions
include/dgl/runtime/c_object_api.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2019 by Contributors * Copyright (c) 2019 by Contributors
* \file dgl/runtime/c_object_api.h * @file dgl/runtime/c_object_api.h
* *
* \brief DGL Object C API, used to extend and prototype new CAPIs. * @brief DGL Object C API, used to extend and prototype new CAPIs.
* *
* \note Most API functions are registerd as PackedFunc and * @note Most API functions are registerd as PackedFunc and
* can be grabbed via DGLFuncGetGlobal * can be grabbed via DGLFuncGetGlobal
*/ */
#ifndef DGL_RUNTIME_C_OBJECT_API_H_ #ifndef DGL_RUNTIME_C_OBJECT_API_H_
...@@ -16,52 +16,52 @@ ...@@ -16,52 +16,52 @@
extern "C" { extern "C" {
#endif #endif
/*! \brief handle to object */ /*! @brief handle to object */
typedef void* ObjectHandle; typedef void* ObjectHandle;
/*! /*!
* \brief free the object handle * @brief free the object handle
* \param handle The object handle to be freed. * @param handle The object handle to be freed.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLObjectFree(ObjectHandle handle); DGL_DLL int DGLObjectFree(ObjectHandle handle);
/*! /*!
* \brief Convert type key to type index. * @brief Convert type key to type index.
* \param type_key The key of the type. * @param type_key The key of the type.
* \param out_index the corresponding type index. * @param out_index the corresponding type index.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLObjectTypeKey2Index(const char* type_key, int* out_index); DGL_DLL int DGLObjectTypeKey2Index(const char* type_key, int* out_index);
/*! /*!
* \brief Get runtime type index of the object. * @brief Get runtime type index of the object.
* \param handle the object handle. * @param handle the object handle.
* \param out_index the corresponding type index. * @param out_index the corresponding type index.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLObjectGetTypeIndex(ObjectHandle handle, int* out_index); DGL_DLL int DGLObjectGetTypeIndex(ObjectHandle handle, int* out_index);
/*! /*!
* \brief get attributes given key * @brief get attributes given key
* \param handle The object handle * @param handle The object handle
* \param key The attribute name * @param key The attribute name
* \param out_value The attribute value * @param out_value The attribute value
* \param out_type_code The type code of the attribute. * @param out_type_code The type code of the attribute.
* \param out_success Whether get is successful. * @param out_success Whether get is successful.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
* \note API calls always exchanges with type bits=64, lanes=1 * @note API calls always exchanges with type bits=64, lanes=1
*/ */
DGL_DLL int DGLObjectGetAttr( DGL_DLL int DGLObjectGetAttr(
ObjectHandle handle, const char* key, DGLValue* out_value, ObjectHandle handle, const char* key, DGLValue* out_value,
int* out_type_code, int* out_success); int* out_type_code, int* out_success);
/*! /*!
* \brief get attributes names in the object. * @brief get attributes names in the object.
* \param handle The object handle * @param handle The object handle
* \param out_size The number of functions * @param out_size The number of functions
* \param out_array The array of function names. * @param out_array The array of function names.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLObjectListAttrNames( DGL_DLL int DGLObjectListAttrNames(
ObjectHandle handle, int* out_size, const char*** out_array); ObjectHandle handle, int* out_size, const char*** out_array);
......
include/dgl/runtime/c_runtime_api.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2016-2022 by Contributors * Copyright (c) 2016-2022 by Contributors
* \file dgl/runtime/c_runtime_api.h * @file dgl/runtime/c_runtime_api.h
* \brief DGL runtime library. * @brief DGL runtime library.
* *
* This runtime is adapted from TVM project (commit: 2ce5277) * This runtime is adapted from TVM project (commit: 2ce5277)
*/ */
...@@ -41,26 +41,26 @@ extern "C" { ...@@ -41,26 +41,26 @@ extern "C" {
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/*! \brief type of array index. */ /*! @brief type of array index. */
typedef int64_t dgl_index_t; typedef int64_t dgl_index_t;
/*! /*!
* \brief The device type in DGLContext. * @brief The device type in DGLContext.
*/ */
#ifdef __cplusplus #ifdef __cplusplus
typedef enum : int32_t { typedef enum : int32_t {
#else #else
typedef enum { typedef enum {
#endif #endif
/*! \brief CPU device */ /*! @brief CPU device */
kDGLCPU = 1, kDGLCPU = 1,
/*! \brief CUDA GPU device */ /*! @brief CUDA GPU device */
kDGLCUDA = 2, kDGLCUDA = 2,
// add more devices once supported // add more devices once supported
} DGLDeviceType; } DGLDeviceType;
/*! /*!
* \brief The object type code is used in DGL FFI to indicate the types of * @brief The object type code is used in DGL FFI to indicate the types of
* objects passed between C and Python. * objects passed between C and Python.
*/ */
typedef enum { typedef enum {
...@@ -91,22 +91,22 @@ typedef enum { ...@@ -91,22 +91,22 @@ typedef enum {
} DGLObjectTypeCode; } DGLObjectTypeCode;
/*! /*!
* \brief The type code options DGLDataType. * @brief The type code options DGLDataType.
*/ */
typedef enum { typedef enum {
/*! \brief signed integer */ /*! @brief signed integer */
kDGLInt = 0U, kDGLInt = 0U,
/*! \brief unsigned integer */ /*! @brief unsigned integer */
kDGLUInt = 1U, kDGLUInt = 1U,
/*! \brief IEEE floating point */ /*! @brief IEEE floating point */
kDGLFloat = 2U, kDGLFloat = 2U,
/*! \brief bfloat16 */ /*! @brief bfloat16 */
kDGLBfloat = 4U, kDGLBfloat = 4U,
// add more data types if we are going to support them // add more data types if we are going to support them
} DGLDataTypeCode; } DGLDataTypeCode;
/*! /*!
* \brief The data type the tensor can hold. The data type is assumed to follow * @brief The data type the tensor can hold. The data type is assumed to follow
* the native endian-ness. An explicit error message should be raised when * the native endian-ness. An explicit error message should be raised when
* attempting to export an array with non-native endianness * attempting to export an array with non-native endianness
* *
...@@ -117,39 +117,39 @@ typedef enum { ...@@ -117,39 +117,39 @@ typedef enum {
*/ */
typedef struct { typedef struct {
/*! /*!
* \brief Type code of base types. * @brief Type code of base types.
* We keep it uint8_t instead of DGLDataTypeCode for minimal memory * We keep it uint8_t instead of DGLDataTypeCode for minimal memory
* footprint, but the value should be one of DGLDataTypeCode enum values. * footprint, but the value should be one of DGLDataTypeCode enum values.
* */ * */
uint8_t code; uint8_t code;
/*! /*!
* \brief Number of bits, common choices are 8, 16, 32. * @brief Number of bits, common choices are 8, 16, 32.
*/ */
uint8_t bits; uint8_t bits;
/*! \brief Number of lanes in the type, used for vector types. */ /*! @brief Number of lanes in the type, used for vector types. */
uint16_t lanes; uint16_t lanes;
} DGLDataType; } DGLDataType;
/*! /*!
* \brief The Device information, abstract away common device types. * @brief The Device information, abstract away common device types.
*/ */
typedef struct { typedef struct {
/*! \brief The device type used in the device. */ /*! @brief The device type used in the device. */
DGLDeviceType device_type; DGLDeviceType device_type;
/*! /*!
* \brief The device index. * @brief The device index.
* For vanilla CPU memory, pinned memory, or managed memory, this is set to 0. * For vanilla CPU memory, pinned memory, or managed memory, this is set to 0.
*/ */
int32_t device_id; int32_t device_id;
} DGLContext; } DGLContext;
/*! /*!
* \brief The tensor array stucture to DGL API. * @brief The tensor array stucture to DGL API.
* The structure is heavily inspired by DLTensor from DLPack. * The structure is heavily inspired by DLTensor from DLPack.
*/ */
typedef struct { typedef struct {
/*! /*!
* \brief The data pointer points to the allocated data. * @brief The data pointer points to the allocated data.
* *
* Depending on the device context, it can be a CPU pointer, or a CUDA * Depending on the device context, it can be a CPU pointer, or a CUDA
* device pointer or acl_mem handle in OpenCL. * device pointer or acl_mem handle in OpenCL.
...@@ -178,28 +178,28 @@ typedef struct { ...@@ -178,28 +178,28 @@ typedef struct {
* \endcode * \endcode
*/ */
void* data; void* data;
/*! \brief The device of the tensor */ /*! @brief The device of the tensor */
DGLContext ctx; DGLContext ctx;
/*! \brief Number of dimensions */ /*! @brief Number of dimensions */
int32_t ndim; int32_t ndim;
/*! \brief The data type of the pointer*/ /*! @brief The data type of the pointer*/
DGLDataType dtype; DGLDataType dtype;
/*! \brief The shape of the tensor */ /*! @brief The shape of the tensor */
int64_t* shape; int64_t* shape;
/*! /*!
* \brief strides of the tensor (in number of elements, not bytes) * @brief strides of the tensor (in number of elements, not bytes)
* can be NULL, indicating tensor is compact and row-majored. * can be NULL, indicating tensor is compact and row-majored.
*/ */
int64_t* strides; int64_t* strides;
/*! \brief The offset in bytes to the beginning pointer to data */ /*! @brief The offset in bytes to the beginning pointer to data */
uint64_t byte_offset; uint64_t byte_offset;
} DGLArray; } DGLArray;
/*! \brief the array handle */ /*! @brief the array handle */
typedef DGLArray* DGLArrayHandle; typedef DGLArray* DGLArrayHandle;
/*! /*!
* \brief Union type of values * @brief Union type of values
* being passed through API and function calls. * being passed through API and function calls.
*/ */
typedef union { typedef union {
...@@ -212,7 +212,7 @@ typedef union { ...@@ -212,7 +212,7 @@ typedef union {
} DGLValue; } DGLValue;
/*! /*!
* \brief Byte array type used to pass in byte array * @brief Byte array type used to pass in byte array
* When kBytes is used as data type. * When kBytes is used as data type.
*/ */
typedef struct { typedef struct {
...@@ -220,27 +220,27 @@ typedef struct { ...@@ -220,27 +220,27 @@ typedef struct {
size_t size; size_t size;
} DGLByteArray; } DGLByteArray;
/*! \brief Handle to DGL runtime modules. */ /*! @brief Handle to DGL runtime modules. */
typedef void* DGLModuleHandle; typedef void* DGLModuleHandle;
/*! \brief Handle to packed function handle. */ /*! @brief Handle to packed function handle. */
typedef void* DGLFunctionHandle; typedef void* DGLFunctionHandle;
/*! \brief Handle to hold return value. */ /*! @brief Handle to hold return value. */
typedef void* DGLRetValueHandle; typedef void* DGLRetValueHandle;
/*! /*!
* \brief The stream that is specific to device * @brief The stream that is specific to device
* can be NULL, which indicates the default one. * can be NULL, which indicates the default one.
*/ */
typedef void* DGLStreamHandle; typedef void* DGLStreamHandle;
/*! /*!
* \brief Used for implementing C API function. * @brief Used for implementing C API function.
* Set last error message before return. * Set last error message before return.
* \param msg The error message to be set. * @param msg The error message to be set.
*/ */
DGL_DLL void DGLAPISetLastError(const char* msg); DGL_DLL void DGLAPISetLastError(const char* msg);
/*! /*!
* \brief return str message of the last error * @brief return str message of the last error
* all function in this file will return 0 when success * all function in this file will return 0 when success
* and -1 when an error occured, * and -1 when an error occured,
* DGLGetLastError can be called to retrieve the error * DGLGetLastError can be called to retrieve the error
...@@ -250,83 +250,83 @@ DGL_DLL void DGLAPISetLastError(const char* msg); ...@@ -250,83 +250,83 @@ DGL_DLL void DGLAPISetLastError(const char* msg);
*/ */
DGL_DLL const char* DGLGetLastError(void); DGL_DLL const char* DGLGetLastError(void);
/*! /*!
* \brief Load module from file. * @brief Load module from file.
* \param file_name The file name to load the module from. * @param file_name The file name to load the module from.
* \param format The format of the module. * @param format The format of the module.
* \param out The result module * @param out The result module
* *
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
* \note The resulting module do not contain import relation. * @note The resulting module do not contain import relation.
* It can be reconstructed by DGLModImport. * It can be reconstructed by DGLModImport.
*/ */
DGL_DLL int DGLModLoadFromFile( DGL_DLL int DGLModLoadFromFile(
const char* file_name, const char* format, DGLModuleHandle* out); const char* file_name, const char* format, DGLModuleHandle* out);
/*! /*!
* \brief Add dep to mod's dependency. * @brief Add dep to mod's dependency.
* This allows functions in this module to use modules. * This allows functions in this module to use modules.
* *
* \param mod The module handle. * @param mod The module handle.
* \param dep The dependent module to be imported. * @param dep The dependent module to be imported.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLModImport(DGLModuleHandle mod, DGLModuleHandle dep); DGL_DLL int DGLModImport(DGLModuleHandle mod, DGLModuleHandle dep);
/*! /*!
* \brief Get function from the module. * @brief Get function from the module.
* \param mod The module handle. * @param mod The module handle.
* \param func_name The name of the function. * @param func_name The name of the function.
* \param query_imports Whether to query imported modules * @param query_imports Whether to query imported modules
* \param out The result function, can be NULL if it is not available. * @param out The result function, can be NULL if it is not available.
* \return 0 when no error is thrown, -1 when failure happens * @return 0 when no error is thrown, -1 when failure happens
*/ */
DGL_DLL int DGLModGetFunction( DGL_DLL int DGLModGetFunction(
DGLModuleHandle mod, const char* func_name, int query_imports, DGLModuleHandle mod, const char* func_name, int query_imports,
DGLFunctionHandle* out); DGLFunctionHandle* out);
/*! /*!
* \brief Free front-end extension type resource. * @brief Free front-end extension type resource.
* \param handle The extension handle. * @param handle The extension handle.
* \param type_code The type of of the extension type. * @param type_code The type of of the extension type.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLExtTypeFree(void* handle, int type_code); DGL_DLL int DGLExtTypeFree(void* handle, int type_code);
/*! /*!
* \brief Free the Module * @brief Free the Module
* \param mod The module to be freed. * @param mod The module to be freed.
* *
* \note This may not free up the module's resources. * @note This may not free up the module's resources.
* If there is active DGLFunctionHandle uses the module * If there is active DGLFunctionHandle uses the module
* Or if this module is imported by another active module. * Or if this module is imported by another active module.
* *
* The all functions remains valid until DGLFuncFree is called. * The all functions remains valid until DGLFuncFree is called.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLModFree(DGLModuleHandle mod); DGL_DLL int DGLModFree(DGLModuleHandle mod);
/*! /*!
* \brief Free the function when it is no longer needed. * @brief Free the function when it is no longer needed.
* \param func The function handle * @param func The function handle
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLFuncFree(DGLFunctionHandle func); DGL_DLL int DGLFuncFree(DGLFunctionHandle func);
/*! /*!
* \brief Call a Packed DGL Function. * @brief Call a Packed DGL Function.
* *
* \param func node handle of the function. * @param func node handle of the function.
* \param arg_values The arguments * @param arg_values The arguments
* \param type_codes The type codes of the arguments * @param type_codes The type codes of the arguments
* \param num_args Number of arguments. * @param num_args Number of arguments.
* *
* \param ret_val The return value. * @param ret_val The return value.
* \param ret_type_code the type code of return value. * @param ret_type_code the type code of return value.
* *
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
* \note DGL calls always exchanges with type bits=64, lanes=1 * @note DGL calls always exchanges with type bits=64, lanes=1
* *
* \note API calls always exchanges with type bits=64, lanes=1 * @note API calls always exchanges with type bits=64, lanes=1
* If API call returns container handles (e.g. FunctionHandle) * If API call returns container handles (e.g. FunctionHandle)
* these handles should be managed by the front-end. * these handles should be managed by the front-end.
* The front-end need to call free function (e.g. DGLFuncFree) * The front-end need to call free function (e.g. DGLFuncFree)
...@@ -337,40 +337,40 @@ DGL_DLL int DGLFuncCall( ...@@ -337,40 +337,40 @@ DGL_DLL int DGLFuncCall(
DGLValue* ret_val, int* ret_type_code); DGLValue* ret_val, int* ret_type_code);
/*! /*!
* \brief Set the return value of DGLPackedCFunc. * @brief Set the return value of DGLPackedCFunc.
* *
* This function is called by DGLPackedCFunc to set the return value. * This function is called by DGLPackedCFunc to set the return value.
* When this function is not called, the function returns null by default. * When this function is not called, the function returns null by default.
* *
* \param ret The return value handle, pass by ret in DGLPackedCFunc * @param ret The return value handle, pass by ret in DGLPackedCFunc
* \param value The value to be returned. * @param value The value to be returned.
* \param type_code The type of the value to be returned. * @param type_code The type of the value to be returned.
* \param num_ret Number of return values, for now only 1 is supported. * @param num_ret Number of return values, for now only 1 is supported.
*/ */
DGL_DLL int DGLCFuncSetReturn( DGL_DLL int DGLCFuncSetReturn(
DGLRetValueHandle ret, DGLValue* value, int* type_code, int num_ret); DGLRetValueHandle ret, DGLValue* value, int* type_code, int num_ret);
/*! /*!
* \brief Inplace translate callback argument value to return value. * @brief Inplace translate callback argument value to return value.
* This is only needed for non-POD arguments. * This is only needed for non-POD arguments.
* *
* \param value The value to be translated. * @param value The value to be translated.
* \param code The type code to be translated. * @param code The type code to be translated.
* \note This function will do a shallow copy when necessary. * @note This function will do a shallow copy when necessary.
* *
* \return 0 when success, -1 when failure happens. * @return 0 when success, -1 when failure happens.
*/ */
DGL_DLL int DGLCbArgToReturn(DGLValue* value, int code); DGL_DLL int DGLCbArgToReturn(DGLValue* value, int code);
/*! /*!
* \brief C type of packed function. * @brief C type of packed function.
* *
* \param args The arguments * @param args The arguments
* \param type_codes The type codes of the arguments * @param type_codes The type codes of the arguments
* \param num_args Number of arguments. * @param num_args Number of arguments.
* \param ret The return value handle. * @param ret The return value handle.
* \param resource_handle The handle additional resouce handle from fron-end. * @param resource_handle The handle additional resouce handle from fron-end.
* \return 0 if success, -1 if failure happens, set error via * @return 0 if success, -1 if failure happens, set error via
* DGLAPISetLastError. * DGLAPISetLastError.
* \sa DGLCFuncSetReturn * \sa DGLCFuncSetReturn
*/ */
...@@ -379,235 +379,235 @@ typedef int (*DGLPackedCFunc)( ...@@ -379,235 +379,235 @@ typedef int (*DGLPackedCFunc)(
void* resource_handle); void* resource_handle);
/*! /*!
* \brief C callback to free the resource handle in C packed function. * @brief C callback to free the resource handle in C packed function.
* \param resource_handle The handle additional resouce handle from fron-end. * @param resource_handle The handle additional resouce handle from fron-end.
*/ */
typedef void (*DGLPackedCFuncFinalizer)(void* resource_handle); typedef void (*DGLPackedCFuncFinalizer)(void* resource_handle);
/*! /*!
* \brief Signature for extension function declarer. * @brief Signature for extension function declarer.
* *
* DGL call this function to get the extension functions * DGL call this function to get the extension functions
* The declarer will call register_func to register function and their name. * The declarer will call register_func to register function and their name.
* *
* \param register_func_handle The register function * @param register_func_handle The register function
* \return 0 if success, -1 if failure happens * @return 0 if success, -1 if failure happens
*/ */
typedef int (*DGLExtensionFuncDeclarer)(DGLFunctionHandle register_func_handle); typedef int (*DGLExtensionFuncDeclarer)(DGLFunctionHandle register_func_handle);
/*! /*!
* \brief Wrap a DGLPackedCFunc to become a FunctionHandle. * @brief Wrap a DGLPackedCFunc to become a FunctionHandle.
* *
* The resource_handle will be managed by DGL API, until the function is no * The resource_handle will be managed by DGL API, until the function is no
* longer used. * longer used.
* *
* \param func The packed C function. * @param func The packed C function.
* \param resource_handle The resource handle from front-end, can be NULL. * @param resource_handle The resource handle from front-end, can be NULL.
* \param fin The finalizer on resource handle when the FunctionHandle get * @param fin The finalizer on resource handle when the FunctionHandle get
* freed, can be NULL. * freed, can be NULL.
* \param out the result function handle. * @param out the result function handle.
* \return 0 when success, -1 when failure happens. * @return 0 when success, -1 when failure happens.
*/ */
DGL_DLL int DGLFuncCreateFromCFunc( DGL_DLL int DGLFuncCreateFromCFunc(
DGLPackedCFunc func, void* resource_handle, DGLPackedCFuncFinalizer fin, DGLPackedCFunc func, void* resource_handle, DGLPackedCFuncFinalizer fin,
DGLFunctionHandle* out); DGLFunctionHandle* out);
/*! /*!
* \brief Register the function to runtime's global table. * @brief Register the function to runtime's global table.
* *
* The registered function then can be pulled by the backend by the name. * The registered function then can be pulled by the backend by the name.
* *
* \param name The name of the function. * @param name The name of the function.
* \param f The function to be registered. * @param f The function to be registered.
* \param override Whether allow override already registered function. * @param override Whether allow override already registered function.
*/ */
DGL_DLL int DGLFuncRegisterGlobal( DGL_DLL int DGLFuncRegisterGlobal(
const char* name, DGLFunctionHandle f, int override); const char* name, DGLFunctionHandle f, int override);
/*! /*!
* \brief Get a global function. * @brief Get a global function.
* *
* \param name The name of the function. * @param name The name of the function.
* \param out the result function pointer, NULL if it does not exist. * @param out the result function pointer, NULL if it does not exist.
* *
* \note The function handle of global function is managed by DGL runtime, * @note The function handle of global function is managed by DGL runtime,
* So DGLFuncFree is should not be called when it get deleted. * So DGLFuncFree is should not be called when it get deleted.
*/ */
DGL_DLL int DGLFuncGetGlobal(const char* name, DGLFunctionHandle* out); DGL_DLL int DGLFuncGetGlobal(const char* name, DGLFunctionHandle* out);
/*! /*!
* \brief List all the globally registered function name * @brief List all the globally registered function name
* \param out_size The number of functions * @param out_size The number of functions
* \param out_array The array of function names. * @param out_array The array of function names.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLFuncListGlobalNames(int* out_size, const char*** out_array); DGL_DLL int DGLFuncListGlobalNames(int* out_size, const char*** out_array);
// Array related apis for quick proptyping // Array related apis for quick proptyping
/*! /*!
* \brief Allocate a nd-array's memory, * @brief Allocate a nd-array's memory,
* including space of shape, of given spec. * including space of shape, of given spec.
* *
* \param shape The shape of the array, the data content will be copied to out * @param shape The shape of the array, the data content will be copied to out
* \param ndim The number of dimension of the array. * @param ndim The number of dimension of the array.
* \param dtype_code The type code of the dtype * @param dtype_code The type code of the dtype
* \param dtype_bits The number of bits of dtype * @param dtype_bits The number of bits of dtype
* \param dtype_lanes The number of lanes in the dtype. * @param dtype_lanes The number of lanes in the dtype.
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context. * @param device_id The device id of context.
* \param out The output handle. * @param out The output handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayAlloc( DGL_DLL int DGLArrayAlloc(
const dgl_index_t* shape, int ndim, int dtype_code, int dtype_bits, const dgl_index_t* shape, int ndim, int dtype_code, int dtype_bits,
int dtype_lanes, int device_type, int device_id, DGLArrayHandle* out); int dtype_lanes, int device_type, int device_id, DGLArrayHandle* out);
/*! /*!
* \brief Allocate a nd-array's with shared memory, * @brief Allocate a nd-array's with shared memory,
* including space of shape, of given spec. * including space of shape, of given spec.
* *
* \param the name of the shared memory * @param the name of the shared memory
* \param shape The shape of the array, the data content will be copied to out * @param shape The shape of the array, the data content will be copied to out
* \param ndim The number of dimension of the array. * @param ndim The number of dimension of the array.
* \param dtype_code The type code of the dtype * @param dtype_code The type code of the dtype
* \param dtype_bits The number of bits of dtype * @param dtype_bits The number of bits of dtype
* \param dtype_lanes The number of lanes in the dtype. * @param dtype_lanes The number of lanes in the dtype.
* \param is_create whether the shared memory is created * @param is_create whether the shared memory is created
* \param out The output handle. * @param out The output handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
int DGLArrayAllocSharedMem( int DGLArrayAllocSharedMem(
const char* mem_name, const dgl_index_t* shape, int ndim, int dtype_code, const char* mem_name, const dgl_index_t* shape, int ndim, int dtype_code,
int dtype_bits, int dtype_lanes, bool is_create, DGLArrayHandle* out); int dtype_bits, int dtype_lanes, bool is_create, DGLArrayHandle* out);
/*! /*!
* \brief Free the DGL Array. * @brief Free the DGL Array.
* \param handle The array handle to be freed. * @param handle The array handle to be freed.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayFree(DGLArrayHandle handle); DGL_DLL int DGLArrayFree(DGLArrayHandle handle);
/*! /*!
* \brief Copy array data from CPU byte array. * @brief Copy array data from CPU byte array.
* \param handle The array handle. * @param handle The array handle.
* \param data the data pointer * @param data the data pointer
* \param nbytes The number of bytes to copy. * @param nbytes The number of bytes to copy.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayCopyFromBytes( DGL_DLL int DGLArrayCopyFromBytes(
DGLArrayHandle handle, void* data, size_t nbytes); DGLArrayHandle handle, void* data, size_t nbytes);
/*! /*!
* \brief Copy array data to CPU byte array. * @brief Copy array data to CPU byte array.
* \param handle The array handle. * @param handle The array handle.
* \param data the data pointer * @param data the data pointer
* \param nbytes The number of bytes to copy. * @param nbytes The number of bytes to copy.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayCopyToBytes( DGL_DLL int DGLArrayCopyToBytes(
DGLArrayHandle handle, void* data, size_t nbytes); DGLArrayHandle handle, void* data, size_t nbytes);
/*! /*!
* \brief Copy the array, both from and to must be valid during the copy. * @brief Copy the array, both from and to must be valid during the copy.
* \param from The array to be copied from. * @param from The array to be copied from.
* \param to The target space. * @param to The target space.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayCopyFromTo(DGLArrayHandle from, DGLArrayHandle to); DGL_DLL int DGLArrayCopyFromTo(DGLArrayHandle from, DGLArrayHandle to);
/*! /*!
* \brief Create a new runtime stream. * @brief Create a new runtime stream.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context * @param device_id The device id of context
* \param out The new stream handle * @param out The new stream handle
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLStreamCreate( DGL_DLL int DGLStreamCreate(
int device_type, int device_id, DGLStreamHandle* out); int device_type, int device_id, DGLStreamHandle* out);
/*! /*!
* \brief Free a created stream handle. * @brief Free a created stream handle.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context * @param device_id The device id of context
* \param stream The stream to be freed * @param stream The stream to be freed
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLStreamFree( DGL_DLL int DGLStreamFree(
int device_type, int device_id, DGLStreamHandle stream); int device_type, int device_id, DGLStreamHandle stream);
/*! /*!
* \brief Set the runtime stream of current thread to be stream. * @brief Set the runtime stream of current thread to be stream.
* The subsequent calls to the same device_type * The subsequent calls to the same device_type
* will use the setted stream handle. * will use the setted stream handle.
* The specific type of stream is runtime device dependent. * The specific type of stream is runtime device dependent.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context. * @param device_id The device id of context.
* \param handle The stream handle. * @param handle The stream handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLSetStream( DGL_DLL int DGLSetStream(
int device_type, int device_id, DGLStreamHandle handle); int device_type, int device_id, DGLStreamHandle handle);
/*! /*!
* \brief Get the runtime stream of current thread. * @brief Get the runtime stream of current thread.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context. * @param device_id The device id of context.
* \param handle The stream handle. * @param handle The stream handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLGetStream( DGL_DLL int DGLGetStream(
int device_type, int device_id, DGLStreamHandle* handle); int device_type, int device_id, DGLStreamHandle* handle);
/*! /*!
* \brief Wait until all computations on stream completes. * @brief Wait until all computations on stream completes.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context. * @param device_id The device id of context.
* \param stream The stream to be synchronized. * @param stream The stream to be synchronized.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLSynchronize( DGL_DLL int DGLSynchronize(
int device_type, int device_id, DGLStreamHandle stream); int device_type, int device_id, DGLStreamHandle stream);
/*! /*!
* \brief Synchronize two streams of execution. * @brief Synchronize two streams of execution.
* *
* \param device_type The device type of context * @param device_type The device type of context
* \param device_id The device id of context * @param device_id The device id of context
* \param src The source stream to synchronize. * @param src The source stream to synchronize.
* \param dst The destination stream to synchronize. * @param dst The destination stream to synchronize.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLStreamStreamSynchronize( DGL_DLL int DGLStreamStreamSynchronize(
int device_type, int device_id, DGLStreamHandle src, DGLStreamHandle dst); int device_type, int device_id, DGLStreamHandle src, DGLStreamHandle dst);
/*! /*!
* \brief Load tensor adapter. * @brief Load tensor adapter.
* \return 0 when success, -1 when failure happens. * @return 0 when success, -1 when failure happens.
*/ */
DGL_DLL int DGLLoadTensorAdapter(const char* path); DGL_DLL int DGLLoadTensorAdapter(const char* path);
/*! /*!
* \brief Pin host memory. * @brief Pin host memory.
*/ */
int DGLArrayPinData(DGLArrayHandle handle, DGLContext ctx); int DGLArrayPinData(DGLArrayHandle handle, DGLContext ctx);
/*! /*!
* \brief Unpin host memory. * @brief Unpin host memory.
*/ */
int DGLArrayUnpinData(DGLArrayHandle handle, DGLContext ctx); int DGLArrayUnpinData(DGLArrayHandle handle, DGLContext ctx);
/*! /*!
* \brief Record the stream that's using this tensor. * @brief Record the stream that's using this tensor.
*/ */
int DGLArrayRecordStream(DGLArrayHandle handle, DGLStreamHandle stream); int DGLArrayRecordStream(DGLArrayHandle handle, DGLStreamHandle stream);
/*! /*!
* \brief Bug report macro. * @brief Bug report macro.
* *
* This serves as a sanity check on system side to make sure the code is correct * This serves as a sanity check on system side to make sure the code is correct
* by checking whether a condition always holds for complex reasons. Failing * by checking whether a condition always holds for complex reasons. Failing
......
include/dgl/runtime/config.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2019 by Contributors * Copyright (c) 2019 by Contributors
* \file runtime/config.h * @file runtime/config.h
* \brief DGL runtime config * @brief DGL runtime config
*/ */
#ifndef DGL_RUNTIME_CONFIG_H_ #ifndef DGL_RUNTIME_CONFIG_H_
......
include/dgl/runtime/container.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2019 by Contributors * Copyright (c) 2019 by Contributors
* \file runtime/container.h * @file runtime/container.h
* \brief Defines the container object data structures. * @brief Defines the container object data structures.
*/ */
#ifndef DGL_RUNTIME_CONTAINER_H_ #ifndef DGL_RUNTIME_CONTAINER_H_
#define DGL_RUNTIME_CONTAINER_H_ #define DGL_RUNTIME_CONTAINER_H_
...@@ -19,21 +19,21 @@ namespace dgl { ...@@ -19,21 +19,21 @@ namespace dgl {
namespace runtime { namespace runtime {
/*! /*!
* \brief value object. * @brief value object.
* *
* It is typically used to wrap a non-Object type to Object type. * It is typically used to wrap a non-Object type to Object type.
* Any type that is supported by DGLRetValue is supported by this. * Any type that is supported by DGLRetValue is supported by this.
*/ */
class ValueObject : public Object { class ValueObject : public Object {
public: public:
/*! \brief the value data */ /*! @brief the value data */
DGLRetValue data; DGLRetValue data;
static constexpr const char* _type_key = "Value"; static constexpr const char* _type_key = "Value";
DGL_DECLARE_OBJECT_TYPE_INFO(ValueObject, Object); DGL_DECLARE_OBJECT_TYPE_INFO(ValueObject, Object);
}; };
/*! \brief Construct a value object. */ /*! @brief Construct a value object. */
template <typename T> template <typename T>
inline std::shared_ptr<ValueObject> MakeValue(T&& val) { inline std::shared_ptr<ValueObject> MakeValue(T&& val) {
auto obj = std::make_shared<ValueObject>(); auto obj = std::make_shared<ValueObject>();
...@@ -41,7 +41,7 @@ inline std::shared_ptr<ValueObject> MakeValue(T&& val) { ...@@ -41,7 +41,7 @@ inline std::shared_ptr<ValueObject> MakeValue(T&& val) {
return obj; return obj;
} }
/*! \brief Vallue reference type */ /*! @brief Vallue reference type */
class Value : public ObjectRef { class Value : public ObjectRef {
public: public:
Value() {} Value() {}
...@@ -54,10 +54,10 @@ class Value : public ObjectRef { ...@@ -54,10 +54,10 @@ class Value : public ObjectRef {
using ContainerType = ValueObject; using ContainerType = ValueObject;
}; };
/*! \brief list obj content in list */ /*! @brief list obj content in list */
class ListObject : public Object { class ListObject : public Object {
public: public:
/*! \brief the data content */ /*! @brief the data content */
std::vector<std::shared_ptr<Object> > data; std::vector<std::shared_ptr<Object> > data;
void VisitAttrs(AttrVisitor* visitor) final { void VisitAttrs(AttrVisitor* visitor) final {
...@@ -68,7 +68,7 @@ class ListObject : public Object { ...@@ -68,7 +68,7 @@ class ListObject : public Object {
DGL_DECLARE_OBJECT_TYPE_INFO(ListObject, Object); DGL_DECLARE_OBJECT_TYPE_INFO(ListObject, Object);
}; };
/*! \brief map obj content */ /*! @brief map obj content */
class MapObject : public Object { class MapObject : public Object {
public: public:
void VisitAttrs(AttrVisitor* visitor) final { void VisitAttrs(AttrVisitor* visitor) final {
...@@ -89,28 +89,28 @@ class MapObject : public Object { ...@@ -89,28 +89,28 @@ class MapObject : public Object {
} }
}; };
/*! \brief The corresponding conatiner type */ /*! @brief The corresponding conatiner type */
using ContainerType = std::unordered_map< using ContainerType = std::unordered_map<
std::shared_ptr<Object>, std::shared_ptr<Object>, Hash, Equal>; std::shared_ptr<Object>, std::shared_ptr<Object>, Hash, Equal>;
/*! \brief the data content */ /*! @brief the data content */
ContainerType data; ContainerType data;
static constexpr const char* _type_key = "Map"; static constexpr const char* _type_key = "Map";
DGL_DECLARE_OBJECT_TYPE_INFO(MapObject, Object); DGL_DECLARE_OBJECT_TYPE_INFO(MapObject, Object);
}; };
/*! \brief specialized map obj with string as key */ /*! @brief specialized map obj with string as key */
class StrMapObject : public Object { class StrMapObject : public Object {
public: public:
void VisitAttrs(AttrVisitor* visitor) final { void VisitAttrs(AttrVisitor* visitor) final {
// Visitor to map have no effect. // Visitor to map have no effect.
} }
/*! \brief The corresponding conatiner type */ /*! @brief The corresponding conatiner type */
using ContainerType = using ContainerType =
std::unordered_map<std::string, std::shared_ptr<Object> >; std::unordered_map<std::string, std::shared_ptr<Object> >;
/*! \brief the data content */ /*! @brief the data content */
ContainerType data; ContainerType data;
static constexpr const char* _type_key = "StrMap"; static constexpr const char* _type_key = "StrMap";
...@@ -118,9 +118,9 @@ class StrMapObject : public Object { ...@@ -118,9 +118,9 @@ class StrMapObject : public Object {
}; };
/*! /*!
* \brief iterator adapter that adapts TIter to return another type. * @brief iterator adapter that adapts TIter to return another type.
* \tparam Converter a struct that contains converting function * @tparam Converter a struct that contains converting function
* \tparam TIter the content iterator type. * @tparam TIter the content iterator type.
*/ */
template <typename Converter, typename TIter> template <typename Converter, typename TIter>
class IterAdapter { class IterAdapter {
...@@ -150,7 +150,7 @@ class IterAdapter { ...@@ -150,7 +150,7 @@ class IterAdapter {
}; };
/*! /*!
* \brief List container of ObjectRef. * @brief List container of ObjectRef.
* *
* List implements copy on write semantics, which means list is mutable * List implements copy on write semantics, which means list is mutable
* but copy will happen when list is referenced in more than two places. * but copy will happen when list is referenced in more than two places.
...@@ -161,9 +161,9 @@ class IterAdapter { ...@@ -161,9 +161,9 @@ class IterAdapter {
* *
* operator[] only provide const access, use Set to mutate the content. * operator[] only provide const access, use Set to mutate the content.
* *
* \tparam T The content ObjectRef type. * @tparam T The content ObjectRef type.
* *
* \note The element type must subclass \c ObjectRef. Otherwise, the * @note The element type must subclass \c ObjectRef. Otherwise, the
* compiler would throw an error: * compiler would throw an error:
* *
* <code> * <code>
...@@ -188,53 +188,53 @@ template < ...@@ -188,53 +188,53 @@ template <
class List : public ObjectRef { class List : public ObjectRef {
public: public:
/*! /*!
* \brief default constructor * @brief default constructor
*/ */
List() { obj_ = std::make_shared<ListObject>(); } List() { obj_ = std::make_shared<ListObject>(); }
/*! /*!
* \brief move constructor * @brief move constructor
* \param other source * @param other source
*/ */
List(List<T>&& other) { // NOLINT(*) List(List<T>&& other) { // NOLINT(*)
obj_ = std::move(other.obj_); obj_ = std::move(other.obj_);
} }
/*! /*!
* \brief copy constructor * @brief copy constructor
* \param other source * @param other source
*/ */
List(const List<T>& other) : ObjectRef(other.obj_) { // NOLINT(*) List(const List<T>& other) : ObjectRef(other.obj_) { // NOLINT(*)
} }
/*! /*!
* \brief constructor from pointer * @brief constructor from pointer
* \param n the container pointer * @param n the container pointer
*/ */
explicit List(std::shared_ptr<Object> n) : ObjectRef(n) {} explicit List(std::shared_ptr<Object> n) : ObjectRef(n) {}
/*! /*!
* \brief constructor from iterator * @brief constructor from iterator
* \param begin begin of iterator * @param begin begin of iterator
* \param end end of iterator * @param end end of iterator
* \tparam IterType The type of iterator * @tparam IterType The type of iterator
*/ */
template <typename IterType> template <typename IterType>
List(IterType begin, IterType end) { List(IterType begin, IterType end) {
assign(begin, end); assign(begin, end);
} }
/*! /*!
* \brief constructor from initializer list * @brief constructor from initializer list
* \param init The initalizer list * @param init The initalizer list
*/ */
List(std::initializer_list<T> init) { // NOLINT(*) List(std::initializer_list<T> init) { // NOLINT(*)
assign(init.begin(), init.end()); assign(init.begin(), init.end());
} }
/*! /*!
* \brief constructor from vector * @brief constructor from vector
* \param init The vector * @param init The vector
*/ */
List(const std::vector<T>& init) { // NOLINT(*) List(const std::vector<T>& init) { // NOLINT(*)
assign(init.begin(), init.end()); assign(init.begin(), init.end());
} }
/*! /*!
* \brief Constructs a container with n elements. Each element is a copy of * @brief Constructs a container with n elements. Each element is a copy of
* val \param n The size of the container \param val The init value * val \param n The size of the container \param val The init value
*/ */
explicit List(size_t n, const T& val) { explicit List(size_t n, const T& val) {
...@@ -245,28 +245,28 @@ class List : public ObjectRef { ...@@ -245,28 +245,28 @@ class List : public ObjectRef {
obj_ = std::move(tmp_obj); obj_ = std::move(tmp_obj);
} }
/*! /*!
* \brief move assign operator * @brief move assign operator
* \param other The source of assignment * @param other The source of assignment
* \return reference to self. * @return reference to self.
*/ */
List<T>& operator=(List<T>&& other) { List<T>& operator=(List<T>&& other) {
obj_ = std::move(other.obj_); obj_ = std::move(other.obj_);
return *this; return *this;
} }
/*! /*!
* \brief copy assign operator * @brief copy assign operator
* \param other The source of assignment * @param other The source of assignment
* \return reference to self. * @return reference to self.
*/ */
List<T>& operator=(const List<T>& other) { List<T>& operator=(const List<T>& other) {
obj_ = other.obj_; obj_ = other.obj_;
return *this; return *this;
} }
/*! /*!
* \brief reset the list to content from iterator. * @brief reset the list to content from iterator.
* \param begin begin of iterator * @param begin begin of iterator
* \param end end of iterator * @param end end of iterator
* \tparam IterType The type of iterator * @tparam IterType The type of iterator
*/ */
template <typename IterType> template <typename IterType>
void assign(IterType begin, IterType end) { void assign(IterType begin, IterType end) {
...@@ -277,9 +277,9 @@ class List : public ObjectRef { ...@@ -277,9 +277,9 @@ class List : public ObjectRef {
obj_ = std::move(n); obj_ = std::move(n);
} }
/*! /*!
* \brief Read i-th element from list. * @brief Read i-th element from list.
* \param i The index * @param i The index
* \return the i-th element. * @return the i-th element.
*/ */
inline const T operator[](size_t i) const { inline const T operator[](size_t i) const {
return T(static_cast<const ListObject*>(obj_.get())->data[i]); return T(static_cast<const ListObject*>(obj_.get())->data[i]);
...@@ -290,12 +290,12 @@ class List : public ObjectRef { ...@@ -290,12 +290,12 @@ class List : public ObjectRef {
return static_cast<const ListObject*>(obj_.get())->data.size(); return static_cast<const ListObject*>(obj_.get())->data.size();
} }
/*! /*!
* \brief copy on write semantics * @brief copy on write semantics
* Do nothing if current handle is the unique copy of the list. * Do nothing if current handle is the unique copy of the list.
* Otherwise make a new copy of the list to ensure the current handle * Otherwise make a new copy of the list to ensure the current handle
* hold a unique copy. * hold a unique copy.
* *
* \return Handle to the internal obj container(which ganrantees to be unique) * @return Handle to the internal obj container(which ganrantees to be unique)
*/ */
inline ListObject* CopyOnWrite() { inline ListObject* CopyOnWrite() {
if (obj_.get() == nullptr || !obj_.unique()) { if (obj_.get() == nullptr || !obj_.unique()) {
...@@ -305,17 +305,17 @@ class List : public ObjectRef { ...@@ -305,17 +305,17 @@ class List : public ObjectRef {
return static_cast<ListObject*>(obj_.get()); return static_cast<ListObject*>(obj_.get());
} }
/*! /*!
* \brief push a new item to the back of the list * @brief push a new item to the back of the list
* \param item The item to be pushed. * @param item The item to be pushed.
*/ */
inline void push_back(const T& item) { inline void push_back(const T& item) {
ListObject* n = this->CopyOnWrite(); ListObject* n = this->CopyOnWrite();
n->data.push_back(item.obj_); n->data.push_back(item.obj_);
} }
/*! /*!
* \brief set i-th element of the list. * @brief set i-th element of the list.
* \param i The index * @param i The index
* \param value The value to be setted. * @param value The value to be setted.
*/ */
inline void Set(size_t i, const T& value) { inline void Set(size_t i, const T& value) {
ListObject* n = this->CopyOnWrite(); ListObject* n = this->CopyOnWrite();
...@@ -323,11 +323,11 @@ class List : public ObjectRef { ...@@ -323,11 +323,11 @@ class List : public ObjectRef {
} }
/*! \return whether list is empty */ /*! \return whether list is empty */
inline bool empty() const { return size() == 0; } inline bool empty() const { return size() == 0; }
/*! \brief Copy the content to a vector */ /*! @brief Copy the content to a vector */
inline std::vector<T> ToVector() const { inline std::vector<T> ToVector() const {
return std::vector<T>(begin(), end()); return std::vector<T>(begin(), end());
} }
/*! \brief specify container obj */ /*! @brief specify container obj */
using ContainerType = ListObject; using ContainerType = ListObject;
struct Ptr2ObjectRef { struct Ptr2ObjectRef {
...@@ -362,7 +362,7 @@ class List : public ObjectRef { ...@@ -362,7 +362,7 @@ class List : public ObjectRef {
}; };
/*! /*!
* \brief Map container of ObjectRef->ObjectRef. * @brief Map container of ObjectRef->ObjectRef.
* *
* Map implements copy on write semantics, which means map is mutable * Map implements copy on write semantics, which means map is mutable
* but copy will happen when list is referenced in more than two places. * but copy will happen when list is referenced in more than two places.
...@@ -373,10 +373,10 @@ class List : public ObjectRef { ...@@ -373,10 +373,10 @@ class List : public ObjectRef {
* *
* operator[] only provide const acces, use Set to mutate the content. * operator[] only provide const acces, use Set to mutate the content.
* *
* \tparam K The key ObjectRef type. * @tparam K The key ObjectRef type.
* \tparam V The value ObjectRef type. * @tparam V The value ObjectRef type.
* *
* \note The element type must subclass \c ObjectRef. Otherwise, the * @note The element type must subclass \c ObjectRef. Otherwise, the
* compiler would throw an error: * compiler would throw an error:
* *
* <code> * <code>
...@@ -404,75 +404,75 @@ template < ...@@ -404,75 +404,75 @@ template <
class Map : public ObjectRef { class Map : public ObjectRef {
public: public:
/*! /*!
* \brief default constructor * @brief default constructor
*/ */
Map() { obj_ = std::make_shared<MapObject>(); } Map() { obj_ = std::make_shared<MapObject>(); }
/*! /*!
* \brief move constructor * @brief move constructor
* \param other source * @param other source
*/ */
Map(Map<K, V>&& other) { // NOLINT(*) Map(Map<K, V>&& other) { // NOLINT(*)
obj_ = std::move(other.obj_); obj_ = std::move(other.obj_);
} }
/*! /*!
* \brief copy constructor * @brief copy constructor
* \param other source * @param other source
*/ */
Map(const Map<K, V>& other) : ObjectRef(other.obj_) { // NOLINT(*) Map(const Map<K, V>& other) : ObjectRef(other.obj_) { // NOLINT(*)
} }
/*! /*!
* \brief constructor from pointer * @brief constructor from pointer
* \param n the container pointer * @param n the container pointer
*/ */
explicit Map(std::shared_ptr<Object> n) : ObjectRef(n) {} explicit Map(std::shared_ptr<Object> n) : ObjectRef(n) {}
/*! /*!
* \brief constructor from iterator * @brief constructor from iterator
* \param begin begin of iterator * @param begin begin of iterator
* \param end end of iterator * @param end end of iterator
* \tparam IterType The type of iterator * @tparam IterType The type of iterator
*/ */
template <typename IterType> template <typename IterType>
Map(IterType begin, IterType end) { Map(IterType begin, IterType end) {
assign(begin, end); assign(begin, end);
} }
/*! /*!
* \brief constructor from initializer list * @brief constructor from initializer list
* \param init The initalizer list * @param init The initalizer list
*/ */
Map(std::initializer_list<std::pair<K, V> > init) { // NOLINT(*) Map(std::initializer_list<std::pair<K, V> > init) { // NOLINT(*)
assign(init.begin(), init.end()); assign(init.begin(), init.end());
} }
/*! /*!
* \brief constructor from vector * @brief constructor from vector
* \param init The vector * @param init The vector
*/ */
template <typename Hash, typename Equal> template <typename Hash, typename Equal>
Map(const std::unordered_map<K, V, Hash, Equal>& init) { // NOLINT(*) Map(const std::unordered_map<K, V, Hash, Equal>& init) { // NOLINT(*)
assign(init.begin(), init.end()); assign(init.begin(), init.end());
} }
/*! /*!
* \brief move assign operator * @brief move assign operator
* \param other The source of assignment * @param other The source of assignment
* \return reference to self. * @return reference to self.
*/ */
Map<K, V>& operator=(Map<K, V>&& other) { Map<K, V>& operator=(Map<K, V>&& other) {
obj_ = std::move(other.obj_); obj_ = std::move(other.obj_);
return *this; return *this;
} }
/*! /*!
* \brief copy assign operator * @brief copy assign operator
* \param other The source of assignment * @param other The source of assignment
* \return reference to self. * @return reference to self.
*/ */
Map<K, V>& operator=(const Map<K, V>& other) { Map<K, V>& operator=(const Map<K, V>& other) {
obj_ = other.obj_; obj_ = other.obj_;
return *this; return *this;
} }
/*! /*!
* \brief reset the list to content from iterator. * @brief reset the list to content from iterator.
* \param begin begin of iterator * @param begin begin of iterator
* \param end end of iterator * @param end end of iterator
* \tparam IterType The type of iterator * @tparam IterType The type of iterator
*/ */
template <typename IterType> template <typename IterType>
void assign(IterType begin, IterType end) { void assign(IterType begin, IterType end) {
...@@ -483,17 +483,17 @@ class Map : public ObjectRef { ...@@ -483,17 +483,17 @@ class Map : public ObjectRef {
obj_ = std::move(n); obj_ = std::move(n);
} }
/*! /*!
* \brief Read element from map. * @brief Read element from map.
* \param key The key * @param key The key
* \return the corresonding element. * @return the corresonding element.
*/ */
inline const V operator[](const K& key) const { inline const V operator[](const K& key) const {
return V(static_cast<const MapObject*>(obj_.get())->data.at(key.obj_)); return V(static_cast<const MapObject*>(obj_.get())->data.at(key.obj_));
} }
/*! /*!
* \brief Read element from map. * @brief Read element from map.
* \param key The key * @param key The key
* \return the corresonding element. * @return the corresonding element.
*/ */
inline const V at(const K& key) const { inline const V at(const K& key) const {
return V(static_cast<const MapObject*>(obj_.get())->data.at(key.obj_)); return V(static_cast<const MapObject*>(obj_.get())->data.at(key.obj_));
...@@ -509,12 +509,12 @@ class Map : public ObjectRef { ...@@ -509,12 +509,12 @@ class Map : public ObjectRef {
return static_cast<const MapObject*>(obj_.get())->data.count(key.obj_); return static_cast<const MapObject*>(obj_.get())->data.count(key.obj_);
} }
/*! /*!
* \brief copy on write semantics * @brief copy on write semantics
* Do nothing if current handle is the unique copy of the list. * Do nothing if current handle is the unique copy of the list.
* Otherwise make a new copy of the list to ensure the current handle * Otherwise make a new copy of the list to ensure the current handle
* hold a unique copy. * hold a unique copy.
* *
* \return Handle to the internal obj container(which ganrantees to be unique) * @return Handle to the internal obj container(which ganrantees to be unique)
*/ */
inline MapObject* CopyOnWrite() { inline MapObject* CopyOnWrite() {
if (obj_.get() == nullptr || !obj_.unique()) { if (obj_.get() == nullptr || !obj_.unique()) {
...@@ -524,9 +524,9 @@ class Map : public ObjectRef { ...@@ -524,9 +524,9 @@ class Map : public ObjectRef {
return static_cast<MapObject*>(obj_.get()); return static_cast<MapObject*>(obj_.get());
} }
/*! /*!
* \brief set the Map. * @brief set the Map.
* \param key The index key. * @param key The index key.
* \param value The value to be setted. * @param value The value to be setted.
*/ */
inline void Set(const K& key, const V& value) { inline void Set(const K& key, const V& value) {
MapObject* n = this->CopyOnWrite(); MapObject* n = this->CopyOnWrite();
...@@ -535,7 +535,7 @@ class Map : public ObjectRef { ...@@ -535,7 +535,7 @@ class Map : public ObjectRef {
/*! \return whether list is empty */ /*! \return whether list is empty */
inline bool empty() const { return size() == 0; } inline bool empty() const { return size() == 0; }
/*! \brief specify container obj */ /*! @brief specify container obj */
using ContainerType = MapObject; using ContainerType = MapObject;
struct Ptr2ObjectRef { struct Ptr2ObjectRef {
...@@ -660,10 +660,10 @@ class Map<std::string, V, T1, T2> : public ObjectRef { ...@@ -660,10 +660,10 @@ class Map<std::string, V, T1, T2> : public ObjectRef {
}; };
/*! /*!
* \brief Helper function to convert a List<Value> object to a vector. * @brief Helper function to convert a List<Value> object to a vector.
* \tparam T element type * @tparam T element type
* \param list Input list object. * @param list Input list object.
* \return std vector * @return std vector
*/ */
template <typename T> template <typename T>
inline std::vector<T> ListValueToVector(const List<Value>& list) { inline std::vector<T> ListValueToVector(const List<Value>& list) {
......
include/dgl/runtime/device_api.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2016 by Contributors * Copyright (c) 2016 by Contributors
* \file dgl/runtime/device_api.h * @file dgl/runtime/device_api.h
* \brief Abstract device memory management API * @brief Abstract device memory management API
*/ */
#ifndef DGL_RUNTIME_DEVICE_API_H_ #ifndef DGL_RUNTIME_DEVICE_API_H_
#define DGL_RUNTIME_DEVICE_API_H_ #define DGL_RUNTIME_DEVICE_API_H_
...@@ -14,7 +14,7 @@ ...@@ -14,7 +14,7 @@
namespace dgl { namespace dgl {
namespace runtime { namespace runtime {
/*! /*!
* \brief the query type into GetAttr * @brief the query type into GetAttr
*/ */
enum DeviceAttrKind : int { enum DeviceAttrKind : int {
kExist = 0, kExist = 0,
...@@ -28,70 +28,70 @@ enum DeviceAttrKind : int { ...@@ -28,70 +28,70 @@ enum DeviceAttrKind : int {
kMaxThreadDimensions = 8 kMaxThreadDimensions = 8
}; };
/*! \brief Number of bytes each allocation must align to */ /*! @brief Number of bytes each allocation must align to */
constexpr int kAllocAlignment = 64; constexpr int kAllocAlignment = 64;
/*! \brief Number of bytes each allocation must align to in temporary allocation /*! @brief Number of bytes each allocation must align to in temporary allocation
*/ */
constexpr int kTempAllocaAlignment = 64; constexpr int kTempAllocaAlignment = 64;
/*! \brief Maximum size that can be allocated on stack */ /*! @brief Maximum size that can be allocated on stack */
constexpr int kMaxStackAlloca = 1024; constexpr int kMaxStackAlloca = 1024;
/*! /*!
* \brief DGL Runtime Device API, abstracts the device * @brief DGL Runtime Device API, abstracts the device
* specific interface for memory management. * specific interface for memory management.
*/ */
class DeviceAPI { class DeviceAPI {
public: public:
/*! \brief virtual destructor */ /*! @brief virtual destructor */
virtual ~DeviceAPI() {} virtual ~DeviceAPI() {}
/*! /*!
* \brief Check whether the device is available. * @brief Check whether the device is available.
*/ */
virtual bool IsAvailable() { return true; } virtual bool IsAvailable() { return true; }
/*! /*!
* \brief Set the environment device id to ctx * @brief Set the environment device id to ctx
* \param ctx The context to be set. * @param ctx The context to be set.
*/ */
virtual void SetDevice(DGLContext ctx) = 0; virtual void SetDevice(DGLContext ctx) = 0;
/*! /*!
* \brief Get attribute of specified device. * @brief Get attribute of specified device.
* \param ctx The device context * @param ctx The device context
* \param kind The result kind * @param kind The result kind
* \param rv The return value. * @param rv The return value.
* \sa DeviceAttrKind * \sa DeviceAttrKind
*/ */
virtual void GetAttr( virtual void GetAttr(
DGLContext ctx, DeviceAttrKind kind, DGLRetValue* rv) = 0; DGLContext ctx, DeviceAttrKind kind, DGLRetValue* rv) = 0;
/*! /*!
* \brief Allocate a data space on device. * @brief Allocate a data space on device.
* \param ctx The device context to perform operation. * @param ctx The device context to perform operation.
* \param nbytes The number of bytes in memory. * @param nbytes The number of bytes in memory.
* \param alignment The alignment of the memory. * @param alignment The alignment of the memory.
* \param type_hint The type of elements. Only needed by certain backends such * @param type_hint The type of elements. Only needed by certain backends such
* as OpenGL, as nbytes & alignment are sufficient for most backends. * as OpenGL, as nbytes & alignment are sufficient for most backends.
* \return The allocated device pointer. * @return The allocated device pointer.
*/ */
virtual void* AllocDataSpace( virtual void* AllocDataSpace(
DGLContext ctx, size_t nbytes, size_t alignment, DGLContext ctx, size_t nbytes, size_t alignment,
DGLDataType type_hint) = 0; DGLDataType type_hint) = 0;
/*! /*!
* \brief Free a data space on device. * @brief Free a data space on device.
* \param ctx The device context to perform operation. * @param ctx The device context to perform operation.
* \param ptr The data space. * @param ptr The data space.
*/ */
virtual void FreeDataSpace(DGLContext ctx, void* ptr) = 0; virtual void FreeDataSpace(DGLContext ctx, void* ptr) = 0;
/*! /*!
* \brief copy data from one place to another * @brief copy data from one place to another
* \param from The source array. * @param from The source array.
* \param from_offset The byte offeset in the from. * @param from_offset The byte offeset in the from.
* \param to The target array. * @param to The target array.
* \param to_offset The byte offset in the to. * @param to_offset The byte offset in the to.
* \param num_bytes The size of the memory in bytes * @param num_bytes The size of the memory in bytes
* \param ctx_from The source context * @param ctx_from The source context
* \param ctx_to The target context * @param ctx_to The target context
* \param type_hint The type of elements, only neded by certain backends. * @param type_hint The type of elements, only neded by certain backends.
* can be useful for cross device endian converison. * can be useful for cross device endian converison.
*/ */
virtual void CopyDataFromTo( virtual void CopyDataFromTo(
...@@ -99,73 +99,73 @@ class DeviceAPI { ...@@ -99,73 +99,73 @@ class DeviceAPI {
size_t num_bytes, DGLContext ctx_from, DGLContext ctx_to, size_t num_bytes, DGLContext ctx_from, DGLContext ctx_to,
DGLDataType type_hint) = 0; DGLDataType type_hint) = 0;
/*! /*!
* \brief Create a new stream of execution. * @brief Create a new stream of execution.
* *
* \param ctx The context of allocation. * @param ctx The context of allocation.
*/ */
DGL_DLL virtual DGLStreamHandle CreateStream(DGLContext ctx); DGL_DLL virtual DGLStreamHandle CreateStream(DGLContext ctx);
/*! /*!
* \brief Free a stream of execution * @brief Free a stream of execution
* *
* \param ctx The context of the stream * @param ctx The context of the stream
* \param stream The pointer to be freed. * @param stream The pointer to be freed.
*/ */
DGL_DLL virtual void FreeStream(DGLContext ctx, DGLStreamHandle stream); DGL_DLL virtual void FreeStream(DGLContext ctx, DGLStreamHandle stream);
/*! /*!
* \brief Synchronize the stream * @brief Synchronize the stream
* \param ctx The context to perform operation. * @param ctx The context to perform operation.
* \param stream The stream to be sync. * @param stream The stream to be sync.
*/ */
virtual void StreamSync(DGLContext ctx, DGLStreamHandle stream) = 0; virtual void StreamSync(DGLContext ctx, DGLStreamHandle stream) = 0;
/*! /*!
* \brief Set the stream * @brief Set the stream
* \param ctx The context to set stream. * @param ctx The context to set stream.
* \param stream The stream to be set. * @param stream The stream to be set.
*/ */
virtual void SetStream(DGLContext ctx, DGLStreamHandle stream) {} virtual void SetStream(DGLContext ctx, DGLStreamHandle stream) {}
/*! /*!
* \brief Get the stream * @brief Get the stream
*/ */
virtual DGLStreamHandle GetStream() const { return nullptr; } virtual DGLStreamHandle GetStream() const { return nullptr; }
/*! /*!
* \brief Synchronize 2 streams of execution. * @brief Synchronize 2 streams of execution.
* *
* An event is created in event_src stream that the second then * An event is created in event_src stream that the second then
* stream waits on. Neither event_src or event_dst need to be of * stream waits on. Neither event_src or event_dst need to be of
* the same device ID as the context, but they must be of the same * the same device ID as the context, but they must be of the same
* device type. * device type.
* *
* \param ctx The context of the streams. * @param ctx The context of the streams.
* \param event_src The source stream to synchronize. * @param event_src The source stream to synchronize.
* \param event_dst The destination stream to synchronize. * @param event_dst The destination stream to synchronize.
*/ */
DGL_DLL virtual void SyncStreamFromTo( DGL_DLL virtual void SyncStreamFromTo(
DGLContext ctx, DGLStreamHandle event_src, DGLStreamHandle event_dst); DGLContext ctx, DGLStreamHandle event_src, DGLStreamHandle event_dst);
/*! /*!
* \brief Pin host memory using cudaHostRegister(). * @brief Pin host memory using cudaHostRegister().
* *
* \param ptr The host memory pointer to be pinned. * @param ptr The host memory pointer to be pinned.
* \param nbytes The size to be pinned. * @param nbytes The size to be pinned.
*/ */
DGL_DLL virtual void PinData(void* ptr, size_t nbytes); DGL_DLL virtual void PinData(void* ptr, size_t nbytes);
/*! /*!
* \brief Unpin host memory using cudaHostUnregister(). * @brief Unpin host memory using cudaHostUnregister().
* *
* \param ptr The host memory pointer to be unpinned. * @param ptr The host memory pointer to be unpinned.
*/ */
DGL_DLL virtual void UnpinData(void* ptr); DGL_DLL virtual void UnpinData(void* ptr);
/*! /*!
* \brief Check whether the memory is in pinned memory. * @brief Check whether the memory is in pinned memory.
*/ */
DGL_DLL virtual bool IsPinned(const void* ptr) { return false; } DGL_DLL virtual bool IsPinned(const void* ptr) { return false; }
/*! /*!
* \brief Allocate temporal workspace for backend execution. * @brief Allocate temporal workspace for backend execution.
* *
* \note We have the following assumption about backend temporal * \note We have the following assumption about backend temporal
* workspace allocation, and backend will optimize for such assumption: * workspace allocation, and backend will optimize for such assumption:
...@@ -176,40 +176,40 @@ class DeviceAPI { ...@@ -176,40 +176,40 @@ class DeviceAPI {
* - Workspace should not overlap between different threads(i.e. be * - Workspace should not overlap between different threads(i.e. be
* threadlocal) * threadlocal)
* *
* \param ctx The context of allocation. * @param ctx The context of allocation.
* \param nbytes The size to be allocated. * @param nbytes The size to be allocated.
* \param type_hint The type of elements. Only needed by certain backends such * @param type_hint The type of elements. Only needed by certain backends such
* as OpenGL, as nbytes is sufficient for most backends. * as OpenGL, as nbytes is sufficient for most backends.
*/ */
DGL_DLL virtual void* AllocWorkspace( DGL_DLL virtual void* AllocWorkspace(
DGLContext ctx, size_t nbytes, DGLDataType type_hint = {}); DGLContext ctx, size_t nbytes, DGLDataType type_hint = {});
/*! /*!
* \brief Free temporal workspace in backend execution. * @brief Free temporal workspace in backend execution.
* *
* \param ctx The context of allocation. * @param ctx The context of allocation.
* \param ptr The pointer to be freed. * @param ptr The pointer to be freed.
*/ */
DGL_DLL virtual void FreeWorkspace(DGLContext ctx, void* ptr); DGL_DLL virtual void FreeWorkspace(DGLContext ctx, void* ptr);
/*! /*!
* \brief Get device API based on context. * @brief Get device API based on context.
* \param ctx The context * @param ctx The context
* \param allow_missing Whether allow missing * @param allow_missing Whether allow missing
* \return The corresponding device API. * @return The corresponding device API.
*/ */
DGL_DLL static DeviceAPI* Get(DGLContext ctx, bool allow_missing = false); DGL_DLL static DeviceAPI* Get(DGLContext ctx, bool allow_missing = false);
/*! /*!
* \brief Get device API based on context. * @brief Get device API based on context.
* \param dev_type The device type * @param dev_type The device type
* \param allow_missing Whether allow missing * @param allow_missing Whether allow missing
* \return The corresponding device API. * @return The corresponding device API.
*/ */
DGL_DLL static DeviceAPI* Get( DGL_DLL static DeviceAPI* Get(
DGLDeviceType dev_type, bool allow_missing = false); DGLDeviceType dev_type, bool allow_missing = false);
}; };
/*! \brief The device type bigger than this is RPC device */ /*! @brief The device type bigger than this is RPC device */
constexpr int kRPCSessMask = 128; constexpr int kRPCSessMask = 128;
} // namespace runtime } // namespace runtime
} // namespace dgl } // namespace dgl
......
include/dgl/runtime/dlpack_convert.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2022 by Contributors * Copyright (c) 2022 by Contributors
* \file include/dgl/runtime/dlpack_convert.h * @file include/dgl/runtime/dlpack_convert.h
* \brief Conversion between NDArray and DLPack. * @brief Conversion between NDArray and DLPack.
*/ */
#ifndef DGL_RUNTIME_DLPACK_CONVERT_H_ #ifndef DGL_RUNTIME_DLPACK_CONVERT_H_
#define DGL_RUNTIME_DLPACK_CONVERT_H_ #define DGL_RUNTIME_DLPACK_CONVERT_H_
...@@ -16,20 +16,20 @@ namespace runtime { ...@@ -16,20 +16,20 @@ namespace runtime {
struct DLPackConvert { struct DLPackConvert {
/*! /*!
* \brief Create a DGL NDArray from a DLPack tensor. * @brief Create a DGL NDArray from a DLPack tensor.
* *
* This allows us to create a NDArray using the memory * This allows us to create a NDArray using the memory
* allocated by an external deep learning framework * allocated by an external deep learning framework
* that is DLPack compatible. * that is DLPack compatible.
* *
* The memory is retained until the NDArray went out of scope. * The memory is retained until the NDArray went out of scope.
* \param tensor The DLPack tensor to copy from. * @param tensor The DLPack tensor to copy from.
* \return The created NDArray view. * @return The created NDArray view.
*/ */
static NDArray FromDLPack(DLManagedTensor* tensor); static NDArray FromDLPack(DLManagedTensor* tensor);
/*! /*!
* \brief Deleter for NDArray converted from DLPack. * @brief Deleter for NDArray converted from DLPack.
* *
* This is used from data which is passed from external * This is used from data which is passed from external
* DLPack(DLManagedTensor) that are not allocated inside of DGL. This enables * DLPack(DLManagedTensor) that are not allocated inside of DGL. This enables
...@@ -38,10 +38,10 @@ struct DLPackConvert { ...@@ -38,10 +38,10 @@ struct DLPackConvert {
*/ */
static void DLPackDeleter(NDArray::Container* ptr); static void DLPackDeleter(NDArray::Container* ptr);
/*! \brief Convert a DGL NDArray to a DLPack tensor. /*! @brief Convert a DGL NDArray to a DLPack tensor.
* *
* \param from The DGL NDArray. * @param from The DGL NDArray.
* \return A DLPack tensor. * @return A DLPack tensor.
*/ */
static DLManagedTensor* ToDLPack(const NDArray& from); static DLManagedTensor* ToDLPack(const NDArray& from);
}; };
...@@ -54,26 +54,26 @@ extern "C" { ...@@ -54,26 +54,26 @@ extern "C" {
#endif #endif
/*! /*!
* \brief Delete (free) a DLManagedTensor's data. * @brief Delete (free) a DLManagedTensor's data.
* \param dltensor Pointer to the DLManagedTensor. * @param dltensor Pointer to the DLManagedTensor.
*/ */
DGL_DLL void DGLDLManagedTensorCallDeleter(DLManagedTensor* dltensor); DGL_DLL void DGLDLManagedTensorCallDeleter(DLManagedTensor* dltensor);
/*! /*!
* \brief Produce an array from the DLManagedTensor that shares data memory * @brief Produce an array from the DLManagedTensor that shares data memory
* with the DLManagedTensor. * with the DLManagedTensor.
* \param from The source DLManagedTensor. * @param from The source DLManagedTensor.
* \param out The output array handle. * @param out The output array handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayFromDLPack(DLManagedTensor* from, DGLArrayHandle* out); DGL_DLL int DGLArrayFromDLPack(DLManagedTensor* from, DGLArrayHandle* out);
/*! /*!
* \brief Produce a DLMangedTensor from the array that shares data memory with * @brief Produce a DLMangedTensor from the array that shares data memory with
* the array. * the array.
* \param from The source array. * @param from The source array.
* \param out The DLManagedTensor handle. * @param out The DLManagedTensor handle.
* \return 0 when success, -1 when failure happens * @return 0 when success, -1 when failure happens
*/ */
DGL_DLL int DGLArrayToDLPack( DGL_DLL int DGLArrayToDLPack(
DGLArrayHandle from, DLManagedTensor** out, int alignment = 0); DGLArrayHandle from, DLManagedTensor** out, int alignment = 0);
......
include/dgl/runtime/module.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2017 by Contributors * Copyright (c) 2017 by Contributors
* \file dgl/runtime/module.h * @file dgl/runtime/module.h
* \brief Runtime container of the functions generated by DGL, * @brief Runtime container of the functions generated by DGL,
* This is used to support dynamically link, load and save * This is used to support dynamically link, load and save
* functions from different convention under unified API. * functions from different convention under unified API.
*/ */
...@@ -25,7 +25,7 @@ class ModuleNode; ...@@ -25,7 +25,7 @@ class ModuleNode;
class PackedFunc; class PackedFunc;
/*! /*!
* \brief Module container of DGL. * @brief Module container of DGL.
*/ */
class Module { class Module {
public: public:
...@@ -33,13 +33,13 @@ class Module { ...@@ -33,13 +33,13 @@ class Module {
// constructor from container. // constructor from container.
explicit Module(std::shared_ptr<ModuleNode> n) : node_(n) {} explicit Module(std::shared_ptr<ModuleNode> n) : node_(n) {}
/*! /*!
* \brief Get packed function from current module by name. * @brief Get packed function from current module by name.
* *
* \param name The name of the function. * @param name The name of the function.
* \param query_imports Whether also query dependency modules. * @param query_imports Whether also query dependency modules.
* \return The result function. * @return The result function.
* This function will return PackedFunc(nullptr) if function do not exist. * This function will return PackedFunc(nullptr) if function do not exist.
* \note Implemented in packed_func.cc * @note Implemented in packed_func.cc
*/ */
inline PackedFunc GetFunction( inline PackedFunc GetFunction(
const std::string& name, bool query_imports = false); const std::string& name, bool query_imports = false);
...@@ -49,18 +49,18 @@ class Module { ...@@ -49,18 +49,18 @@ class Module {
inline const ModuleNode* operator->() const; inline const ModuleNode* operator->() const;
// The following functions requires link with runtime. // The following functions requires link with runtime.
/*! /*!
* \brief Import another module into this module. * @brief Import another module into this module.
* \param other The module to be imported. * @param other The module to be imported.
* *
* \note Cyclic dependency is not allowed among modules, * @note Cyclic dependency is not allowed among modules,
* An error will be thrown when cyclic dependency is detected. * An error will be thrown when cyclic dependency is detected.
*/ */
DGL_DLL void Import(Module other); DGL_DLL void Import(Module other);
/*! /*!
* \brief Load a module from file. * @brief Load a module from file.
* \param file_name The name of the host function module. * @param file_name The name of the host function module.
* \param format The format of the file. * @param format The format of the file.
* \note This function won't load the import relationship. * @note This function won't load the import relationship.
* Re-create import relationship by calling Import. * Re-create import relationship by calling Import.
*/ */
DGL_DLL static Module LoadFromFile( DGL_DLL static Module LoadFromFile(
...@@ -71,29 +71,29 @@ class Module { ...@@ -71,29 +71,29 @@ class Module {
}; };
/*! /*!
* \brief Base node container of module. * @brief Base node container of module.
* Do not create this directly, instead use Module. * Do not create this directly, instead use Module.
*/ */
class ModuleNode { class ModuleNode {
public: public:
/*! \brief virtual destructor */ /*! @brief virtual destructor */
virtual ~ModuleNode() {} virtual ~ModuleNode() {}
/*! \return The module type key */ /*! \return The module type key */
virtual const char* type_key() const = 0; virtual const char* type_key() const = 0;
/*! /*!
* \brief Get a PackedFunc from module. * @brief Get a PackedFunc from module.
* *
* The PackedFunc may not be fully initialized, * The PackedFunc may not be fully initialized,
* there might still be first time running overhead when * there might still be first time running overhead when
* executing the function on certain devices. * executing the function on certain devices.
* For benchmarking, use prepare to eliminate * For benchmarking, use prepare to eliminate
* *
* \param name the name of the function. * @param name the name of the function.
* \param sptr_to_self The shared_ptr that points to this module node. * @param sptr_to_self The shared_ptr that points to this module node.
* *
* \return PackedFunc(nullptr) when it is not available. * @return PackedFunc(nullptr) when it is not available.
* *
* \note The function will always remain valid. * @note The function will always remain valid.
* If the function need resource from the module(e.g. late linking), * If the function need resource from the module(e.g. late linking),
* it should capture sptr_to_self. * it should capture sptr_to_self.
*/ */
...@@ -101,32 +101,32 @@ class ModuleNode { ...@@ -101,32 +101,32 @@ class ModuleNode {
const std::string& name, const std::string& name,
const std::shared_ptr<ModuleNode>& sptr_to_self) = 0; const std::shared_ptr<ModuleNode>& sptr_to_self) = 0;
/*! /*!
* \brief Save the module to file. * @brief Save the module to file.
* \param file_name The file to be saved to. * @param file_name The file to be saved to.
* \param format The format of the file. * @param format The format of the file.
*/ */
virtual void SaveToFile( virtual void SaveToFile(
const std::string& file_name, const std::string& format); const std::string& file_name, const std::string& format);
/*! /*!
* \brief Save the module to binary stream. * @brief Save the module to binary stream.
* \param stream The binary stream to save to. * @param stream The binary stream to save to.
* \note It is recommended to implement this for device modules, * @note It is recommended to implement this for device modules,
* but not necessarily host modules. * but not necessarily host modules.
* We can use this to do AOT loading of bundled device functions. * We can use this to do AOT loading of bundled device functions.
*/ */
DGL_DLL virtual void SaveToBinary(dmlc::Stream* stream); DGL_DLL virtual void SaveToBinary(dmlc::Stream* stream);
/*! /*!
* \brief Get the source code of module, when available. * @brief Get the source code of module, when available.
* \param format Format of the source code, can be empty by default. * @param format Format of the source code, can be empty by default.
* \return Possible source code when available. * @return Possible source code when available.
*/ */
DGL_DLL virtual std::string GetSource(const std::string& format = ""); DGL_DLL virtual std::string GetSource(const std::string& format = "");
/*! /*!
* \brief Get a function from current environment * @brief Get a function from current environment
* The environment includes all the imports as well as Global functions. * The environment includes all the imports as well as Global functions.
* *
* \param name name of the function. * @param name name of the function.
* \return The corresponding function. * @return The corresponding function.
*/ */
DGL_DLL const PackedFunc* GetFuncFromEnv(const std::string& name); DGL_DLL const PackedFunc* GetFuncFromEnv(const std::string& name);
/*! \return The module it imports from */ /*! \return The module it imports from */
...@@ -134,32 +134,32 @@ class ModuleNode { ...@@ -134,32 +134,32 @@ class ModuleNode {
protected: protected:
friend class Module; friend class Module;
/*! \brief The modules this module depend on */ /*! @brief The modules this module depend on */
std::vector<Module> imports_; std::vector<Module> imports_;
private: private:
/*! \brief Cache used by GetImport */ /*! @brief Cache used by GetImport */
std::unordered_map<std::string, std::unique_ptr<PackedFunc> > import_cache_; std::unordered_map<std::string, std::unique_ptr<PackedFunc> > import_cache_;
}; };
/*! \brief namespace for constant symbols */ /*! @brief namespace for constant symbols */
namespace symbol { namespace symbol {
/*! \brief Global variable to store module context. */ /*! @brief Global variable to store module context. */
constexpr const char* dgl_module_ctx = "__dgl_module_ctx"; constexpr const char* dgl_module_ctx = "__dgl_module_ctx";
/*! \brief Global variable to store device module blob */ /*! @brief Global variable to store device module blob */
constexpr const char* dgl_dev_mblob = "__dgl_dev_mblob"; constexpr const char* dgl_dev_mblob = "__dgl_dev_mblob";
/*! \brief Number of bytes of device module blob. */ /*! @brief Number of bytes of device module blob. */
constexpr const char* dgl_dev_mblob_nbytes = "__dgl_dev_mblob_nbytes"; constexpr const char* dgl_dev_mblob_nbytes = "__dgl_dev_mblob_nbytes";
/*! \brief global function to set device */ /*! @brief global function to set device */
constexpr const char* dgl_set_device = "__dgl_set_device"; constexpr const char* dgl_set_device = "__dgl_set_device";
/*! \brief Auxiliary counter to global barrier. */ /*! @brief Auxiliary counter to global barrier. */
constexpr const char* dgl_global_barrier_state = "__dgl_global_barrier_state"; constexpr const char* dgl_global_barrier_state = "__dgl_global_barrier_state";
/*! /*!
* \brief Prepare the global barrier before kernels that uses global barrier. * @brief Prepare the global barrier before kernels that uses global barrier.
*/ */
constexpr const char* dgl_prepare_global_barrier = constexpr const char* dgl_prepare_global_barrier =
"__dgl_prepare_global_barrier"; "__dgl_prepare_global_barrier";
/*! \brief Placeholder for the module's entry function. */ /*! @brief Placeholder for the module's entry function. */
constexpr const char* dgl_module_main = "__dgl_main__"; constexpr const char* dgl_module_main = "__dgl_main__";
} // namespace symbol } // namespace symbol
......
include/dgl/runtime/object.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2019 by Contributors * Copyright (c) 2019 by Contributors
* \file runtime/object.h * @file runtime/object.h
* \brief Defines the Object data structures. * @brief Defines the Object data structures.
*/ */
#ifndef DGL_RUNTIME_OBJECT_H_ #ifndef DGL_RUNTIME_OBJECT_H_
#define DGL_RUNTIME_OBJECT_H_ #define DGL_RUNTIME_OBJECT_H_
...@@ -22,7 +22,7 @@ class ObjectRef; ...@@ -22,7 +22,7 @@ class ObjectRef;
class NDArray; class NDArray;
/*! /*!
* \brief Visitor class to each object attribute. * @brief Visitor class to each object attribute.
* The content is going to be called for each field. * The content is going to be called for each field.
*/ */
class AttrVisitor { class AttrVisitor {
...@@ -49,52 +49,52 @@ class AttrVisitor { ...@@ -49,52 +49,52 @@ class AttrVisitor {
}; };
/*! /*!
* \brief base class of object container. * @brief base class of object container.
* All object's internal is stored as std::shared_ptr<Object> * All object's internal is stored as std::shared_ptr<Object>
*/ */
class Object { class Object {
public: public:
/*! \brief virtual destructor */ /*! @brief virtual destructor */
virtual ~Object() {} virtual ~Object() {}
/*! \return The unique type key of the object */ /*! \return The unique type key of the object */
virtual const char* type_key() const = 0; virtual const char* type_key() const = 0;
/*! /*!
* \brief Apply visitor to each field of the Object * @brief Apply visitor to each field of the Object
* Visitor could mutate the content of the object. * Visitor could mutate the content of the object.
* override if Object contains attribute fields. * override if Object contains attribute fields.
* \param visitor The visitor * @param visitor The visitor
*/ */
virtual void VisitAttrs(AttrVisitor* visitor) {} virtual void VisitAttrs(AttrVisitor* visitor) {}
/*! \return the type index of the object */ /*! \return the type index of the object */
virtual uint32_t type_index() const = 0; virtual uint32_t type_index() const = 0;
/*! /*!
* \brief Whether this object derives from object with type_index=tid. * @brief Whether this object derives from object with type_index=tid.
* Implemented by DGL_DECLARE_OBJECT_TYPE_INFO * Implemented by DGL_DECLARE_OBJECT_TYPE_INFO
* *
* \param tid The type index. * @param tid The type index.
* \return the check result. * @return the check result.
*/ */
virtual bool _DerivedFrom(uint32_t tid) const; virtual bool _DerivedFrom(uint32_t tid) const;
/*! /*!
* \brief get a runtime unique type index given a type key * @brief get a runtime unique type index given a type key
* \param type_key Type key of a type. * @param type_key Type key of a type.
* \return the corresponding type index. * @return the corresponding type index.
*/ */
static uint32_t TypeKey2Index(const char* type_key); static uint32_t TypeKey2Index(const char* type_key);
/*! /*!
* \brief get type key from type index. * @brief get type key from type index.
* \param index The type index * @param index The type index
* \return the corresponding type key. * @return the corresponding type key.
*/ */
static const char* TypeIndex2Key(uint32_t index); static const char* TypeIndex2Key(uint32_t index);
/*! /*!
* \return whether the type is derived from * @return whether the type is derived from
*/ */
template <typename T> template <typename T>
inline bool derived_from() const; inline bool derived_from() const;
/*! /*!
* \return whether the object is of type T * @return whether the object is of type T
* \tparam The type to be checked. * @tparam The type to be checked.
*/ */
template <typename T> template <typename T>
inline bool is_type() const; inline bool is_type() const;
...@@ -103,45 +103,45 @@ class Object { ...@@ -103,45 +103,45 @@ class Object {
static constexpr const char* _type_key = "Object"; static constexpr const char* _type_key = "Object";
}; };
/*! \brief base class of all reference object */ /*! @brief base class of all reference object */
class ObjectRef { class ObjectRef {
public: public:
/*! \brief type indicate the container type */ /*! @brief type indicate the container type */
using ContainerType = Object; using ContainerType = Object;
/*! /*!
* \brief Comparator * @brief Comparator
* *
* Compare with the two are referencing to the same object (compare by * Compare with the two are referencing to the same object (compare by
* address). * address).
* *
* \param other Another object ref. * @param other Another object ref.
* \return the compare result. * @return the compare result.
* \sa same_as * \sa same_as
*/ */
inline bool operator==(const ObjectRef& other) const; inline bool operator==(const ObjectRef& other) const;
/*! /*!
* \brief Comparator * @brief Comparator
* *
* Compare with the two are referencing to the same object (compare by * Compare with the two are referencing to the same object (compare by
* address). * address).
* *
* \param other Another object ref. * @param other Another object ref.
* \return the compare result. * @return the compare result.
*/ */
inline bool same_as(const ObjectRef& other) const; inline bool same_as(const ObjectRef& other) const;
/*! /*!
* \brief Comparator * @brief Comparator
* *
* The operator overload allows ObjectRef be used in std::map. * The operator overload allows ObjectRef be used in std::map.
* *
* \param other Another object ref. * @param other Another object ref.
* \return the compare result. * @return the compare result.
*/ */
inline bool operator<(const ObjectRef& other) const; inline bool operator<(const ObjectRef& other) const;
/*! /*!
* \brief Comparator * @brief Comparator
* \param other Another object ref. * @param other Another object ref.
* \return the compare result. * @return the compare result.
* \sa same_as * \sa same_as
*/ */
inline bool operator!=(const ObjectRef& other) const; inline bool operator!=(const ObjectRef& other) const;
...@@ -156,28 +156,28 @@ class ObjectRef { ...@@ -156,28 +156,28 @@ class ObjectRef {
/*! \return the internal object pointer */ /*! \return the internal object pointer */
inline const Object* operator->() const; inline const Object* operator->() const;
/*! /*!
* \brief Downcast this object to its actual type. * @brief Downcast this object to its actual type.
* This returns nullptr if the object is not of the requested type. * This returns nullptr if the object is not of the requested type.
* Example usage: * Example usage:
* *
* if (const Banana *banana = obj->as<Banana>()) { * if (const Banana *banana = obj->as<Banana>()) {
* // This is a Banana! * // This is a Banana!
* } * }
* \tparam T the target type, must be subtype of Object * @tparam T the target type, must be subtype of Object
*/ */
template <typename T> template <typename T>
inline const T* as() const; inline const T* as() const;
/*! \brief default constructor */ /*! @brief default constructor */
ObjectRef() = default; ObjectRef() = default;
explicit ObjectRef(std::shared_ptr<Object> obj) : obj_(obj) {} explicit ObjectRef(std::shared_ptr<Object> obj) : obj_(obj) {}
/*! \brief the internal object, do not touch */ /*! @brief the internal object, do not touch */
std::shared_ptr<Object> obj_; std::shared_ptr<Object> obj_;
}; };
/*! /*!
* \brief helper macro to declare type information in a base object. * @brief helper macro to declare type information in a base object.
* *
* This is macro should be used in abstract base class definition * This is macro should be used in abstract base class definition
* because it does not define type_key and type_index. * because it does not define type_key and type_index.
...@@ -190,7 +190,7 @@ class ObjectRef { ...@@ -190,7 +190,7 @@ class ObjectRef {
} }
/*! /*!
* \brief helper macro to declare type information in a terminal class * @brief helper macro to declare type information in a terminal class
* *
* This is macro should be used in terminal class definition. * This is macro should be used in terminal class definition.
* *
...@@ -222,7 +222,7 @@ class ObjectRef { ...@@ -222,7 +222,7 @@ class ObjectRef {
return Parent::_DerivedFrom(tid); \ return Parent::_DerivedFrom(tid); \
} }
/*! \brief Macro to generate common object reference class method definition */ /*! @brief Macro to generate common object reference class method definition */
#define DGL_DEFINE_OBJECT_REF_METHODS(TypeName, BaseTypeName, ObjectName) \ #define DGL_DEFINE_OBJECT_REF_METHODS(TypeName, BaseTypeName, ObjectName) \
TypeName() {} \ TypeName() {} \
explicit TypeName(std::shared_ptr<runtime::Object> obj) \ explicit TypeName(std::shared_ptr<runtime::Object> obj) \
...@@ -237,7 +237,7 @@ class ObjectRef { ...@@ -237,7 +237,7 @@ class ObjectRef {
operator bool() const { return this->defined(); } \ operator bool() const { return this->defined(); } \
using ContainerType = ObjectName using ContainerType = ObjectName
/*! \brief Macro to generate object reference class definition */ /*! @brief Macro to generate object reference class definition */
#define DGL_DEFINE_OBJECT_REF(TypeName, ObjectName) \ #define DGL_DEFINE_OBJECT_REF(TypeName, ObjectName) \
class TypeName : public ::dgl::runtime::ObjectRef { \ class TypeName : public ::dgl::runtime::ObjectRef { \
public: \ public: \
...@@ -300,12 +300,12 @@ inline const T* ObjectRef::as() const { ...@@ -300,12 +300,12 @@ inline const T* ObjectRef::as() const {
return nullptr; return nullptr;
} }
/*! \brief The hash function for nodes */ /*! @brief The hash function for nodes */
struct ObjectHash { struct ObjectHash {
size_t operator()(const ObjectRef& a) const { return a.hash(); } size_t operator()(const ObjectRef& a) const { return a.hash(); }
}; };
/*! \brief The equal comparator for nodes */ /*! @brief The equal comparator for nodes */
struct ObjectEqual { struct ObjectEqual {
bool operator()(const ObjectRef& a, const ObjectRef& b) const { bool operator()(const ObjectRef& a, const ObjectRef& b) const {
return a.get() == b.get(); return a.get() == b.get();
......
include/dgl/runtime/packed_func.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2017 by Contributors * Copyright (c) 2017 by Contributors
* \file dgl/runtime/packed_func.h * @file dgl/runtime/packed_func.h
* \brief Type-erased function used across DGL API. * @brief Type-erased function used across DGL API.
*/ */
#ifndef DGL_RUNTIME_PACKED_FUNC_H_ #ifndef DGL_RUNTIME_PACKED_FUNC_H_
#define DGL_RUNTIME_PACKED_FUNC_H_ #define DGL_RUNTIME_PACKED_FUNC_H_
...@@ -42,7 +42,7 @@ class DGLRetValue; ...@@ -42,7 +42,7 @@ class DGLRetValue;
class DGLArgsSetter; class DGLArgsSetter;
/*! /*!
* \brief Packed function is a type-erased function. * @brief Packed function is a type-erased function.
* The arguments are passed by packed format. * The arguments are passed by packed format.
* *
* This is an useful unified interface to call generated functions, * This is an useful unified interface to call generated functions,
...@@ -52,9 +52,9 @@ class DGLArgsSetter; ...@@ -52,9 +52,9 @@ class DGLArgsSetter;
class PackedFunc { class PackedFunc {
public: public:
/*! /*!
* \brief The internal std::function * @brief The internal std::function
* \param args The arguments to the function. * @param args The arguments to the function.
* \param rv The return value. * @param rv The return value.
* *
* \code * \code
* // Example code on how to implemented FType * // Example code on how to implemented FType
...@@ -70,17 +70,17 @@ class PackedFunc { ...@@ -70,17 +70,17 @@ class PackedFunc {
* \endcode * \endcode
*/ */
using FType = std::function<void(DGLArgs args, DGLRetValue* rv)>; using FType = std::function<void(DGLArgs args, DGLRetValue* rv)>;
/*! \brief default constructor */ /*! @brief default constructor */
PackedFunc() {} PackedFunc() {}
/*! /*!
* \brief constructing a packed function from a std::function. * @brief constructing a packed function from a std::function.
* \param body the internal container of packed function. * @param body the internal container of packed function.
*/ */
explicit PackedFunc(FType body) : body_(body) {} explicit PackedFunc(FType body) : body_(body) {}
/*! /*!
* \brief Call packed function by directly passing in unpacked format. * @brief Call packed function by directly passing in unpacked format.
* \param args Arguments to be passed. * @param args Arguments to be passed.
* \tparam Args arguments to be passed. * @tparam Args arguments to be passed.
* *
* \code * \code
* // Example code on how to call packed function * // Example code on how to call packed function
...@@ -94,9 +94,9 @@ class PackedFunc { ...@@ -94,9 +94,9 @@ class PackedFunc {
template <typename... Args> template <typename... Args>
inline DGLRetValue operator()(Args&&... args) const; inline DGLRetValue operator()(Args&&... args) const;
/*! /*!
* \brief Call the function in packed format. * @brief Call the function in packed format.
* \param args The arguments * @param args The arguments
* \param rv The return value. * @param rv The return value.
*/ */
inline void CallPacked(DGLArgs args, DGLRetValue* rv) const; inline void CallPacked(DGLArgs args, DGLRetValue* rv) const;
/*! \return the internal body function */ /*! \return the internal body function */
...@@ -107,12 +107,12 @@ class PackedFunc { ...@@ -107,12 +107,12 @@ class PackedFunc {
bool operator!=(std::nullptr_t null) const { return body_ != nullptr; } bool operator!=(std::nullptr_t null) const { return body_ != nullptr; }
private: private:
/*! \brief internal container of packed function */ /*! @brief internal container of packed function */
FType body_; FType body_;
}; };
/*! /*!
* \brief Please refer to \ref TypedPackedFuncAnchor * @brief Please refer to \ref TypedPackedFuncAnchor
* "TypedPackedFunc<R(Args..)>" * "TypedPackedFunc<R(Args..)>"
*/ */
template <typename FType> template <typename FType>
...@@ -120,7 +120,7 @@ class TypedPackedFunc; ...@@ -120,7 +120,7 @@ class TypedPackedFunc;
/*! /*!
* \anchor TypedPackedFuncAnchor * \anchor TypedPackedFuncAnchor
* \brief A PackedFunc wrapper to provide typed function signature. * @brief A PackedFunc wrapper to provide typed function signature.
* It is backed by a PackedFunc internally. * It is backed by a PackedFunc internally.
* *
* TypedPackedFunc enables compile time type checking. * TypedPackedFunc enables compile time type checking.
...@@ -147,18 +147,18 @@ class TypedPackedFunc; ...@@ -147,18 +147,18 @@ class TypedPackedFunc;
* // Can be directly converted to PackedFunc * // Can be directly converted to PackedFunc
* PackedFunc packed = ftype; * PackedFunc packed = ftype;
* \endcode * \endcode
* \tparam R The return value of the function. * @tparam R The return value of the function.
* \tparam Args The argument signature of the function. * @tparam Args The argument signature of the function.
*/ */
template <typename R, typename... Args> template <typename R, typename... Args>
class TypedPackedFunc<R(Args...)> { class TypedPackedFunc<R(Args...)> {
public: public:
/*! \brief short hand for this function type */ /*! @brief short hand for this function type */
using TSelf = TypedPackedFunc<R(Args...)>; using TSelf = TypedPackedFunc<R(Args...)>;
/*! \brief default constructor */ /*! @brief default constructor */
TypedPackedFunc() {} TypedPackedFunc() {}
/*! /*!
* \brief construct by wrap a PackedFunc * @brief construct by wrap a PackedFunc
* *
* Example usage: * Example usage:
* \code * \code
...@@ -172,11 +172,11 @@ class TypedPackedFunc<R(Args...)> { ...@@ -172,11 +172,11 @@ class TypedPackedFunc<R(Args...)> {
* CHECK_EQ(ftyped(1), 2); * CHECK_EQ(ftyped(1), 2);
* \endcode * \endcode
* *
* \param packed The packed function * @param packed The packed function
*/ */
inline explicit TypedPackedFunc(PackedFunc packed); inline explicit TypedPackedFunc(PackedFunc packed);
/*! /*!
* \brief construct from a lambda function with the same signature. * @brief construct from a lambda function with the same signature.
* *
* Example usage: * Example usage:
* \code * \code
...@@ -187,8 +187,8 @@ class TypedPackedFunc<R(Args...)> { ...@@ -187,8 +187,8 @@ class TypedPackedFunc<R(Args...)> {
* CHECK_EQ(ftyped(1), 2); * CHECK_EQ(ftyped(1), 2);
* \endcode * \endcode
* *
* \param typed_lambda typed lambda function. * @param typed_lambda typed lambda function.
* \tparam FLambda the type of the lambda function. * @tparam FLambda the type of the lambda function.
*/ */
template < template <
typename FLambda, typename = typename std::enable_if<std::is_convertible< typename FLambda, typename = typename std::enable_if<std::is_convertible<
...@@ -197,7 +197,7 @@ class TypedPackedFunc<R(Args...)> { ...@@ -197,7 +197,7 @@ class TypedPackedFunc<R(Args...)> {
this->AssignTypedLambda(typed_lambda); this->AssignTypedLambda(typed_lambda);
} }
/*! /*!
* \brief copy assignment operator from typed lambda * @brief copy assignment operator from typed lambda
* *
* Example usage: * Example usage:
* \code * \code
...@@ -208,9 +208,9 @@ class TypedPackedFunc<R(Args...)> { ...@@ -208,9 +208,9 @@ class TypedPackedFunc<R(Args...)> {
* CHECK_EQ(ftyped(1), 2); * CHECK_EQ(ftyped(1), 2);
* \endcode * \endcode
* *
* \param typed_lambda typed lambda function. * @param typed_lambda typed lambda function.
* \tparam FLambda the type of the lambda function. * @tparam FLambda the type of the lambda function.
* \returns reference to self. * @returns reference to self.
*/ */
template < template <
typename FLambda, typename = typename std::enable_if<std::is_convertible< typename FLambda, typename = typename std::enable_if<std::is_convertible<
...@@ -221,71 +221,71 @@ class TypedPackedFunc<R(Args...)> { ...@@ -221,71 +221,71 @@ class TypedPackedFunc<R(Args...)> {
return *this; return *this;
} }
/*! /*!
* \brief copy assignment operator from PackedFunc. * @brief copy assignment operator from PackedFunc.
* \param packed The packed function. * @param packed The packed function.
* \returns reference to self. * @returns reference to self.
*/ */
TSelf& operator=(PackedFunc packed) { TSelf& operator=(PackedFunc packed) {
packed_ = packed; packed_ = packed;
return *this; return *this;
} }
/*! /*!
* \brief Invoke the operator. * @brief Invoke the operator.
* \param args The arguments * @param args The arguments
* \returns The return value. * @returns The return value.
*/ */
inline R operator()(Args... args) const; inline R operator()(Args... args) const;
/*! /*!
* \brief convert to PackedFunc * @brief convert to PackedFunc
* \return the internal PackedFunc * @return the internal PackedFunc
*/ */
operator PackedFunc() const { return packed(); } operator PackedFunc() const { return packed(); }
/*! /*!
* \return reference the internal PackedFunc * @return reference the internal PackedFunc
*/ */
const PackedFunc& packed() const { return packed_; } const PackedFunc& packed() const { return packed_; }
private: private:
friend class DGLRetValue; friend class DGLRetValue;
/*! \brief The internal packed function */ /*! @brief The internal packed function */
PackedFunc packed_; PackedFunc packed_;
/*! /*!
* \brief Assign the packed field using a typed lambda function. * @brief Assign the packed field using a typed lambda function.
* *
* \param flambda The lambda function. * @param flambda The lambda function.
* \tparam FLambda The lambda function type. * @tparam FLambda The lambda function type.
* \note We capture the lambda when possible for maximum efficiency. * @note We capture the lambda when possible for maximum efficiency.
*/ */
template <typename FLambda> template <typename FLambda>
inline void AssignTypedLambda(FLambda flambda); inline void AssignTypedLambda(FLambda flambda);
}; };
/*! \brief Arguments into DGL functions. */ /*! @brief Arguments into DGL functions. */
class DGLArgs { class DGLArgs {
public: public:
const DGLValue* values; const DGLValue* values;
const int* type_codes; const int* type_codes;
int num_args; int num_args;
/*! /*!
* \brief constructor * @brief constructor
* \param values The argument values * @param values The argument values
* \param type_codes The argument type codes * @param type_codes The argument type codes
* \param num_args number of arguments. * @param num_args number of arguments.
*/ */
DGLArgs(const DGLValue* values, const int* type_codes, int num_args) DGLArgs(const DGLValue* values, const int* type_codes, int num_args)
: values(values), type_codes(type_codes), num_args(num_args) {} : values(values), type_codes(type_codes), num_args(num_args) {}
/*! \return size of the arguments */ /*! \return size of the arguments */
inline int size() const; inline int size() const;
/*! /*!
* \brief Get i-th argument * @brief Get i-th argument
* \param i the index. * @param i the index.
* \return the ith argument. * @return the ith argument.
*/ */
inline DGLArgValue operator[](int i) const; inline DGLArgValue operator[](int i) const;
}; };
/*! /*!
* \brief Type traits to mark if a class is dgl extension type. * @brief Type traits to mark if a class is dgl extension type.
* *
* To enable extension type in C++ must be register () ed via marco. * To enable extension type in C++ must be register () ed via marco.
* DGL_REGISTER_EXT_TYPE(TypeName) after defining this with this traits. * DGL_REGISTER_EXT_TYPE(TypeName) after defining this with this traits.
...@@ -293,7 +293,7 @@ class DGLArgs { ...@@ -293,7 +293,7 @@ class DGLArgs {
* Extension class can be passed and returned via PackedFunc in all dgl runtime. * Extension class can be passed and returned via PackedFunc in all dgl runtime.
* Internally extension class is stored as T*. * Internally extension class is stored as T*.
* *
* \tparam T the typename * @tparam T the typename
*/ */
template <typename T> template <typename T>
struct extension_class_info { struct extension_class_info {
...@@ -301,25 +301,25 @@ struct extension_class_info { ...@@ -301,25 +301,25 @@ struct extension_class_info {
}; };
/*! /*!
* \brief Runtime function table about extension type. * @brief Runtime function table about extension type.
*/ */
class ExtTypeVTable { class ExtTypeVTable {
public: public:
/*! \brief function to be called to delete a handle */ /*! @brief function to be called to delete a handle */
void (*destroy)(void* handle); void (*destroy)(void* handle);
/*! \brief function to be called when clone a handle */ /*! @brief function to be called when clone a handle */
void* (*clone)(void* handle); void* (*clone)(void* handle);
/*! /*!
* \brief Register type * @brief Register type
* \tparam T The type to be register. * @tparam T The type to be register.
* \return The registered vtable. * @return The registered vtable.
*/ */
template <typename T> template <typename T>
static inline ExtTypeVTable* Register_(); static inline ExtTypeVTable* Register_();
/*! /*!
* \brief Get a vtable based on type code. * @brief Get a vtable based on type code.
* \param type_code The type code * @param type_code The type code
* \return The registered vtable. * @return The registered vtable.
*/ */
DGL_DLL static ExtTypeVTable* Get(int type_code); DGL_DLL static ExtTypeVTable* Get(int type_code);
...@@ -330,7 +330,7 @@ class ExtTypeVTable { ...@@ -330,7 +330,7 @@ class ExtTypeVTable {
}; };
/*! /*!
* \brief Internal base class to * @brief Internal base class to
* handle conversion to POD values. * handle conversion to POD values.
*/ */
class DGLPODValue_ { class DGLPODValue_ {
...@@ -394,9 +394,9 @@ class DGLPODValue_ { ...@@ -394,9 +394,9 @@ class DGLPODValue_ {
} }
int type_code() const { return type_code_; } int type_code() const { return type_code_; }
/*! /*!
* \brief return handle as specific pointer type. * @brief return handle as specific pointer type.
* \tparam T the data type. * @tparam T the data type.
* \return The pointer type. * @return The pointer type.
*/ */
template <typename T> template <typename T>
T* ptr() const { T* ptr() const {
...@@ -410,26 +410,26 @@ class DGLPODValue_ { ...@@ -410,26 +410,26 @@ class DGLPODValue_ {
DGLPODValue_(DGLValue value, int type_code) DGLPODValue_(DGLValue value, int type_code)
: value_(value), type_code_(type_code) {} : value_(value), type_code_(type_code) {}
/*! \brief The value */ /*! @brief The value */
DGLValue value_; DGLValue value_;
/*! \brief the type code */ /*! @brief the type code */
int type_code_; int type_code_;
}; };
/*! /*!
* \brief A single argument value to PackedFunc. * @brief A single argument value to PackedFunc.
* Containing both type_code and DGLValue * Containing both type_code and DGLValue
* *
* Provides utilities to do type cast into other types. * Provides utilities to do type cast into other types.
*/ */
class DGLArgValue : public DGLPODValue_ { class DGLArgValue : public DGLPODValue_ {
public: public:
/*! \brief default constructor */ /*! @brief default constructor */
DGLArgValue() {} DGLArgValue() {}
/*! /*!
* \brief constructor * @brief constructor
* \param value of the function * @param value of the function
* \param type_code The type code. * @param type_code The type code.
*/ */
DGLArgValue(DGLValue value, int type_code) : DGLPODValue_(value, type_code) {} DGLArgValue(DGLValue value, int type_code) : DGLPODValue_(value, type_code) {}
// reuse converter from parent // reuse converter from parent
...@@ -498,7 +498,7 @@ class DGLArgValue : public DGLPODValue_ { ...@@ -498,7 +498,7 @@ class DGLArgValue : public DGLPODValue_ {
}; };
/*! /*!
* \brief Return Value container, * @brief Return Value container,
* Unlike DGLArgValue, which only holds reference and do not delete * Unlike DGLArgValue, which only holds reference and do not delete
* the underlying container during destruction. * the underlying container during destruction.
* *
...@@ -507,18 +507,18 @@ class DGLArgValue : public DGLPODValue_ { ...@@ -507,18 +507,18 @@ class DGLArgValue : public DGLPODValue_ {
*/ */
class DGLRetValue : public DGLPODValue_ { class DGLRetValue : public DGLPODValue_ {
public: public:
/*! \brief default constructor */ /*! @brief default constructor */
DGLRetValue() {} DGLRetValue() {}
/*! /*!
* \brief move constructor from anoter return value. * @brief move constructor from anoter return value.
* \param other The other return value. * @param other The other return value.
*/ */
DGLRetValue(DGLRetValue&& other) DGLRetValue(DGLRetValue&& other)
: DGLPODValue_(other.value_, other.type_code_) { : DGLPODValue_(other.value_, other.type_code_) {
other.value_.v_handle = nullptr; other.value_.v_handle = nullptr;
other.type_code_ = kNull; other.type_code_ = kNull;
} }
/*! \brief destructor */ /*! @brief destructor */
~DGLRetValue() { this->Clear(); } ~DGLRetValue() { this->Clear(); }
// reuse converter from parent // reuse converter from parent
using DGLPODValue_::operator double; using DGLPODValue_::operator double;
...@@ -653,13 +653,13 @@ class DGLRetValue : public DGLPODValue_ { ...@@ -653,13 +653,13 @@ class DGLRetValue : public DGLPODValue_ {
return *this; return *this;
} }
/*! /*!
* \brief Move the value back to front-end via C API. * @brief Move the value back to front-end via C API.
* This marks the current container as null. * This marks the current container as null.
* The managed resources is moved to front-end and * The managed resources is moved to front-end and
* the front end should take charge in managing them. * the front end should take charge in managing them.
* *
* \param ret_value The return value. * @param ret_value The return value.
* \param ret_type_code The return type code. * @param ret_type_code The return type code.
*/ */
void MoveToCHost(DGLValue* ret_value, int* ret_type_code) { void MoveToCHost(DGLValue* ret_value, int* ret_type_code) {
// cannot move str; need specially handle. // cannot move str; need specially handle.
...@@ -823,7 +823,7 @@ inline void for_each(const F& f, Args&&... args) { // NOLINT(*) ...@@ -823,7 +823,7 @@ inline void for_each(const F& f, Args&&... args) { // NOLINT(*)
} }
} // namespace detail } // namespace detail
/* \brief argument settter to PackedFunc */ /* @brief argument settter to PackedFunc */
class DGLArgsSetter { class DGLArgsSetter {
public: public:
DGLArgsSetter(DGLValue* values, int* type_codes) DGLArgsSetter(DGLValue* values, int* type_codes)
...@@ -920,9 +920,9 @@ class DGLArgsSetter { ...@@ -920,9 +920,9 @@ class DGLArgsSetter {
inline void operator()(size_t i, const ObjectRef& other) const; // NOLINT(*) inline void operator()(size_t i, const ObjectRef& other) const; // NOLINT(*)
private: private:
/*! \brief The values fields */ /*! @brief The values fields */
DGLValue* values_; DGLValue* values_;
/*! \brief The type code fields */ /*! @brief The type code fields */
int* type_codes_; int* type_codes_;
}; };
......
include/dgl/runtime/registry.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2017 by Contributors * Copyright (c) 2017 by Contributors
* \file dgl/runtime/registry.h * @file dgl/runtime/registry.h
* \brief This file defines the DGL global function registry. * @brief This file defines the DGL global function registry.
* *
* The registered functions will be made available to front-end * The registered functions will be made available to front-end
* as well as backend users. * as well as backend users.
...@@ -33,23 +33,23 @@ ...@@ -33,23 +33,23 @@
namespace dgl { namespace dgl {
namespace runtime { namespace runtime {
/*! \brief Registry for global function */ /*! @brief Registry for global function */
class Registry { class Registry {
public: public:
/*! /*!
* \brief set the body of the function to be f * @brief set the body of the function to be f
* \param f The body of the function. * @param f The body of the function.
*/ */
DGL_DLL Registry& set_body(PackedFunc f); // NOLINT(*) DGL_DLL Registry& set_body(PackedFunc f); // NOLINT(*)
/*! /*!
* \brief set the body of the function to be f * @brief set the body of the function to be f
* \param f The body of the function. * @param f The body of the function.
*/ */
Registry& set_body(PackedFunc::FType f) { // NOLINT(*) Registry& set_body(PackedFunc::FType f) { // NOLINT(*)
return set_body(PackedFunc(f)); return set_body(PackedFunc(f));
} }
/*! /*!
* \brief set the body of the function to be TypedPackedFunc. * @brief set the body of the function to be TypedPackedFunc.
* *
* \code * \code
* *
...@@ -58,38 +58,38 @@ class Registry { ...@@ -58,38 +58,38 @@ class Registry {
* *
* \endcode * \endcode
* *
* \param f The body of the function. * @param f The body of the function.
* \tparam FType the signature of the function. * @tparam FType the signature of the function.
* \tparam FLambda The type of f. * @tparam FLambda The type of f.
*/ */
template <typename FType, typename FLambda> template <typename FType, typename FLambda>
Registry& set_body_typed(FLambda f) { Registry& set_body_typed(FLambda f) {
return set_body(TypedPackedFunc<FType>(f).packed()); return set_body(TypedPackedFunc<FType>(f).packed());
} }
/*! /*!
* \brief Register a function with given name * @brief Register a function with given name
* \param name The name of the function. * @param name The name of the function.
* \param override Whether allow oveeride existing function. * @param override Whether allow oveeride existing function.
* \return Reference to theregistry. * @return Reference to theregistry.
*/ */
DGL_DLL static Registry& Register( DGL_DLL static Registry& Register(
const std::string& name, bool override = false); // NOLINT(*) const std::string& name, bool override = false); // NOLINT(*)
/*! /*!
* \brief Erase global function from registry, if exist. * @brief Erase global function from registry, if exist.
* \param name The name of the function. * @param name The name of the function.
* \return Whether function exist. * @return Whether function exist.
*/ */
DGL_DLL static bool Remove(const std::string& name); DGL_DLL static bool Remove(const std::string& name);
/*! /*!
* \brief Get the global function by name. * @brief Get the global function by name.
* \param name The name of the function. * @param name The name of the function.
* \return pointer to the registered function, * @return pointer to the registered function,
* nullptr if it does not exist. * nullptr if it does not exist.
*/ */
DGL_DLL static const PackedFunc* Get(const std::string& name); // NOLINT(*) DGL_DLL static const PackedFunc* Get(const std::string& name); // NOLINT(*)
/*! /*!
* \brief Get the names of currently registered global function. * @brief Get the names of currently registered global function.
* \return The names * @return The names
*/ */
DGL_DLL static std::vector<std::string> ListNames(); DGL_DLL static std::vector<std::string> ListNames();
...@@ -97,14 +97,14 @@ class Registry { ...@@ -97,14 +97,14 @@ class Registry {
struct Manager; struct Manager;
protected: protected:
/*! \brief name of the function */ /*! @brief name of the function */
std::string name_; std::string name_;
/*! \brief internal packed function */ /*! @brief internal packed function */
PackedFunc func_; PackedFunc func_;
friend struct Manager; friend struct Manager;
}; };
/*! \brief helper macro to supress unused warning */ /*! @brief helper macro to supress unused warning */
#if defined(__GNUC__) #if defined(__GNUC__)
#define DGL_ATTRIBUTE_UNUSED __attribute__((unused)) #define DGL_ATTRIBUTE_UNUSED __attribute__((unused))
#else #else
...@@ -121,7 +121,7 @@ class Registry { ...@@ -121,7 +121,7 @@ class Registry {
static DGL_ATTRIBUTE_UNUSED ::dgl::runtime::ExtTypeVTable* __mk_##DGLT static DGL_ATTRIBUTE_UNUSED ::dgl::runtime::ExtTypeVTable* __mk_##DGLT
/*! /*!
* \brief Register a function globally. * @brief Register a function globally.
* \code * \code
* DGL_REGISTER_GLOBAL("MyPrint") * DGL_REGISTER_GLOBAL("MyPrint")
* .set_body([](DGLArgs args, DGLRetValue* rv) { * .set_body([](DGLArgs args, DGLRetValue* rv) {
...@@ -133,7 +133,7 @@ class Registry { ...@@ -133,7 +133,7 @@ class Registry {
::dgl::runtime::Registry::Register(OpName) ::dgl::runtime::Registry::Register(OpName)
/*! /*!
* \brief Macro to register extension type. * @brief Macro to register extension type.
* This must be registered in a cc file * This must be registered in a cc file
* after the trait extension_class_info is defined. * after the trait extension_class_info is defined.
*/ */
......
include/dgl/runtime/serializer.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2017 by Contributors * Copyright (c) 2017 by Contributors
* \file dgl/runtime/serializer.h * @file dgl/runtime/serializer.h
* \brief Serializer extension to support DGL data types * @brief Serializer extension to support DGL data types
* Include this file to enable serialization of DGLDataType, DGLContext * Include this file to enable serialization of DGLDataType, DGLContext
*/ */
#ifndef DGL_RUNTIME_SERIALIZER_H_ #ifndef DGL_RUNTIME_SERIALIZER_H_
......
include/dgl/runtime/shared_mem.h
View file @ 6c53f351
/*! /*!
* Copyright (c) 2017 by Contributors * Copyright (c) 2017 by Contributors
* \file dgl/runtime/ndarray.h * @file dgl/runtime/ndarray.h
* \brief shared memory management. * @brief shared memory management.
*/ */
#ifndef DGL_RUNTIME_SHARED_MEM_H_ #ifndef DGL_RUNTIME_SHARED_MEM_H_
#define DGL_RUNTIME_SHARED_MEM_H_ #define DGL_RUNTIME_SHARED_MEM_H_
...@@ -15,7 +15,7 @@ namespace dgl { ...@@ -15,7 +15,7 @@ namespace dgl {
namespace runtime { namespace runtime {
/* /*
* \brief This class owns shared memory. * @brief This class owns shared memory.
* *
* When the object is gone, the shared memory will also be destroyed. * When the object is gone, the shared memory will also be destroyed.
* When the shared memory is destroyed, the file corresponding to * When the shared memory is destroyed, the file corresponding to
...@@ -23,26 +23,26 @@ namespace runtime { ...@@ -23,26 +23,26 @@ namespace runtime {
*/ */
class SharedMemory { class SharedMemory {
/* /*
* \brief whether the shared memory is owned by the object. * @brief whether the shared memory is owned by the object.
* *
* If shared memory is created in the object, it'll be owned by the object * If shared memory is created in the object, it'll be owned by the object
* and will be responsible for deleting it when the object is destroyed. * and will be responsible for deleting it when the object is destroyed.
*/ */
bool own_; bool own_;
/* \brief the file descripter of the shared memory. */ /* @brief the file descripter of the shared memory. */
#ifndef _WIN32 #ifndef _WIN32
int fd_; int fd_;
#else // !_WIN32 #else // !_WIN32
HANDLE handle_; HANDLE handle_;
#endif // _WIN32 #endif // _WIN32
/* \brief the address of the shared memory. */ /* @brief the address of the shared memory. */
void *ptr_; void *ptr_;
/* \brief the size of the shared memory. */ /* @brief the size of the shared memory. */
size_t size_; size_t size_;
/* /*
* \brief the name of the object. * @brief the name of the object.
* *
* In Unix, shared memory is identified by a file. Thus, `name` is actually * In Unix, shared memory is identified by a file. Thus, `name` is actually
* the file name that identifies the shared memory. * the file name that identifies the shared memory.
...@@ -50,38 +50,38 @@ class SharedMemory { ...@@ -50,38 +50,38 @@ class SharedMemory {
std::string name; std::string name;
public: public:
/* \brief Get the filename of shared memory file /* @brief Get the filename of shared memory file
*/ */
std::string GetName() const { return name; } std::string GetName() const { return name; }
/* /*
* \brief constructor of the shared memory. * @brief constructor of the shared memory.
* \param name The file corresponding to the shared memory. * @param name The file corresponding to the shared memory.
*/ */
explicit SharedMemory(const std::string &name); explicit SharedMemory(const std::string &name);
/* /*
* \brief destructor of the shared memory. * @brief destructor of the shared memory.
* It deallocates the shared memory and removes the corresponding file. * It deallocates the shared memory and removes the corresponding file.
*/ */
~SharedMemory(); ~SharedMemory();
/* /*
* \brief create shared memory. * @brief create shared memory.
* It creates the file and shared memory. * It creates the file and shared memory.
* \param sz the size of the shared memory. * @param sz the size of the shared memory.
* \return the address of the shared memory * @return the address of the shared memory
*/ */
void *CreateNew(size_t sz); void *CreateNew(size_t sz);
/* /*
* \brief allocate shared memory that has been created. * @brief allocate shared memory that has been created.
* \param sz the size of the shared memory. * @param sz the size of the shared memory.
* \return the address of the shared memory * @return the address of the shared memory
*/ */
void *Open(size_t sz); void *Open(size_t sz);
/* /*
* \brief check if the shared memory exist. * @brief check if the shared memory exist.
* \param name the name of the shared memory. * @param name the name of the shared memory.
* \return a boolean value to indicate if the shared memory exists. * @return a boolean value to indicate if the shared memory exists.
*/ */
static bool Exist(const std::string &name); static bool Exist(const std::string &name);
}; };
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment