c_api.h

Go to the documentation of this file.

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

#ifndef MXNET_C_API_H_
#define MXNET_C_API_H_

#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus

#ifdef __cplusplus
#define DEFAULT(x) = x
#else
#define DEFAULT(x)
#endif  // __cplusplus

#include <stdint.h>

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef _WIN32
#ifdef MXNET_EXPORTS
#define MXNET_DLL __declspec(dllexport)
#else
#define MXNET_DLL __declspec(dllimport)
#endif
#else
#define MXNET_DLL
#endif

typedef unsigned int mx_uint;
typedef float mx_float;
// all the handles are simply void *
// will be casted internally to specific pointers types
// these typedefs are mainly used for readablity reasons
typedef void *NDArrayHandle;
typedef const void *FunctionHandle;
typedef void *AtomicSymbolCreator;
typedef void *CachedOpHandle;
typedef void *SymbolHandle;
typedef void *AtomicSymbolHandle;
typedef void *ExecutorHandle;
typedef void *DataIterCreator;
typedef void *DataIterHandle;
typedef void *KVStoreHandle;
typedef void *RecordIOHandle;
typedef void *RtcHandle;
typedef void *CudaModuleHandle;
typedef void *CudaKernelHandle;

typedef void (*ExecutorMonitorCallback)(const char*,
                                        NDArrayHandle,
                                        void *);

struct NativeOpInfo {
  void (*forward)(int, float**, int*, unsigned**, int*, void*);
  void (*backward)(int, float**, int*, unsigned**, int*, void*);
  void (*infer_shape)(int, int*, unsigned**, void*);
  void (*list_outputs)(char***, void*);
  void (*list_arguments)(char***, void*);
  // all functions also pass a payload void* pointer
  void* p_forward;
  void* p_backward;
  void* p_infer_shape;
  void* p_list_outputs;
  void* p_list_arguments;
};

struct NDArrayOpInfo {
  bool (*forward)(int, void**, int*, void*);
  bool (*backward)(int, void**, int*, void*);
  bool (*infer_shape)(int, int*, unsigned**, void*);
  bool (*list_outputs)(char***, void*);
  bool (*list_arguments)(char***, void*);
  bool (*declare_backward_dependency)(const int*, const int*, const int*,
                                      int*, int**, void*);
  // all functions also pass a payload void* pointer
  void* p_forward;
  void* p_backward;
  void* p_infer_shape;
  void* p_list_outputs;
  void* p_list_arguments;
  void* p_declare_backward_dependency;
};

typedef int (*MXGenericCallback)(void);

struct MXCallbackList {
  int num_callbacks;
  int (**callbacks)(void);
  void **contexts;
};

enum CustomOpCallbacks {
  kCustomOpDelete,
  kCustomOpForward,
  kCustomOpBackward
};

enum CustomOpPropCallbacks {
  kCustomOpPropDelete,
  kCustomOpPropListArguments,
  kCustomOpPropListOutputs,
  kCustomOpPropListAuxiliaryStates,
  kCustomOpPropInferShape,
  kCustomOpPropDeclareBackwardDependency,
  kCustomOpPropCreateOperator,
  kCustomOpPropInferType
};


typedef int (*CustomOpFBFunc)(int /*size*/, void** /*ptrs*/, int* /*tags*/,
                              const int* /*reqs*/, const int /*is_train*/,
                              void* /*state*/);
typedef int (*CustomOpDelFunc)(void* /*state*/);
typedef int (*CustomOpListFunc)(char*** /*args*/, void* /*state*/);
typedef int (*CustomOpInferShapeFunc)(int /*num_input*/, int* /*ndims*/,
                                      unsigned** /*shapes*/, void* /*state*/);
typedef int (*CustomOpInferTypeFunc)(int /*num_input*/, int* /*types*/, void* /*state*/);
typedef int (*CustomOpBwdDepFunc)(const int* /*out_grad*/, const int* /*in_data*/,
                                  const int* /*out_data*/, int* /*num_deps*/,
                                  int** /*rdeps*/, void* /*state*/);
typedef int (*CustomOpCreateFunc)(const char* /*ctx*/, int /*num_inputs*/,
                                  unsigned** /*shapes*/, const int* /*ndims*/,
                                  const int* /*dtypes*/, struct MXCallbackList* /*ret*/,
                                  void* /*state*/);
