mxnet
Macros | Typedefs | Functions
c_api.h File Reference

C API of NNVM symbolic construction and pass. Enables construction and transformation of Graph in any other host languages. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define NNVM_DLL   __attribute__((visibility("default")))
 NNVM_DLL prefix for windows. More...
 

Typedefs

typedef unsigned int nn_uint
 manually define unsigned int More...
 
typedef void * OpHandle
 handle to a function that takes param and creates symbol More...
 
typedef void * SymbolHandle
 handle to a symbol that can be bind as operator More...
 
typedef void * GraphHandle
 handle to Graph More...
 

Functions

NNVM_DLL void NNAPISetLastError (const char *msg)
 Set the last error message needed by C API. More...
 
NNVM_DLL const char * NNGetLastError (void)
 return str message of the last error all function in this file will return 0 when success and -1 when an error occurred, NNGetLastError can be called to retrieve the error More...
 
NNVM_DLL int NNListAllOpNames (nn_uint *out_size, const char ***out_array)
 list all the available operator names, include entries. More...
 
NNVM_DLL int NNGetOpHandle (const char *op_name, OpHandle *op_out)
 Get operator handle given name. More...
 
NNVM_DLL int NNListUniqueOps (nn_uint *out_size, OpHandle **out_array)
 list all the available operators. This won't include the alias, use ListAllNames instead to get all alias names. More...
 
NNVM_DLL int NNGetOpInfo (OpHandle op, const char **real_name, const char **description, nn_uint *num_doc_args, const char ***arg_names, const char ***arg_type_infos, const char ***arg_descriptions, const char **return_type)
 Get the detailed information about atomic symbol. More...
 
NNVM_DLL int NNSymbolCreateAtomicSymbol (OpHandle op, nn_uint num_param, const char **keys, const char **vals, SymbolHandle *out)
 Create an AtomicSymbol functor. More...
 
NNVM_DLL int NNSymbolCreateVariable (const char *name, SymbolHandle *out)
 Create a Variable Symbol. More...
 
NNVM_DLL int NNSymbolCreateGroup (nn_uint num_symbols, SymbolHandle *symbols, SymbolHandle *out)
 Create a Symbol by grouping list of symbols together. More...
 
NNVM_DLL int NNAddControlDeps (SymbolHandle handle, SymbolHandle src_dep)
 Add src_dep to the handle as control dep. More...
 
NNVM_DLL int NNSymbolFree (SymbolHandle symbol)
 Free the symbol handle. More...
 
NNVM_DLL int NNSymbolCopy (SymbolHandle symbol, SymbolHandle *out)
 Copy the symbol to another handle. More...
 
NNVM_DLL int NNSymbolPrint (SymbolHandle symbol, const char **out_str)
 Print the content of symbol, used for debug. More...
 
NNVM_DLL int NNSymbolGetAttr (SymbolHandle symbol, const char *key, const char **out, int *success)
 Get string attribute from symbol. More...
 
NNVM_DLL int NNSymbolSetAttrs (SymbolHandle symbol, nn_uint num_param, const char **keys, const char **values)
 Set string attribute from symbol. NOTE: Setting attribute to a symbol can affect the semantics(mutable/immutable) of symbolic graph. More...
 
NNVM_DLL int NNSymbolListAttrs (SymbolHandle symbol, int recursive_option, nn_uint *out_size, const char ***out)
 Get all attributes from symbol, including all descendents. More...
 
NNVM_DLL int NNSymbolListInputVariables (SymbolHandle symbol, int option, nn_uint *out_size, SymbolHandle **out_sym_array)
 List inputs variables in the symbol. More...
 
NNVM_DLL int NNSymbolListInputNames (SymbolHandle symbol, int option, nn_uint *out_size, const char ***out_str_array)
 List input names in the symbol. More...
 
NNVM_DLL int NNSymbolListOutputNames (SymbolHandle symbol, nn_uint *out_size, const char ***out_str_array)
 List returns names in the symbol. More...
 
