Skip to content

Commit

Permalink
[C API] add in C API for symbolic (#3)
Browse files Browse the repository at this point in the history
  • Loading branch information
tqchen committed May 29, 2018
1 parent 93534ec commit 39dfff8
Show file tree
Hide file tree
Showing 8 changed files with 544 additions and 22 deletions.
8 changes: 4 additions & 4 deletions nnvm/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ export CFLAGS = -std=c++11 -Wall -O3 -msse2 -Wno-unknown-pragmas -funroll-loop
# specify tensor path
.PHONY: clean all test lint doc

all: lib/libnngraph.so lib/libnngraph.a cli_test
all: lib/libnnvm.so lib/libnnvm.a cli_test

SRC = $(wildcard src/*.cc src/*/*.cc example/*.cc)
ALL_OBJ = $(patsubst src/%.cc, build/%.o, $(SRC))
Expand All @@ -20,19 +20,19 @@ build/%.o: src/%.cc
$(CXX) $(CFLAGS) -MM -MT build/$*.o $< >build/$*.d
$(CXX) -c $(CFLAGS) -c $< -o $@

lib/libnngraph.so: $(ALL_DEP)
lib/libnnvm.so: $(ALL_DEP)
@mkdir -p $(@D)
$(CXX) $(CFLAGS) -shared -o $@ $(filter %.o %.a, $^) $(LDFLAGS)

lib/libnngraph.a: $(ALL_DEP)
lib/libnnvm.a: $(ALL_DEP)
@mkdir -p $(@D)
ar crv $@ $(filter %.o, $?)

cli_test: $(ALL_DEP) build/test_main.o
$(CXX) $(CFLAGS) -o $@ $(filter %.o %.a, $^) $(LDFLAGS)

lint:
python2 dmlc-core/scripts/lint.py nngraph cpp include src
python2 dmlc-core/scripts/lint.py nnvm cpp include src

doc:
doxygen docs/Doxyfile
Expand Down
219 changes: 219 additions & 0 deletions nnvm/include/nnvm/c_api.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
/*!
* Copyright (c) 2016 by Contributors
* \file c_api.h
* \brief C API of NNVM symbolic construction and pass.
* Enables construction and transformation of Graph
* in any other host languages.
*/
#ifndef NNVM_C_API_H_
#define NNVM_C_API_H_

#ifdef __cplusplus
#define NNVM_EXTERN_C extern "C"
#endif

/*! \brief NNVM_DLL prefix for windows */
#ifdef _WIN32
#ifdef NNVM_EXPORTS
#define NNVM_DLL NNVM_EXTERN_C __declspec(dllexport)
#else
#define NNVM_DLL NNVM_EXTERN_C __declspec(dllimport)
#endif
#else
#define NNVM_DLL NNVM_EXTERN_C
#endif

/*! \brief manually define unsigned int */
typedef unsigned int nn_uint;

/*! \brief handle to a function that takes param and creates symbol */
typedef void *AtomicSymbolCreator;
/*! \brief handle to a symbol that can be bind as operator */
typedef void *SymbolHandle;
/*! \brief handle to a AtomicSymbol */
typedef void *AtomicSymbolHandle;

/*!
* \brief return str message of the last error
* all function in this file will return 0 when success
* and -1 when an error occured,
* NNGetLastError can be called to retrieve the error
*
* this function is threadsafe and can be called by different thread
* \return error info
*/
NNVM_DLL const char *NNGetLastError();

/*!
* \brief list all the available AtomicSymbolEntry
* \param out_size the size of returned array
* \param out_array the output AtomicSymbolCreator array
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolListAtomicSymbolCreators(nn_uint *out_size,
AtomicSymbolCreator **out_array);
/*!
* \brief Get the detailed information about atomic symbol.
* \param creator the AtomicSymbolCreator.
* \param name The returned name of the creator.
* \param description The returned description of the symbol.
* \param num_doc_args Number of arguments that contain documents.
* \param arg_names Name of the arguments of doc args
* \param arg_type_infos Type informations about the arguments.
* \param arg_descriptions Description information about the arguments.
* \param return_type Return type of the function, if any.
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolGetAtomicSymbolInfo(AtomicSymbolCreator creator,
const char **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 = NULL);
/*!
* \brief Create an AtomicSymbol functor.
* \param creator the AtomicSymbolCreator
* \param num_param the number of parameters
* \param keys the keys to the params
* \param vals the vals of the params
* \param out pointer to the created symbol handle
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolCreateAtomicSymbol(AtomicSymbolCreator creator,
nn_uint num_param,
const char **keys,
const char **vals,
SymbolHandle *out);
/*!
* \brief Create a Variable Symbol.
* \param name name of the variable
* \param out pointer to the created symbol handle
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolCreateVariable(const char *name, SymbolHandle *out);
/*!
* \brief Create a Symbol by grouping list of symbols together
* \param num_symbols number of symbols to be grouped
* \param symbols array of symbol handles
* \param out pointer to the created symbol handle
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolCreateGroup(nn_uint num_symbols,
SymbolHandle *symbols,
SymbolHandle *out);
/*!
* \brief Free the symbol handle.
* \param symbol the symbol
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolFree(SymbolHandle symbol);
/*!
* \brief Copy the symbol to another handle
* \param symbol the source symbol
* \param out used to hold the result of copy
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolCopy(SymbolHandle symbol, SymbolHandle *out);
/*!
* \brief Print the content of symbol, used for debug.
* \param symbol the symbol
* \param out_str pointer to hold the output string of the printing.
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolPrint(SymbolHandle symbol, const char **out_str);

/*!
* \brief 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.
*
* \param symbol the source symbol
* \param num_param Number of parameters to set.
* \param keys The keys of the attribute
* \param values The value to be set
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolSetAttrs(SymbolHandle symbol,
nn_uint num_param,
const char** keys,
const char** values);
/*!
* \brief Get all attributes from symbol, including all descendents.
* \param symbol the source symbol
* \param recursive_option 0 for recursive, 1 for shallow.
* \param out_size The number of output attributes
* \param out 2*out_size strings representing key value pairs.
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolListAttrs(SymbolHandle symbol,
int recursive_option,
nn_uint *out_size,
const char*** out);
/*!
* \brief List arguments in the symbol.
* \param symbol the symbol
* \param out_size output size
* \param out_str_array pointer to hold the output string array
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolListArguments(SymbolHandle symbol,
nn_uint *out_size,
const char ***out_str_array);
/*!
* \brief List returns in the symbol.
* \param symbol the symbol
* \param out_size output size
* \param out_str_array pointer to hold the output string array
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolListOutputs(SymbolHandle symbol,
nn_uint *out_size,
const char ***out_str_array);
/*!
* \brief Get a symbol that contains all the internals.
* \param symbol The symbol
* \param out The output symbol whose outputs are all the internals.
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolGetInternals(SymbolHandle symbol,
SymbolHandle *out);
/*!
* \brief Get index-th outputs of the symbol.
* \param symbol The symbol
* \param index the Index of the output.
* \param out The output symbol whose outputs are the index-th symbol.
* \return 0 when success, -1 when failure happens
*/
NNVM_DLL int NNSymbolGetOutput(SymbolHandle symbol,
nn_uint index,
SymbolHandle *out);

/*!
* \brief Compose the symbol on other symbols.
*
* This function will change the sym hanlde.
* To achieve function apply behavior, copy the symbol first
* before apply.
*
* \param sym the symbol to apply
* \param name the name of symbol
* \param num_args number of arguments
* \param keys the key of keyword args (optional)
* \param args arguments to sym
* \return 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);

#endif // NNVM_C_API_H_
9 changes: 6 additions & 3 deletions nnvm/include/nnvm/op.h
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,10 @@ class Op {
public:
/*! \brief name of the operator */
std::string name;
/*! \brief detailed description of the operator */
/*!
* \brief detailed description of the operator
* This can be used to generate docstring automatically for the operator.
*/
std::string description;
/*!
* \brief number of inputs to the operator,
Expand Down Expand Up @@ -339,7 +342,7 @@ inline Op& Op::set_num_inputs(uint32_t n) { // NOLINT(*)
return *this;
}

inline Op& Op::set_num_inputs(uint32_t (*fn)(const NodeAttrs&)) { // NOLINT(*)
inline Op& Op::set_num_inputs(uint32_t (*fn)(const NodeAttrs& attr)) { // NOLINT(*)
this->get_num_inputs = fn;
return *this;
}
Expand All @@ -349,7 +352,7 @@ inline Op& Op::set_num_outputs(uint32_t n) { // NOLINT(*)
return *this;
}

inline Op& Op::set_num_outputs(uint32_t (*fn)(const NodeAttrs&)) { // NOLINT(*)
inline Op& Op::set_num_outputs(uint32_t (*fn)(const NodeAttrs& attr)) { // NOLINT(*)
this->get_num_outputs = fn;
return *this;
}
Expand Down
18 changes: 8 additions & 10 deletions nnvm/include/nnvm/symbolic.h
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ class Symbol {
/*! \brief option passed to ListAttr */
enum ListAttrOption {
/*! \brief recursively list all attributes */
kRecursive,
kRecursive = 0,
/*! \brief only list attributes in current node */
kShallow
kShallow = 1
};

/*! \brief output entries contained in the symbol */
Expand Down Expand Up @@ -69,7 +69,7 @@ class Symbol {
*
* The rest of the symbols will remain the same name.
*
* \param positional arguments
* \param args positional arguments
* \param kwargs keyword arguments for the symbol
* \param name name of returned symbol.
*/
Expand Down Expand Up @@ -108,8 +108,7 @@ class Symbol {
*
* This function mutate the node's symbol and is not recommended.
*
* \param key the key of the attribute
* \param value the value of the attribute.
* \param attrs The attributes to set.
*/
void SetAttrs(const std::vector<std::pair<std::string, std::string> >& attrs);
/*!
Expand All @@ -119,16 +118,15 @@ class Symbol {
* The name of symbol will be pre-pended to each key.
* \return The created attribute.
*/
std::unordered_map<std::string, std::string> ListAttr(ListAttrOption option) const;
std::unordered_map<std::string, std::string> ListAttrs(ListAttrOption option) const;
/*!
* \brief create symbolic functor(AtomicSymbol) by given operator and attributes.
* \param op_name The name of the operator.
* \param op The operator.
* \param attrs The additional attributes.
*
* \return Symbol that can be used to call compose further.
*/
static Symbol CreateFunctor(const std::string& op_name,
const std::unordered_map<std::string, std::string>& attrs);
static Symbol CreateFunctor(const Op* op,
std::unordered_map<std::string, std::string>&& attrs);
/*!
* \brief create variable symbol node
* \param name name of the variable
Expand Down
59 changes: 59 additions & 0 deletions nnvm/src/c_api/c_api_common.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
/*!
* Copyright (c) 2016 by Contributors
* \file c_api_error.h
* \brief Common fields of all C APIs
*/
#ifndef NNVM_C_API_C_API_COMMON_H_
#define NNVM_C_API_C_API_COMMON_H_

#include <dmlc/base.h>
#include <dmlc/logging.h>
#include <dmlc/thread_local.h>
#include <nnvm/c_api.h>
#include <vector>
#include <string>

/*! \brief macro to guard beginning and end section of all functions */
#define API_BEGIN() try {
/*! \brief every function starts with API_BEGIN();
and finishes with API_END() or API_END_HANDLE_ERROR */
#define API_END() } catch(dmlc::Error &_except_) { return NNAPIHandleException(_except_); } return 0; // NOLINT(*)
/*!
* \brief every function starts with API_BEGIN();
* and finishes with API_END() or API_END_HANDLE_ERROR
* The finally clause contains procedure to cleanup states when an error happens.
*/
#define API_END_HANDLE_ERROR(Finalize) } catch(dmlc::Error &_except_) { Finalize; return NNAPIHandleException(_except_); } return 0; // NOLINT(*)


/*! \brief entry to to easily hold returning information */
struct NNAPIThreadLocalEntry {
/*! \brief result holder for returning string */
std::string ret_str;
/*! \brief result holder for returning strings */
std::vector<std::string> ret_vec_str;
/*! \brief result holder for returning string pointers */
std::vector<const char *> ret_vec_charp;
/*! \brief result holder for returning handles */
std::vector<void *> ret_handles;
};

/*! \brief Thread local store that can be used to hold return values. */
typedef dmlc::ThreadLocalStore<NNAPIThreadLocalEntry> NNAPIThreadLocalStore;

/*!
* \brief Set the last error message needed by C API
* \param msg The error message to set.
*/
void NNAPISetLastError(const char* msg);
/*!
* \brief handle exception throwed out
* \param e the exception
* \return the return value of API after exception is handled
*/
inline int NNAPIHandleException(const dmlc::Error &e) {
NNAPISetLastError(e.what());
return -1;
}

#endif // NNVM_C_API_C_API_COMMON_H_
Loading

0 comments on commit 39dfff8

Please sign in to comment.