typedef int (*CustomOpPropCreator)(const char* /*op_type*/, const int /*num_kwargs*/,
                                   const char** /*keys*/, const char** /*values*/,
                                   struct MXCallbackList* /*ret*/);


enum CustomFunctionCallbacks {
  kCustomFunctionBackward,
  kCustomFunctionDelete
};

typedef int (*CustomFunctionBwdFunc)(int /*num_ograds*/, int /*num_igrads*/, void** /*ptrs*/,
                                     const int* /*reqs*/, const int /*is_train*/,
                                     void* /*state*/);
typedef int (*CustomFunctionDelFunc)(void* /*state*/);

MXNET_DLL const char *MXGetLastError();

//-------------------------------------
// Part 0: Global State setups
//-------------------------------------
MXNET_DLL int MXRandomSeed(int seed);
MXNET_DLL int MXNotifyShutdown();
MXNET_DLL int MXSetProfilerConfig(int mode, const char* filename);
MXNET_DLL int MXSetProfilerState(int state);

MXNET_DLL int MXDumpProfile();

MXNET_DLL int MXSetNumOMPThreads(int thread_num);

MXNET_DLL int MXEngineSetBulkSize(int bulk_size, int* prev_bulk_size);

MXNET_DLL int MXGetVersion(int *out);

//-------------------------------------
// Part 1: NDArray creation and deletion
//-------------------------------------
MXNET_DLL int MXNDArrayCreateNone(NDArrayHandle *out);
MXNET_DLL int MXNDArrayCreate(const mx_uint *shape,
                              mx_uint ndim,
                              int dev_type,
                              int dev_id,
                              int delay_alloc,
                              NDArrayHandle *out);

MXNET_DLL int MXNDArrayCreateEx(const mx_uint *shape,
                              mx_uint ndim,
                              int dev_type,
                              int dev_id,
                              int delay_alloc,
                              int dtype,
                              NDArrayHandle *out);


MXNET_DLL int MXNDArrayCreateSparseEx(int storage_type,
                                      const mx_uint *shape,
                                      mx_uint ndim,
                                      int dev_type,
                                      int dev_id,
                                      int delay_alloc,
                                      int dtype,
                                      mx_uint num_aux,
                                      int *aux_type,
                                      mx_uint *aux_ndims,
                                      const mx_uint *aux_shape,
                                      NDArrayHandle *out);

MXNET_DLL int MXNDArrayLoadFromRawBytes(const void *buf,
                                        size_t size,
                                        NDArrayHandle *out);
MXNET_DLL int MXNDArraySaveRawBytes(NDArrayHandle handle,
                                    size_t *out_size,
                                    const char **out_buf);
MXNET_DLL int MXNDArraySave(const char* fname,
                            mx_uint num_args,
                            NDArrayHandle* args,
                            const char** keys);
MXNET_DLL int MXNDArrayLoad(const char* fname,
                            mx_uint *out_size,
                            NDArrayHandle** out_arr,
                            mx_uint *out_name_size,
                            const char*** out_names);
MXNET_DLL int MXNDArraySyncCopyFromCPU(NDArrayHandle handle,
                                       const void *data,
                                       size_t size);
MXNET_DLL int MXNDArraySyncCopyToCPU(NDArrayHandle handle,
                                     void *data,
                                     size_t size);
MXNET_DLL int MXNDArraySyncCopyFromNDArray(NDArrayHandle handle_dst,
                                           const NDArrayHandle handle_src,
                                           const int i);

MXNET_DLL int MXNDArraySyncCheckFormat(NDArrayHandle handle, const bool full_check);
MXNET_DLL int MXNDArrayWaitToRead(NDArrayHandle handle);
MXNET_DLL int MXNDArrayWaitToWrite(NDArrayHandle handle);
MXNET_DLL int MXNDArrayWaitAll();
MXNET_DLL int MXNDArrayFree(NDArrayHandle handle);
MXNET_DLL int MXNDArraySlice(NDArrayHandle handle,
                             mx_uint slice_begin,
                             mx_uint slice_end,
                             NDArrayHandle *out);

MXNET_DLL int MXNDArrayAt(NDArrayHandle handle,
                          mx_uint idx,
                          NDArrayHandle *out);

MXNET_DLL int MXNDArrayGetStorageType(NDArrayHandle handle,
                                      int *out_storage_type);

MXNET_DLL int MXNDArrayReshape(NDArrayHandle handle,
                               int ndim,
                               int *dims,
                               NDArrayHandle *out);