NNVM_DLL int NNSymbolGetNumOutputs (SymbolHandle symbol, nn_uint *output_count)
 Supply number of outputs of the symbol. More...
 
NNVM_DLL int NNSymbolGetInternals (SymbolHandle symbol, SymbolHandle *out)
 Get a symbol that contains all the internals. More...
 
NNVM_DLL int NNSymbolGetChildren (SymbolHandle symbol, SymbolHandle *out)
 Get a symbol that contains only direct children. More...
 
NNVM_DLL int NNSymbolGetOutput (SymbolHandle symbol, nn_uint index, SymbolHandle *out)
 Get index-th outputs of the symbol. More...
 
NNVM_DLL int NNSymbolCompose (SymbolHandle sym, const char *name, nn_uint num_args, const char **keys, SymbolHandle *args)
 Compose the symbol on other symbols. More...
 
NNVM_DLL int NNGraphCreate (SymbolHandle symbol, GraphHandle *graph)
 create a graph handle from symbol More...
 
NNVM_DLL int NNGraphFree (GraphHandle handle)
 free the graph handle More...
 
NNVM_DLL int NNGraphGetSymbol (GraphHandle graph, SymbolHandle *symbol)
 Get a new symbol from the graph. More...
 
NNVM_DLL int NNGraphSetJSONAttr (GraphHandle handle, const char *key, const char *json_value)
 Get Set a attribute in json format. This feature allows pass graph attributes back and forth in reasonable speed. More...
 
NNVM_DLL int NNGraphGetJSONAttr (GraphHandle handle, const char *key, const char **json_out, int *success)
 Get a serialized attrirbute from graph. This feature allows pass graph attributes back and forth in reasonable speed. More...
 
NNVM_DLL int NNGraphSetNodeEntryListAttr_ (GraphHandle handle, const char *key, SymbolHandle list)
 Set a attribute whose type is std::vector<NodeEntry> in c++ This feature allows pass List of symbolic variables for gradient request. More...
 
NNVM_DLL int NNGraphApplyPasses (GraphHandle src, nn_uint num_pass, const char **pass_names, GraphHandle *dst)
 Apply passes on the src graph. More...
 

Detailed Description

C API of NNVM symbolic construction and pass. Enables construction and transformation of Graph in any other host languages.

Macro Definition Documentation

#define NNVM_DLL   __attribute__((visibility("default")))

NNVM_DLL prefix for windows.

Typedef Documentation

typedef void* GraphHandle

handle to Graph

typedef unsigned int nn_uint

manually define unsigned int

typedef void* OpHandle

handle to a function that takes param and creates symbol

typedef void* SymbolHandle

handle to a symbol that can be bind as operator

Function Documentation

NNVM_DLL int NNAddControlDeps ( SymbolHandle  handle,
SymbolHandle  src_dep 
)

Add src_dep to the handle as control dep.

Parameters
handleThe symbol to add dependency edges on.
src_depthe source handles.
NNVM_DLL void NNAPISetLastError ( const char *  msg)

Set the last error message needed by C API.

Parameters
msgThe error message to set.
NNVM_DLL const char* NNGetLastError ( void  )

return str message of the last error all function in this file will return 0 when success and -1 when an error occurred, NNGetLastError can be called to retrieve the error

this function is threadsafe and can be called by different thread

Returns
error info
NNVM_DLL int NNGetOpHandle ( const char *  op_name,
OpHandle op_out 
)

Get operator handle given name.

Parameters
op_nameThe name of the operator.
op_outThe returnning op handle.
NNVM_DLL int NNGetOpInfo ( OpHandle  op,
const char **  real_name,
const char **  description,
nn_uint num_doc_args,
const char ***  arg_names,
const char ***  arg_type_infos,
const char ***  arg_descriptions,
const char **  return_type 
)

Get the detailed information about atomic symbol.

