Function Extension Interface

Macros
#define	BEGIN_FUNCTION_REGISTRATION
#define	REGISTER_FUNCTION(function, ...)
#define	REGISTER_NAMED_FUNCTION(name, function, ...)
#define	REGISTER_DOCSTRING(function, docstring)
#define	END_FUNCTION_REGISTRATION

Detailed Description

The Function Extension Interface provides a collection of macros that automate the process of exporting a function to Python. The macros are located in sdk/toolkit_function_macros.hpp .

For detailed usage descriptions, see page_turicreate_extension_interface .

Example:

#include <string>
#include <model_server/lib/toolkit_function_macros.hpp>
using namespace turi;

std::string demo_to_string(int in) {
  return std::to_string(in);
}

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(demo_to_string, "in");
END_FUNCTION_REGISTRATION

Macro Definition Documentation

BEGIN_FUNCTION_REGISTRATION

#define BEGIN_FUNCTION_REGISTRATION

Value:

__attribute__((visibility("default")))                  \
      std::vector<::turi::toolkit_function_specification> \
      get_toolkit_function_registration() {               \
     std::vector<::turi::toolkit_function_specification> specs;

Begins a toolkit registration block.

See also

END_FUNCTION_REGISTRATION

REGISTER_FUNCTION

The basic usage is:

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(my_function, inargname1, inargname2 ...)
REGISTER_FUNCTION(my_function2, inargname1, ...)
END_FUNCTION_REGISTRATION

Definition at line 61 of file toolkit_function_macros.hpp.

END_FUNCTION_REGISTRATION

#define END_FUNCTION_REGISTRATION

Value:

return specs; \
   }

Ends a toolkit registration block.

See also

BEGIN_FUNCTION_REGISTRATION.

REGISTER_FUNCTION_FUNCTION

The basic usage is:

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(my_function, inargname1, inargname2 ...)
REGISTER_FUNCTION(my_function2, inargname1, ...)
END_FUNCTION_REGISTRATION

Definition at line 173 of file toolkit_function_macros.hpp.

REGISTER_DOCSTRING

#define REGISTER_DOCSTRING	(		function,
			docstring
	)

Value:

for (auto& i: specs) { \
    if (i.description.count("_raw_fn_pointer_") &&  \
        i.description.at("_raw_fn_pointer_") == reinterpret_cast<size_t>(function)) { \
      i.description["documentation"] = docstring; \
    } \
  }

Sets a docstring on the function. If not provided, a default docstring describing the input arguments will be used. Must be called only after the function is registered. i.e. the matching REGISTER_FUNCTION must appear before, and it must be called with exactly the same function.

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(demo_add_one, "in");
REGISTER_DOCSTRING(demo_add_one, "Adds one to an integer/float")
REGISTER_DOCSTRING(demo_to_string, "Converts an arbitrary value to a string")
END_FUNCTION_REGISTRATION

Definition at line 149 of file toolkit_function_macros.hpp.

REGISTER_FUNCTION

#define REGISTER_FUNCTION	(		function,
			...
	)

Value:

specs.push_back(toolkit_function_wrapper_impl::make_spec_indirect(function, #function, \
                                                                      ##__VA_ARGS__));

Registers a function to make it callable from Python.

See also

BEGIN_FUNCTION_REGISTRATION

END_FUNCTION_REGISTRATION

Registers a function with no arguments.

REGISTER_FUNCTION(function)

Registers a function with 3 input arguments. The first input argument shall be named "a", the second named "b" and the 3rd named "c"

REGISTER_FUNCTION(function, "a", "b", "c")

Example:

std::string demo_to_string(flexible_type in) {
  return std::string(in);
}

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(demo_to_string, "in");
END_FUNCTION_REGISTRATION

Namespaces are permitted. For instance:

namespace example {
std::string demo_to_string(flexible_type in) {
  return std::string(in);
}
}

BEGIN_FUNCTION_REGISTRATION
REGISTER_FUNCTION(example::demo_to_string, "in");
END_FUNCTION_REGISTRATION

Both will be published as "demo_to_string"; the namespacing is ignored.

The return value of the function will be returned to Python. The function can return void. If the function fails, it should throw an exception which will be forward back to Python as RuntimeError.

Definition at line 114 of file toolkit_function_macros.hpp.

REGISTER_NAMED_FUNCTION

#define REGISTER_NAMED_FUNCTION	(		name,
			function,
			...
	)

Value:

specs.push_back(toolkit_function_wrapper_impl::make_spec_indirect(function, name, \
                                                                      ##__VA_ARGS__));

Register a function, assigning it a different name than the name of the function.

std::string demo_to_string(flexible_type in) {
  return std::string(in);
}

BEGIN_FUNCTION_REGISTRATION
REGISTER_NAMED_FUNCTION("module._demo_to_string", demo_to_string, "in");
END_FUNCTION_REGISTRATION

Definition at line 131 of file toolkit_function_macros.hpp.