MXNET_DLL int MXNDArrayGetShape(NDArrayHandle handle,
                                mx_uint *out_dim,
                                const mx_uint **out_pdata);
MXNET_DLL int MXNDArrayGetData(NDArrayHandle handle,
                               void **out_pdata);
MXNET_DLL int MXNDArrayGetDType(NDArrayHandle handle,
                               int *out_dtype);

MXNET_DLL int MXNDArrayGetAuxType(NDArrayHandle handle,
                                  mx_uint i,
                                  int *out_type);

MXNET_DLL int MXNDArrayGetAuxNDArray(NDArrayHandle handle,
                                     mx_uint i,
                                     NDArrayHandle *out);

MXNET_DLL int MXNDArrayGetDataNDArray(NDArrayHandle handle,
                                      NDArrayHandle *out);
MXNET_DLL int MXNDArrayGetContext(NDArrayHandle handle,
                                  int *out_dev_type,
                                  int *out_dev_id);
MXNET_DLL int MXNDArrayGetGrad(NDArrayHandle handle, NDArrayHandle *out);
MXNET_DLL int MXNDArrayDetach(NDArrayHandle handle, NDArrayHandle *out);
MXNET_DLL int MXNDArraySetGradState(NDArrayHandle handle, int state);
MXNET_DLL int MXNDArrayGetGradState(NDArrayHandle handle, int *out);
//--------------------------------
// Part 2: functions on NDArray
//--------------------------------
MXNET_DLL int MXListFunctions(mx_uint *out_size,
                              FunctionHandle **out_array);
MXNET_DLL int MXGetFunction(const char *name,
                            FunctionHandle *out);
MXNET_DLL int MXFuncGetInfo(FunctionHandle fun,
                            const char **name,
                            const char **description,
                            mx_uint *num_args,
                            const char ***arg_names,
                            const char ***arg_type_infos,
                            const char ***arg_descriptions,
                            const char **return_type DEFAULT(NULL));
MXNET_DLL int MXFuncDescribe(FunctionHandle fun,
                             mx_uint *num_use_vars,
                             mx_uint *num_scalars,
                             mx_uint *num_mutate_vars,
                             int *type_mask);
MXNET_DLL int MXFuncInvoke(FunctionHandle fun,
                           NDArrayHandle *use_vars,
                           mx_float *scalar_args,
                           NDArrayHandle *mutate_vars);
MXNET_DLL int MXFuncInvokeEx(FunctionHandle fun,
                             NDArrayHandle *use_vars,
                             mx_float *scalar_args,
                             NDArrayHandle *mutate_vars,
                             int num_params,
                             char **param_keys,
                             char **param_vals);
MXNET_DLL int MXImperativeInvoke(AtomicSymbolCreator creator,
                                 int num_inputs,
                                 NDArrayHandle *inputs,
                                 int *num_outputs,
                                 NDArrayHandle **outputs,
                                 int num_params,
                                 const char **param_keys,
                                 const char **param_vals);
MXNET_DLL int MXImperativeInvokeEx(AtomicSymbolCreator creator,
                                   int num_inputs,
                                   NDArrayHandle *inputs,
                                   int *num_outputs,
                                   NDArrayHandle **outputs,
                                   int num_params,
                                   const char **param_keys,
                                   const char **param_vals,
                                   const int **out_stypes);
MXNET_DLL int MXAutogradSetIsRecording(int is_recording, int* prev);
MXNET_DLL int MXAutogradSetIsTraining(int is_training, int* prev);
MXNET_DLL int MXAutogradIsRecording(bool* curr);
MXNET_DLL int MXAutogradIsTraining(bool* curr);
MXNET_DLL int MXAutogradMarkVariables(mx_uint num_var,
                                      NDArrayHandle *var_handles,
                                      mx_uint *reqs_array,
                                      NDArrayHandle *grad_handles);
MXNET_DLL int MXAutogradComputeGradient(mx_uint num_output,
                                        NDArrayHandle* output_handles);
MXNET_DLL int MXAutogradBackward(mx_uint num_output,
                                 NDArrayHandle* output_handles,
                                 NDArrayHandle* ograd_handles,
                                 int retain_graph);
MXNET_DLL int MXAutogradBackwardEx(mx_uint num_output,
                                   NDArrayHandle *output_handles,
                                   NDArrayHandle *ograd_handles,
                                   mx_uint num_variables,
                                   NDArrayHandle *var_handles,
                                   int retain_graph,
                                   int create_graph,
                                   int is_train,
                                   NDArrayHandle **grad_handles,
                                   int **grad_stypes);