Parameters
opThe operator handle.
real_nameThe returned name of the creator. This name is not the alias name of the atomic symbol.
descriptionThe returned description of the symbol.
num_doc_argsNumber of arguments that contain documents.
arg_namesName of the arguments of doc args
arg_type_infosType informations about the arguments.
arg_descriptionsDescription information about the arguments.
return_typeReturn type of the function, if any.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphApplyPasses ( GraphHandle  src,
nn_uint  num_pass,
const char **  pass_names,
GraphHandle dst 
)

Apply passes on the src graph.

Parameters
srcThe source graph handle.
num_passThe number of pass to be applied.
pass_namesThe names of the pass.
dstThe result graph.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphCreate ( SymbolHandle  symbol,
GraphHandle graph 
)

create a graph handle from symbol

Parameters
symbolThe symbol representing the graph.
graphThe graph handle created.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphFree ( GraphHandle  handle)

free the graph handle

Parameters
handleThe handle to be freed.
NNVM_DLL int NNGraphGetJSONAttr ( GraphHandle  handle,
const char *  key,
const char **  json_out,
int *  success 
)

Get a serialized attrirbute from graph. This feature allows pass graph attributes back and forth in reasonable speed.

Parameters
handleThe graph handle.
keyThe key to the attribute.
json_outThe result attribute, can be NULL if the attribute do not exist. The json_out is an array of [type_name, value]. Where the type_name is a registered type string in C++ side via DMLC_JSON_ENABLE_ANY.
successWhether the result is contained in out.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphGetSymbol ( GraphHandle  graph,
SymbolHandle symbol 
)

Get a new symbol from the graph.

Parameters
graphThe graph handle.
symbolThe corresponding symbol
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphSetJSONAttr ( GraphHandle  handle,
const char *  key,
const char *  json_value 
)

Get Set a attribute in json format. This feature allows pass graph attributes back and forth in reasonable speed.

Parameters
handleThe graph handle.
keyThe key to the attribute.
json_valueThe value need to be in format [type_name, value], Where type_name is a registered type string in C++ side via DMLC_JSON_ENABLE_ANY.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNGraphSetNodeEntryListAttr_ ( GraphHandle  handle,
const char *  key,
SymbolHandle  list 
)

Set a attribute whose type is std::vector<NodeEntry> in c++ This feature allows pass List of symbolic variables for gradient request.

Note
This is beta feature only used for test purpos
Parameters
handleThe graph handle.
keyThe key to the attribute.
listThe symbol whose outputs represents the list of NodeEntry to be passed.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNListAllOpNames ( nn_uint out_size,
const char ***  out_array 
)

list all the available operator names, include entries.

Parameters
out_sizethe size of returned array
out_arraythe output operator name array.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNListUniqueOps ( nn_uint out_size,
OpHandle **  out_array 
)

list all the available operators. This won't include the alias, use ListAllNames instead to get all alias names.

Parameters
out_sizethe size of returned array
out_arraythe output AtomicSymbolCreator array
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolCompose ( SymbolHandle  sym,
const char *  name,
nn_uint  num_args,
const char **  keys,
SymbolHandle args 
)

Compose the symbol on other symbols.

This function will change the sym hanlde. To achieve function apply behavior, copy the symbol first before apply.

Parameters
symthe symbol to apply
namethe name of symbol
num_argsnumber of arguments
keysthe key of keyword args (optional)
argsarguments to sym
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolCopy ( SymbolHandle  symbol,
SymbolHandle out 
)

Copy the symbol to another handle.

Parameters
symbolthe source symbol
outused to hold the result of copy
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolCreateAtomicSymbol ( OpHandle  op,
nn_uint  num_param,
const char **  keys,
const char **  vals,
SymbolHandle out 
)

Create an AtomicSymbol functor.

Parameters
opThe operator handle
num_paramthe number of parameters
keysthe keys to the params
valsthe vals of the params
outpointer to the created symbol handle
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolCreateGroup ( nn_uint  num_symbols,
SymbolHandle symbols,
SymbolHandle out 
)

Create a Symbol by grouping list of symbols together.

