[C API] add in C API for symbolic (#3)

Author: tqchen

nnvm/Makefile

@@ -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))
@@ -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

nnvm/include/nnvm/c_api.h

@@ -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_

nnvm/include/nnvm/op.h

@@ -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,
@@ -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;
 }
@@ -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;
 }

nnvm/include/nnvm/symbolic.h

@@ -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 */
@@ -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.
    */
@@ -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);
   /*!
@@ -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

nnvm/src/c_api/c_api_common.h

@@ -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_