/*
 * \brief get the graph constructed by autograd.
 * \param handle ndarray handle
 * \param out output symbol handle
 */
MXNET_DLL int MXAutogradGetSymbol(NDArrayHandle handle, SymbolHandle *out);
MXNET_DLL int MXCreateCachedOp(SymbolHandle handle, CachedOpHandle *out);
MXNET_DLL int MXCreateCachedOpEx(SymbolHandle handle,
                                 int num_params,
                                 const char** keys,
                                 const char** vals,
                                 CachedOpHandle *out);
MXNET_DLL int MXFreeCachedOp(CachedOpHandle handle);
MXNET_DLL int MXInvokeCachedOp(CachedOpHandle handle,
                               int num_inputs,
                               NDArrayHandle *inputs,
                               int *num_outputs,
                               NDArrayHandle **outputs);
MXNET_DLL int MXInvokeCachedOpEx(CachedOpHandle handle,
                                 int num_inputs,
                                 NDArrayHandle *inputs,
                                 int *num_outputs,
                                 NDArrayHandle **outputs,
                                 const int** out_stypes);
MXNET_DLL int MXInvokeCachedOp(CachedOpHandle handle,
                               int num_inputs,
                               NDArrayHandle *inputs,
                               int *num_outputs,
                               NDArrayHandle **outputs);
//--------------------------------------------
// Part 3: symbolic configuration generation
//--------------------------------------------
MXNET_DLL int MXListAllOpNames(mx_uint *out_size,
                               const char ***out_array);
MXNET_DLL int MXSymbolListAtomicSymbolCreators(mx_uint *out_size,
                                               AtomicSymbolCreator **out_array);

MXNET_DLL int MXSymbolGetAtomicSymbolName(AtomicSymbolCreator creator,
                                          const char **name);
MXNET_DLL int MXSymbolGetAtomicSymbolInfo(AtomicSymbolCreator creator,
                                          const char **name,
                                          const char **description,
                                          mx_uint *num_args,
                                          const char ***arg_names,
                                          const char ***arg_type_infos,
                                          const char ***arg_descriptions,
                                          const char **key_var_num_args,
                                          const char **return_type DEFAULT(NULL));
MXNET_DLL int MXSymbolCreateAtomicSymbol(AtomicSymbolCreator creator,
                                         mx_uint num_param,
                                         const char **keys,
                                         const char **vals,
                                         SymbolHandle *out);
MXNET_DLL int MXSymbolCreateVariable(const char *name, SymbolHandle *out);
MXNET_DLL int MXSymbolCreateGroup(mx_uint num_symbols,
                                  SymbolHandle *symbols,
                                  SymbolHandle *out);
MXNET_DLL int MXSymbolCreateFromFile(const char *fname, SymbolHandle *out);
MXNET_DLL int MXSymbolCreateFromJSON(const char *json, SymbolHandle *out);
MXNET_DLL int MXSymbolSaveToFile(SymbolHandle symbol, const char *fname);
MXNET_DLL int MXSymbolSaveToJSON(SymbolHandle symbol, const char **out_json);
MXNET_DLL int MXSymbolFree(SymbolHandle symbol);
MXNET_DLL int MXSymbolCopy(SymbolHandle symbol, SymbolHandle *out);
MXNET_DLL int MXSymbolPrint(SymbolHandle symbol, const char **out_str);
MXNET_DLL int MXSymbolGetName(SymbolHandle symbol,
                              const char** out,
                              int *success);
MXNET_DLL int MXSymbolGetAttr(SymbolHandle symbol,
                              const char* key,
                              const char** out,
                              int *success);
MXNET_DLL int MXSymbolSetAttr(SymbolHandle symbol,
                              const char* key,
                              const char* value);
MXNET_DLL int MXSymbolListAttr(SymbolHandle symbol,
                               mx_uint *out_size,
                               const char*** out);
MXNET_DLL int MXSymbolListAttrShallow(SymbolHandle symbol,
                                      mx_uint *out_size,
                                      const char*** out);
MXNET_DLL int MXSymbolListArguments(SymbolHandle symbol,
                                    mx_uint *out_size,
                                    const char ***out_str_array);
MXNET_DLL int MXSymbolListOutputs(SymbolHandle symbol,
                                  mx_uint *out_size,
                                  const char ***out_str_array);