Parameters
num_symbolsnumber of symbols to be grouped
symbolsarray of symbol handles
outpointer to the created symbol handle
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolCreateVariable ( const char *  name,
SymbolHandle out 
)

Create a Variable Symbol.

Parameters
namename of the variable
outpointer to the created symbol handle
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolFree ( SymbolHandle  symbol)

Free the symbol handle.

Parameters
symbolthe symbol
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolGetAttr ( SymbolHandle  symbol,
const char *  key,
const char **  out,
int *  success 
)

Get string attribute from symbol.

Parameters
symbolthe source symbol
keyThe key of the symbol.
outThe result attribute, can be NULL if the attribute do not exist.
successWhether the result is contained in out.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolGetChildren ( SymbolHandle  symbol,
SymbolHandle out 
)

Get a symbol that contains only direct children.

Parameters
symbolThe symbol
outThe output symbol whose outputs are the direct children.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolGetInternals ( SymbolHandle  symbol,
SymbolHandle out 
)

Get a symbol that contains all the internals.

Parameters
symbolThe symbol
outThe output symbol whose outputs are all the internals.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolGetNumOutputs ( SymbolHandle  symbol,
nn_uint output_count 
)

Supply number of outputs of the symbol.

Parameters
symbolthe symbol
output_countnumber of outputs
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolGetOutput ( SymbolHandle  symbol,
nn_uint  index,
SymbolHandle out 
)

Get index-th outputs of the symbol.

Parameters
symbolThe symbol
indexthe Index of the output.
outThe output symbol whose outputs are the index-th symbol.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolListAttrs ( SymbolHandle  symbol,
int  recursive_option,
nn_uint out_size,
const char ***  out 
)

Get all attributes from symbol, including all descendents.

Parameters
symbolthe source symbol
recursive_option0 for recursive, 1 for shallow.
out_sizeThe number of output attributes
out2*out_size strings representing key value pairs.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolListInputNames ( SymbolHandle  symbol,
int  option,
nn_uint out_size,
const char ***  out_str_array 
)

List input names in the symbol.

Parameters
symbolthe symbol
optionThe option to list the inputs option=0 means list all arguments. option=1 means list arguments that are readed only by the graph. option=2 means list arguments that are mutated by the graph.
out_sizeoutput size
out_str_arraypointer to hold the output string array
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolListInputVariables ( SymbolHandle  symbol,
int  option,
nn_uint out_size,
SymbolHandle **  out_sym_array 
)

List inputs variables in the symbol.

Parameters
symbolthe symbol
optionThe option to list the inputs option=0 means list all arguments. option=1 means list arguments that are readed only by the graph. option=2 means list arguments that are mutated by the graph.
out_sizeoutput size
out_sym_arraythe output array.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolListOutputNames ( SymbolHandle  symbol,
nn_uint out_size,
const char ***  out_str_array 
)

List returns names in the symbol.

Parameters
symbolthe symbol
out_sizeoutput size
out_str_arraypointer to hold the output string array
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolPrint ( SymbolHandle  symbol,
const char **  out_str 
)

Print the content of symbol, used for debug.

Parameters
symbolthe symbol
out_strpointer to hold the output string of the printing.
Returns
0 when success, -1 when failure happens
NNVM_DLL int NNSymbolSetAttrs ( SymbolHandle  symbol,
nn_uint  num_param,
const char **  keys,
const char **  values 
)

Set string attribute from symbol. NOTE: Setting attribute to a symbol can affect the semantics(mutable/immutable) of symbolic graph.

Safe recommendaton: use immutable graph

  • Only allow set attributes during creation of new symbol as optional parameter

Mutable graph (be careful about the semantics):

  • Allow set attr at any point.
  • Mutating an attribute of some common node of two graphs can cause confusion from user.
Parameters
symbolthe source symbol
num_paramNumber of parameters to set.
keysThe keys of the attribute
valuesThe value to be set
Returns
0 when success, -1 when failure happens