MXNET_DLL int MXSymbolGetNumOutputs(SymbolHandle symbol,
                                     mx_uint *output_count);

MXNET_DLL int MXSymbolGetInternals(SymbolHandle symbol,
                                   SymbolHandle *out);
MXNET_DLL int MXSymbolGetChildren(SymbolHandle symbol,
                                  SymbolHandle *out);
MXNET_DLL int MXSymbolGetOutput(SymbolHandle symbol,
                                mx_uint index,
                                SymbolHandle *out);

MXNET_DLL int MXSymbolListAuxiliaryStates(SymbolHandle symbol,
                                          mx_uint *out_size,
                                          const char ***out_str_array);
MXNET_DLL int MXSymbolCompose(SymbolHandle sym,
                              const char *name,
                              mx_uint num_args,
                              const char** keys,
                              SymbolHandle* args);
MXNET_DLL int MXSymbolGrad(SymbolHandle sym,
                           mx_uint num_wrt,
                           const char** wrt,
                           SymbolHandle* out);
MXNET_DLL int MXSymbolInferShape(SymbolHandle sym,
                                 mx_uint num_args,
                                 const char** keys,
                                 const mx_uint *arg_ind_ptr,
                                 const mx_uint *arg_shape_data,
                                 mx_uint *in_shape_size,
                                 const mx_uint **in_shape_ndim,
                                 const mx_uint ***in_shape_data,
                                 mx_uint *out_shape_size,
                                 const mx_uint **out_shape_ndim,
                                 const mx_uint ***out_shape_data,
                                 mx_uint *aux_shape_size,
                                 const mx_uint **aux_shape_ndim,
                                 const mx_uint ***aux_shape_data,
                                 int *complete);
MXNET_DLL int MXSymbolInferShapePartial(SymbolHandle sym,
                                        mx_uint num_args,
                                        const char** keys,
                                        const mx_uint *arg_ind_ptr,
                                        const mx_uint *arg_shape_data,
                                        mx_uint *in_shape_size,
                                        const mx_uint **in_shape_ndim,
                                        const mx_uint ***in_shape_data,
                                        mx_uint *out_shape_size,
                                        const mx_uint **out_shape_ndim,
                                        const mx_uint ***out_shape_data,
                                        mx_uint *aux_shape_size,
                                        const mx_uint **aux_shape_ndim,
                                        const mx_uint ***aux_shape_data,
                                        int *complete);

MXNET_DLL int MXSymbolInferType(SymbolHandle sym,
                                mx_uint num_args,
                                const char** keys,
                                const int *arg_type_data,
                                mx_uint *in_type_size,
                                const int **in_type_data,
                                mx_uint *out_type_size,
                                const int **out_type_data,
                                mx_uint *aux_type_size,
                                const int **aux_type_data,
                                int *complete);




//--------------------------------------------
// Part 4: Executor interface
//--------------------------------------------
MXNET_DLL int MXExecutorFree(ExecutorHandle handle);
MXNET_DLL int MXExecutorPrint(ExecutorHandle handle, const char **out_str);
MXNET_DLL int MXExecutorForward(ExecutorHandle handle, int is_train);
MXNET_DLL int MXExecutorBackward(ExecutorHandle handle,
                                 mx_uint len,
                                 NDArrayHandle *head_grads);
MXNET_DLL int MXExecutorBackwardEx(ExecutorHandle handle,
                                   mx_uint len,
                                   NDArrayHandle *head_grads,
                                   int is_train);
MXNET_DLL int MXExecutorOutputs(ExecutorHandle handle,
                                mx_uint *out_size,
                                NDArrayHandle **out);

MXNET_DLL int MXExecutorBind(SymbolHandle symbol_handle,
                             int dev_type,
                             int dev_id,
                             mx_uint len,
                             NDArrayHandle *in_args,
                             NDArrayHandle *arg_grad_store,
                             mx_uint *grad_req_type,
                             mx_uint aux_states_len,
                             NDArrayHandle *aux_states,
                             ExecutorHandle *out);
MXNET_DLL int MXExecutorBindX(SymbolHandle symbol_handle,
                              int dev_type,
                              int dev_id,
                              mx_uint num_map_keys,
                              const char** map_keys,
                              const int* map_dev_types,
                              const int* map_dev_ids,
                              mx_uint len,
                              NDArrayHandle *in_args,
                              NDArrayHandle *arg_grad_store,
                              mx_uint *grad_req_type,
                              mx_uint aux_states_len,
                              NDArrayHandle *aux_states,
                              ExecutorHandle *out);
MXNET_DLL int MXExecutorBindEX(SymbolHandle symbol_handle,
                               int dev_type,
                               int dev_id,
                               mx_uint num_map_keys,
                               const char** map_keys,
                               const int* map_dev_types,
                               const int* map_dev_ids,
                               mx_uint len,
                               NDArrayHandle *in_args,
                               NDArrayHandle *arg_grad_store,
                               mx_uint *grad_req_type,
                               mx_uint aux_states_len,
                               NDArrayHandle *aux_states,
                               ExecutorHandle shared_exec,
                               ExecutorHandle *out);

MXNET_DLL int MXExecutorSimpleBind(SymbolHandle symbol_handle,
                                   int dev_type,
                                   int dev_id,
                                   const mx_uint num_g2c_keys,
                                   const char** g2c_keys,
                                   const int* g2c_dev_types,
                                   const int* g2c_dev_ids,
                                   const mx_uint provided_grad_req_list_len,
                                   const char** provided_grad_req_names,
                                   const char** provided_grad_req_types,
                                   const mx_uint num_provided_arg_shapes,
                                   const char** provided_arg_shape_names,
                                   const mx_uint* provided_arg_shape_data,
                                   const mx_uint* provided_arg_shape_idx,
                                   const mx_uint num_provided_arg_dtypes,
                                   const char** provided_arg_dtype_names,
                                   const int* provided_arg_dtypes,
                                   const mx_uint num_provided_arg_stypes,
                                   const char** provided_arg_stype_names,
                                   const int* provided_arg_stypes,
                                   const mx_uint num_shared_arg_names,
                                   const char** shared_arg_name_list,
                                   int* shared_buffer_len,
                                   const char** shared_buffer_name_list,
                                   NDArrayHandle* shared_buffer_handle_list,
                                   const char*** updated_shared_buffer_name_list,
                                   NDArrayHandle** updated_shared_buffer_handle_list,
                                   mx_uint* num_in_args,
                                   NDArrayHandle** in_args,
                                   NDArrayHandle** arg_grads,
                                   mx_uint* num_aux_states,
                                   NDArrayHandle** aux_states,
                                   ExecutorHandle shared_exec_handle,
                                   ExecutorHandle* out);
MXNET_DLL int MXExecutorSetMonitorCallback(ExecutorHandle handle,
                                           ExecutorMonitorCallback callback,
                                           void* callback_handle);
//--------------------------------------------
// Part 5: IO Interface
//--------------------------------------------
MXNET_DLL int MXListDataIters(mx_uint *out_size,
                              DataIterCreator **out_array);
MXNET_DLL int MXDataIterCreateIter(DataIterCreator handle,
                                   mx_uint num_param,
                                   const char **keys,
                                   const char **vals,
                                   DataIterHandle *out);
MXNET_DLL int MXDataIterGetIterInfo(DataIterCreator creator,
                                    const char **name,
                                    const char **description,
                                    mx_uint *num_args,
                                    const char ***arg_names,
                                    const char ***arg_type_infos,
                                    const char ***arg_descriptions);
MXNET_DLL int MXDataIterFree(DataIterHandle handle);
MXNET_DLL int MXDataIterNext(DataIterHandle handle,
                             int *out);
MXNET_DLL int MXDataIterBeforeFirst(DataIterHandle handle);

MXNET_DLL int MXDataIterGetData(DataIterHandle handle,
                                NDArrayHandle *out);
MXNET_DLL int MXDataIterGetIndex(DataIterHandle handle,
                                 uint64_t **out_index,
                                 uint64_t *out_size);
MXNET_DLL int MXDataIterGetPadNum(DataIterHandle handle,
                                  int *pad);

MXNET_DLL int MXDataIterGetLabel(DataIterHandle handle,
                                 NDArrayHandle *out);
//--------------------------------------------
// Part 6: basic KVStore interface
//--------------------------------------------
MXNET_DLL int MXInitPSEnv(mx_uint num_vars,
                          const char **keys,
                          const char **vals);


MXNET_DLL int MXKVStoreCreate(const char *type,
                              KVStoreHandle *out);

MXNET_DLL int MXKVStoreSetGradientCompression(KVStoreHandle handle,
                                              mx_uint num_params,
                                              const char** keys,
                                              const char** vals);

MXNET_DLL int MXKVStoreFree(KVStoreHandle handle);
MXNET_DLL int MXKVStoreInit(KVStoreHandle handle,
                            mx_uint num,
                            const int* keys,
                            NDArrayHandle* vals);

MXNET_DLL int MXKVStoreInitEx(KVStoreHandle handle,
                              mx_uint num,
                              const char** keys,
                              NDArrayHandle* vals);

MXNET_DLL int MXKVStorePush(KVStoreHandle handle,
                            mx_uint num,
                            const int* keys,
                            NDArrayHandle* vals,
                            int priority);
MXNET_DLL int MXKVStorePushEx(KVStoreHandle handle,
                              mx_uint num,
                              const char** keys,
                              NDArrayHandle* vals,
                              int priority);
MXNET_DLL int MXKVStorePull(KVStoreHandle handle,
                            mx_uint num,
                            const int* keys,
                            NDArrayHandle* vals,
                            int priority);
MXNET_DLL int MXKVStorePullEx(KVStoreHandle handle,
                              mx_uint num,
                              const char** keys,
                              NDArrayHandle* vals,
                              int priority);

MXNET_DLL int MXKVStorePullRowSparse(KVStoreHandle handle,
                                     mx_uint num,
                                     const int* keys,
                                     NDArrayHandle* vals,
                                     const NDArrayHandle* row_ids,
                                     int priority);
MXNET_DLL int MXKVStorePullRowSparseEx(KVStoreHandle handle,
                                       mx_uint num,
                                       const char** keys,
                                       NDArrayHandle* vals,
                                       const NDArrayHandle* row_ids,
                                       int priority);

typedef void (MXKVStoreUpdater)(int key,
                                NDArrayHandle recv,
                                NDArrayHandle local,
                                void *handle);
typedef void (MXKVStoreStrUpdater)(const char* key,
                                   NDArrayHandle recv,
                                   NDArrayHandle local,
                                   void *handle);
MXNET_DLL int MXKVStoreSetUpdater(KVStoreHandle handle,
                                  MXKVStoreUpdater updater,
                                  void *updater_handle);
MXNET_DLL int MXKVStoreSetUpdaterEx(KVStoreHandle handle,
                                    MXKVStoreUpdater updater,
                                    MXKVStoreStrUpdater str_updater,
                                    void *updater_handle);
MXNET_DLL int MXKVStoreGetType(KVStoreHandle handle,
                               const char** type);
//--------------------------------------------
// Part 6: advanced KVStore for multi-machines
//--------------------------------------------

MXNET_DLL int MXKVStoreGetRank(KVStoreHandle handle,
                               int *ret);

MXNET_DLL int MXKVStoreGetGroupSize(KVStoreHandle handle,
                                    int *ret);

MXNET_DLL int MXKVStoreIsWorkerNode(int *ret);


MXNET_DLL int MXKVStoreIsServerNode(int *ret);


MXNET_DLL int MXKVStoreIsSchedulerNode(int *ret);

MXNET_DLL int MXKVStoreBarrier(KVStoreHandle handle);

MXNET_DLL int MXKVStoreSetBarrierBeforeExit(KVStoreHandle handle,
                                            const int barrier_before_exit);

typedef void (MXKVStoreServerController)(int head,
                                         const char *body,
                                         void *controller_handle);

MXNET_DLL int MXKVStoreRunServer(KVStoreHandle handle,
                                 MXKVStoreServerController controller,
                                 void *controller_handle);

MXNET_DLL int MXKVStoreSendCommmandToServers(KVStoreHandle handle,
                                             int cmd_id,
                                             const char* cmd_body);

MXNET_DLL int MXKVStoreGetNumDeadNode(KVStoreHandle handle,
                                      const int node_id,
                                      int *number,
                                      const int timeout_sec DEFAULT(60));

MXNET_DLL int MXRecordIOWriterCreate(const char *uri, RecordIOHandle *out);

MXNET_DLL int MXRecordIOWriterFree(RecordIOHandle handle);

MXNET_DLL int MXRecordIOWriterWriteRecord(RecordIOHandle handle,
                                          const char *buf, size_t size);

MXNET_DLL int MXRecordIOWriterTell(RecordIOHandle handle, size_t *pos);

MXNET_DLL int MXRecordIOReaderCreate(const char *uri, RecordIOHandle *out);

MXNET_DLL int MXRecordIOReaderFree(RecordIOHandle handle);

MXNET_DLL int MXRecordIOReaderReadRecord(RecordIOHandle handle,
                                        char const **buf, size_t *size);

MXNET_DLL int MXRecordIOReaderSeek(RecordIOHandle handle, size_t pos);

MXNET_DLL int MXRecordIOReaderTell(RecordIOHandle handle, size_t *pos);

MXNET_DLL int MXRtcCreate(char* name, mx_uint num_input, mx_uint num_output,
                          char** input_names, char** output_names,
                          NDArrayHandle* inputs, NDArrayHandle* outputs,
                          char* kernel, RtcHandle *out);

MXNET_DLL int MXRtcPush(RtcHandle handle, mx_uint num_input, mx_uint num_output,
                        NDArrayHandle* inputs, NDArrayHandle* outputs,
                        mx_uint gridDimX,
                        mx_uint gridDimY,
                        mx_uint gridDimZ,
                        mx_uint blockDimX,
                        mx_uint blockDimY,
                        mx_uint blockDimZ);

MXNET_DLL int MXRtcFree(RtcHandle handle);
/*
 * \brief register custom operators from frontend.
 * \param op_type name of custom op
 * \param creator
 */
MXNET_DLL int MXCustomOpRegister(const char* op_type, CustomOpPropCreator creator);
/*
 * \brief record custom function for backward later.
 * \param num_inputs number of input NDArrays.
 * \param inputs handle to input NDArrays.
 * \param num_outputs number of output NDArrays.
 * \param outputs handle to output NDArrays.
 * \param callbacks callbacks for backward function.
 */
MXNET_DLL int MXCustomFunctionRecord(int num_inputs, NDArrayHandle *inputs,
                                     int num_outputs, NDArrayHandle *outputs,
                                     struct MXCallbackList *callbacks);
/*
 * \brief create cuda rtc module
 * \param source cuda source code
 * \param num_options number of compiler flags
 * \param options compiler flags
 * \param num_exports number of exported function names
 * \param exported function names
 * \param out handle to created module
 */
MXNET_DLL int MXRtcCudaModuleCreate(const char* source, int num_options,
                                    const char** options, int num_exports,
                                    const char** exports, CudaModuleHandle *out);
/*
 * \brief delete cuda rtc module
 * \param handle handle to cuda module
 */
MXNET_DLL int MXRtcCudaModuleFree(CudaModuleHandle handle);
/*
 * \brief get kernel from module
 * \param handle handle to cuda module
 * \param name name of kernel function
 * \param num_args number of arguments
 * \param is_ndarray whether argument is ndarray
 * \param is_const whether argument is constant
 * \param arg_types data type of arguments
 * \param out created kernel
 */
MXNET_DLL int MXRtcCudaKernelCreate(CudaModuleHandle handle, const char* name,
                                    int num_args, int* is_ndarray, int* is_const,
                                    int* arg_types, CudaKernelHandle *out);
/*
 * \brief delete kernel
 * \param handle handle to previously created kernel
 */
MXNET_DLL int MXRtcCudaKernelFree(CudaKernelHandle handle);
/*
 * \brief launch cuda kernel
 * \param handle handle to kernel
 * \param dev_id (GPU) device id
 * \param args pointer to arguments
 * \param grid_dim_x grid dimension x
 * \param grid_dim_y grid dimension y
 * \param grid_dim_z grid dimension z
 * \param block_dim_x block dimension x
 * \param block_dim_y block dimension y
 * \param block_dim_z block dimension z
 * \param shared_mem size of dynamically allocated shared memory
 */
MXNET_DLL int MXRtcCudaKernelCall(CudaKernelHandle handle, int dev_id, void** args,
                                  mx_uint grid_dim_x, mx_uint grid_dim_y,
                                  mx_uint grid_dim_z, mx_uint block_dim_x,
                                  mx_uint block_dim_y, mx_uint block_dim_z,
                                  mx_uint shared_mem);
MXNET_DLL int MXNDArrayGetSharedMemHandle(NDArrayHandle handle, int* shared_pid,
                                          int* shared_id);
MXNET_DLL int MXNDArrayCreateFromSharedMem(int shared_pid, int shared_id, const mx_uint *shape,
                                           mx_uint ndim, int dtype, NDArrayHandle *out);


#ifdef __cplusplus
}
#endif  // __cplusplus

#endif  // MXNET_C_API_H_