From 2fea995f332071c85e390305585d6c050f15b94b Mon Sep 17 00:00:00 2001 From: Antony Polukhin Date: Fri, 21 Nov 2014 18:58:07 +0300 Subject: [PATCH] Deprecated import_function* and import_variable* methods and updated the docs and tests --- README.md | 13 +++++---- doc/Jamfile.v2 | 4 +-- doc/faq.qbk | 2 +- doc/getting_started.qbk | 4 +-- doc/revisionhistory.qbk | 2 ++ doc/tutorial.qbk | 10 +++---- example/getting_started.cpp | 4 +-- example/tutorial1/tutorial1.cpp | 4 +-- example/tutorial2/tutorial2.cpp | 4 +-- example/tutorial3/tutorial3.cpp | 4 +-- example/tutorial6/tutorial6.cpp | 4 +-- example/tutorial8/refcounting_api.hpp | 4 +-- include/boost/dll/import.hpp | 38 ++++++++++++------------- include/boost/dll/import_function.hpp | 33 ++++++++++----------- include/boost/dll/import_variable.hpp | 36 ++++++++++++----------- test/not_a_function.cpp | 2 +- test/shared_library_get_symbol_test.cpp | 12 ++++---- 17 files changed, 94 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index b293dc2..ab0d8dc 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,16 @@ Library for comfortable work with DLL and DSO. #include ... -auto cpp11_func = dll::import_function_alias( - path_to_shared_library, "cpp11_function_alias_name" -); +auto cpp11_func = dll::import_alias( + path_to_shared_library, "cpp11_function_alias_name" + ); +std::string s = cpp11_func(0); -boost::function c_func - = boost::dll::import_function( + +boost::function c_func = boost::dll::import( path_to_shared_library, "c_func_name" ); - +int i = c_func(1); ``` ### Installation diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index d61ba8e..315731a 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -62,8 +62,8 @@ doxygen autodoc_shared_library_refcountable : [ glob ../include/boost/dll/import.hpp - ../include/boost/dll/import_function.hpp - ../include/boost/dll/import_variable.hpp +# ../include/boost/dll/import_function.hpp +# ../include/boost/dll/import_variable.hpp ] : $(doxygen_params) diff --git a/doc/faq.qbk b/doc/faq.qbk index ab6b0f8..7687203 100644 --- a/doc/faq.qbk +++ b/doc/faq.qbk @@ -35,7 +35,7 @@ to `library_info` class. [pre ] -* [*Question:] What if I specify wrong type in `shared_library::get` or `import_function`? +* [*Question:] What if I specify wrong type in `shared_library::get` or `import`? * [*Answer:] Usually you'll end up with `Segmentation Fault`. However it is safe to make types more strict, for example making `const int` from an `int` will not harm. diff --git a/doc/getting_started.qbk b/doc/getting_started.qbk index 9bdaf78..5762a58 100644 --- a/doc/getting_started.qbk +++ b/doc/getting_started.qbk @@ -26,7 +26,7 @@ using namespace boost; [ [ [getting_started_exports_c_function] ] [ [getting_started_imports_c_function] ] - [ [funcref boost::dll::import_symbol import_symbol(...) ] ] + [ [funcref boost::dll::import import(...) ] ] ][ [ [getting_started_exports_cpp_function] ] [ [getting_started_imports_cpp_function] ] @@ -34,7 +34,7 @@ using namespace boost; ][ [ [getting_started_exports_c_variable] ] [ [getting_started_imports_c_variable] ] - [ [funcref boost::dll::import_symbol import_symbol(...) ] ] + [ [funcref boost::dll::import import(...) ] ] ][ [ [getting_started_exports_cpp_variable] ] [ [getting_started_imports_cpp_variable] ] diff --git a/doc/revisionhistory.qbk b/doc/revisionhistory.qbk index 661214e..4de5615 100644 --- a/doc/revisionhistory.qbk +++ b/doc/revisionhistory.qbk @@ -11,6 +11,8 @@ * Removed `shared_library::load_self()` * Renamed `shared_library::path()` to `shared_library::location()` +* `import_function*` and `import_variable*` methods were moved to `explicit_api` namespace +and *will be removed* in next release (or moved to the `detail` namespace, which is almost the same) * *TODO:* * improve load_mode::append_decorations (make it work with executables, take care of files starting on lib) * rename `shared_library::search_symbol()` to `shared_library::exists()`/`shared_library::count()` diff --git a/doc/tutorial.qbk b/doc/tutorial.qbk index 669d536..be3c701 100644 --- a/doc/tutorial.qbk +++ b/doc/tutorial.qbk @@ -28,7 +28,7 @@ Now let's make a DLL/DSO library that will holds implementation of plugin interf [import ../example/tutorial1/my_plugin_sum.cpp] [plugcpp_my_plugin_sum] -Simple application that loads plugin using the [funcref boost::dll::import_variable_alias] +Simple application that loads plugin using the [funcref boost::dll::import_alias] and [enumref boost::dll::load_mode::type append_decorations]: [import ../example/tutorial1/tutorial1.cpp] @@ -72,7 +72,7 @@ using [macroref BOOST_DLL_ALIAS]. [import ../example/tutorial2/tutorial2.cpp] [callplugcpp_tutorial2] -In that application we have imported the factory method using [funcref boost::dll::import_function_alias]. +In that application we have imported the factory method using [funcref boost::dll::import_alias]. [caution Be careful: `creator` variable holds a reference to the loaded shared library. If this variable goes out of scope or will be reset, then the *DLL/DSO will be unloaded* and any attempt to @@ -316,9 +316,9 @@ __to_top [section Advanced library reference counting] -As noted in documentation to the [funcref boost::dll::import_function] and [funcref boost::dll::import_variable] -variables and functions returned from those functions holds a reference to the shared library. However nested objects and -objects that are returned by `import_*` functions do not hold a reference to the shared library. There's no way to solve +As noted in documentation to the [funcref boost::dll::import] +variables and functions returned from those functions hold a reference to the shared library. However nested objects and +objects that are returned by `import*` functions do not hold a reference to the shared library. There's no way to solve this issue on the Boost.DLL library level, but you can take care of this problem by your own. Here's an example how this could be done. diff --git a/example/getting_started.cpp b/example/getting_started.cpp index e2f9be6..eab5985 100644 --- a/example/getting_started.cpp +++ b/example/getting_started.cpp @@ -18,7 +18,7 @@ int test_main(int argc, char* argv[]) { filesystem::path path_to_shared_library = shared_lib_path(argv[1], L"getting_started_library"); //[getting_started_imports_c_function - function c_func = dll::import_symbol( + function c_func = dll::import( path_to_shared_library, "c_func_name" ); //] @@ -28,7 +28,7 @@ int test_main(int argc, char* argv[]) { //[getting_started_imports_c_variable - shared_ptr c_var = dll::import_symbol( + shared_ptr c_var = dll::import( path_to_shared_library, "c_variable_name" ); //] diff --git a/example/tutorial1/tutorial1.cpp b/example/tutorial1/tutorial1.cpp index 68f2f27..9064cef 100644 --- a/example/tutorial1/tutorial1.cpp +++ b/example/tutorial1/tutorial1.cpp @@ -7,7 +7,7 @@ #include "../shared_lib_path.hpp" // contains BJAM_LIBRARY_DECORATIONS macro to workaround --layout=X //[callplugcpp_tutorial1 -#include // for import_variable_alias +#include // for import_alias #include #include "../tutorial_common/plugin_api.hpp" @@ -21,7 +21,7 @@ int main(int argc, char* argv[]) { boost::shared_ptr plugin; // variable to hold a pointer to plugin variable std::cout << "Loading the plugin" << std::endl; - plugin = dll::import_variable_alias( // type of imported symbol is located between `<` and `>` + plugin = dll::import_alias( // type of imported symbol is located between `<` and `>` lib_path / "my_plugin_sum"/*<-*/ BJAM_LIBRARY_DECORATIONS /*->*/, // path to the library and library name "plugin", // name of the symbol to import dll::load_mode::append_decorations // makes `libmy_plugin_sum.so` or `my_plugin_sum.dll` from `my_plugin_sum` diff --git a/example/tutorial2/tutorial2.cpp b/example/tutorial2/tutorial2.cpp index 8d7e741..dde0b8e 100644 --- a/example/tutorial2/tutorial2.cpp +++ b/example/tutorial2/tutorial2.cpp @@ -7,7 +7,7 @@ #include "../shared_lib_path.hpp" // contains BJAM_LIBRARY_DECORATIONS macro to workaround --layout=X //[callplugcpp_tutorial2 -#include // for import_function_alias +#include // for import_alias #include #include "../tutorial_common/plugin_api.hpp" @@ -22,7 +22,7 @@ int main(int argc, char* argv[]) { typedef boost::shared_ptr (pluginapi_create_t)(); boost::function creator; - creator = boost::dll::import_function_alias( // type of imported symbol must be explicitly specified + creator = boost::dll::import_alias( // type of imported symbol must be explicitly specified shared_library_path, // path to library "create_plugin", // symbol to import dll::load_mode::append_decorations // do append extensions and prefixes diff --git a/example/tutorial3/tutorial3.cpp b/example/tutorial3/tutorial3.cpp index 5a53124..9996dab 100644 --- a/example/tutorial3/tutorial3.cpp +++ b/example/tutorial3/tutorial3.cpp @@ -7,7 +7,7 @@ #include "../shared_lib_path.hpp" // contains BJAM_LIBRARY_DECORATIONS macro to workaround --layout=X //[callplugcpp_tutorial3 -#include // for import_function_alias +#include // for import_alias #include #include #include "../tutorial_common/plugin_api.hpp" @@ -29,7 +29,7 @@ std::size_t search_for_symbols(const std::vector& plugi // library has symbol, importing... typedef boost::shared_ptr (pluginapi_create_t)(); boost::function creator - = dll::import_function_alias(lib, "create_plugin"); + = dll::import_alias(lib, "create_plugin"); std::cout << "Matching plugin name: " << creator()->name() << std::endl; ++ plugins_found; diff --git a/example/tutorial6/tutorial6.cpp b/example/tutorial6/tutorial6.cpp index f227fd6..9fefc49 100644 --- a/example/tutorial6/tutorial6.cpp +++ b/example/tutorial6/tutorial6.cpp @@ -7,7 +7,7 @@ #include "../shared_lib_path.hpp" //[callplugcpp_tutorial6 -#include +#include #include typedef boost::function callback_t; @@ -23,7 +23,7 @@ int main(int argc, char* argv[]) { // loading library and getting a function from it boost::function on_unload - = boost::dll::import_function_alias( + = boost::dll::import_alias( shared_library_path, "on_unload" ); diff --git a/example/tutorial8/refcounting_api.hpp b/example/tutorial8/refcounting_api.hpp index 90878c2..13d078b 100644 --- a/example/tutorial8/refcounting_api.hpp +++ b/example/tutorial8/refcounting_api.hpp @@ -45,12 +45,12 @@ inline boost::shared_ptr bind(my_refcounting_api* ptr) { //] //[plugcpp_get_plugin_refcounting -#include +#include inline boost::shared_ptr get_plugin( boost::filesystem::path path, boost::string_ref func_name) { typedef my_refcounting_api*(func_t)(); - boost::function f = boost::dll::import_function_alias( + boost::function f = boost::dll::import_alias( path, func_name, boost::dll::load_mode::append_decorations // will be ignored for executable diff --git a/include/boost/dll/import.hpp b/include/boost/dll/import.hpp index f911f0c..08304a0 100644 --- a/include/boost/dll/import.hpp +++ b/include/boost/dll/import.hpp @@ -36,18 +36,18 @@ namespace boost { namespace dll { * * \b Examples: * \code -* boost::function f = import_symbol( +* boost::function f = import( * boost::make_shared("test_lib.so"), * "integer_func_name" * ); * \endcode * * \code -* boost::function f = import_symbol("test_lib.so", "integer_func_name"); +* boost::function f = import("test_lib.so", "integer_func_name"); * \endcode * * \code -* boost::shared_ptr i = import_symbol("test_lib.so", "integer_name"); +* boost::shared_ptr i = import("test_lib.so", "integer_name"); * \endcode * * \tparam T Type of the symbol that we are going to import. Must be explicitly specified. @@ -63,33 +63,33 @@ namespace boost { namespace dll { */ template typename boost::disable_if, boost::function >::type -import_symbol(const boost::filesystem::path& lib, boost::string_ref func_name, +import(const boost::filesystem::path& lib, boost::string_ref func_name, load_mode::type mode = load_mode::default_mode) { - return boost::dll::import_function(lib, func_name, mode); + return boost::dll::explicit_api::import_function(lib, func_name, mode); } -//! \overload boost::dll::import_symbol(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) +//! \overload boost::dll::import(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template typename boost::disable_if, boost::function >::type -import_symbol(const boost::shared_ptr& lib, boost::string_ref func_name) { - return boost::dll::import_function(lib, func_name); +import(const boost::shared_ptr& lib, boost::string_ref func_name) { + return boost::dll::explicit_api::import_function(lib, func_name); } -//! \overload boost::dll::import_symbol(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) +//! \overload boost::dll::import(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template typename boost::enable_if, boost::shared_ptr >::type -import_symbol(const boost::filesystem::path& lib, boost::string_ref variable_name, +import(const boost::filesystem::path& lib, boost::string_ref variable_name, load_mode::type mode = load_mode::default_mode) { - return boost::dll::import_variable(lib, variable_name, mode); + return boost::dll::explicit_api::import_variable(lib, variable_name, mode); } -//! \overload boost::dll::import_symbol(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) +//! \overload boost::dll::import(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template typename boost::enable_if, boost::shared_ptr >::type -import_symbol(const boost::shared_ptr& lib, boost::string_ref variable_name) { - return boost::dll::import_variable(lib, variable_name); +import(const boost::shared_ptr& lib, boost::string_ref variable_name) { + return boost::dll::explicit_api::import_variable(lib, variable_name); } @@ -103,7 +103,7 @@ import_symbol(const boost::shared_ptr& lib, boost::string_ref va * This call will succeed if call to \forcedlink{shared_library}`::search_symbol(boost::string_ref )` * function with the same symbol name returned `true`. * -* For importing symbols by \b non \b alias names use \forcedlink{import_symbol} method. +* For importing symbols by \b non \b alias names use \forcedlink{import} method. * * \b Examples: * \code @@ -140,14 +140,14 @@ typename boost::disable_if, boost::function >::type import_alias(const boost::filesystem::path& lib, boost::string_ref func_name, load_mode::type mode = load_mode::default_mode) { - return boost::dll::import_function_alias(lib, func_name, mode); + return boost::dll::explicit_api::import_function_alias(lib, func_name, mode); } //! \overload boost::dll::import_alias(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template typename boost::disable_if, boost::function >::type import_alias(const boost::shared_ptr& lib, boost::string_ref func_name) { - return boost::dll::import_function_alias(lib, func_name); + return boost::dll::explicit_api::import_function_alias(lib, func_name); } //! \overload boost::dll::import_alias(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) @@ -156,14 +156,14 @@ typename boost::enable_if, boost::shared_ptr >::type import_alias(const boost::filesystem::path& lib, boost::string_ref variable_name, load_mode::type mode = load_mode::default_mode) { - return boost::dll::import_variable_alias(lib, variable_name, mode); + return boost::dll::explicit_api::import_variable_alias(lib, variable_name, mode); } //! \overload boost::dll::import_alias(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template typename boost::enable_if, boost::shared_ptr >::type import_alias(const boost::shared_ptr& lib, boost::string_ref variable_name) { - return boost::dll::import_variable_alias(lib, variable_name); + return boost::dll::explicit_api::import_variable_alias(lib, variable_name); } diff --git a/include/boost/dll/import_function.hpp b/include/boost/dll/import_function.hpp index 64f5e5a..ff7d5ab 100644 --- a/include/boost/dll/import_function.hpp +++ b/include/boost/dll/import_function.hpp @@ -42,6 +42,13 @@ namespace detail { }; } // namespace detail +namespace explicit_api { + +//! \overload boost::dll::import_function(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) +template +boost::function import_function(const boost::shared_ptr& lib, boost::string_ref func_name) { + return boost::dll::detail::refc_function(lib, &lib->get(func_name)); +} /*! * Returns boost::function that holds an imported function from the loaded library and refcounts usage @@ -81,20 +88,20 @@ template boost::function import_function(const boost::filesystem::path& lib,boost::string_ref func_name, load_mode::type mode = load_mode::default_mode) { - return import_function( - boost::make_shared(lib, mode), + return boost::dll::explicit_api::import_function( + boost::make_shared(lib, mode), func_name ); } -//! \overload boost::dll::import_function(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) + + +//! \overload boost::dll::import_function_alias(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) template -boost::function import_function(const boost::shared_ptr& lib, boost::string_ref func_name) { - return boost::dll::detail::refc_function(lib, &lib->get(func_name)); +boost::function import_function_alias(const boost::shared_ptr& lib, boost::string_ref func_name) { + return boost::dll::detail::refc_function(lib, lib->get(func_name)); } - - /*! * Imports function by it alias name and returns boost::function that holds the function * from the loaded library and refcounts usage of the loaded shared library. Library won't @@ -136,20 +143,14 @@ template boost::function import_function_alias(const boost::filesystem::path& lib, boost::string_ref func_name, load_mode::type mode = load_mode::default_mode) { - return import_function_alias( - boost::make_shared(lib, mode), + return boost::dll::explicit_api::import_function_alias( + boost::make_shared(lib, mode), func_name ); } -//! \overload boost::dll::import_function_alias(const boost::shared_ptr& lib, boost::string_ref func_name, load_mode::type mode) -template -boost::function import_function_alias(const boost::shared_ptr& lib, boost::string_ref func_name) { - return boost::dll::detail::refc_function(lib, lib->get(func_name)); -} - -}} // boost::dll +}}} // boost::dll::explicit_api #endif // BOOST_DLL_IMPORT_FUNCTION_HPP diff --git a/include/boost/dll/import_variable.hpp b/include/boost/dll/import_variable.hpp index a472fd0..ea9530b 100644 --- a/include/boost/dll/import_variable.hpp +++ b/include/boost/dll/import_variable.hpp @@ -17,7 +17,7 @@ #endif /// \file boost/dll/import_variable.hpp -/// \brief Contains all the boost::dll::import_variable* reference counting +/// \brief Contains all the import_variable* reference counting /// functions that hold a shared pointer to the instance of /// boost::dll::shared_library. @@ -35,6 +35,15 @@ namespace detail { }; } // namespace detail +namespace explicit_api { + + +//! \overload boost::dll::import_variable(const boost::shared_ptr& lib, boost::string_ref variable_name, load_mode::type mode) +template +boost::shared_ptr import_variable(const boost::shared_ptr& lib, boost::string_ref variable_name) { + return boost::shared_ptr(&lib->get(variable_name), boost::dll::detail::ptr_holding_empty_deleter(lib)); +} + /*! * Returns boost::shared_ptr that holds an imported variable from the loaded library and refcounts usage * of the loaded shared library, so that it won't get unload until all copies of return value @@ -77,20 +86,20 @@ template boost::shared_ptr import_variable(const boost::filesystem::path& lib, boost::string_ref variable_name, load_mode::type mode = load_mode::default_mode) { - return import_variable( - boost::make_shared(lib, mode), + return boost::dll::explicit_api::import_variable( + boost::make_shared(lib, mode), variable_name ); } -//! \overload boost::dll::import_variable(const boost::shared_ptr& lib, boost::string_ref variable_name, load_mode::type mode) + + +//! \overload boost::dll::import_variable_alias(const boost::shared_ptr& lib, boost::string_ref variable_name, load_mode::type mode) template -boost::shared_ptr import_variable(const boost::shared_ptr& lib, boost::string_ref variable_name) { - return boost::shared_ptr(&lib->get(variable_name), boost::dll::detail::ptr_holding_empty_deleter(lib)); +boost::shared_ptr import_variable_alias(const boost::shared_ptr& lib, boost::string_ref variable_name) { + return boost::shared_ptr(lib->get(variable_name), boost::dll::detail::ptr_holding_empty_deleter(lib)); } - - /*! * Imports variable by it alias name and returns boost::shared_ptr that holds an imported * variable from the loaded library and refcounts usage of the loaded shared library. @@ -132,20 +141,15 @@ template boost::shared_ptr import_variable_alias(const boost::filesystem::path& lib, boost::string_ref variable_name, load_mode::type mode = load_mode::default_mode) { - return import_variable_alias( - boost::make_shared(lib, mode), + return boost::dll::explicit_api::import_variable_alias( + boost::make_shared(lib, mode), variable_name ); } -//! \overload boost::dll::import_variable_alias(const boost::shared_ptr& lib, boost::string_ref variable_name, load_mode::type mode) -template -boost::shared_ptr import_variable_alias(const boost::shared_ptr& lib, boost::string_ref variable_name) { - return boost::shared_ptr(lib->get(variable_name), boost::dll::detail::ptr_holding_empty_deleter(lib)); -} -}} // boost::dll +}}} // boost::dll::explicit_api #endif // BOOST_DLL_IMPORT_VARIABLE_HPP diff --git a/test/not_a_function.cpp b/test/not_a_function.cpp index 8e2a94b..3e4abfd 100644 --- a/test/not_a_function.cpp +++ b/test/not_a_function.cpp @@ -10,5 +10,5 @@ int main() { // Must be a compile time error - boost::dll::import_function("library name", "symbol name") + boost::dll::explicit_api::import_function("library name", "symbol name") } diff --git a/test/shared_library_get_symbol_test.cpp b/test/shared_library_get_symbol_test.cpp index 5ac8974..5db0b34 100644 --- a/test/shared_library_get_symbol_test.cpp +++ b/test/shared_library_get_symbol_test.cpp @@ -41,7 +41,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { { boost::function sz2 - = import_function(shared_library_path, "say_hello"); + = import(shared_library_path, "say_hello"); sz2(); sz2(); @@ -50,7 +50,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { { boost::function&)> sz - = import_function_alias&)>(shared_library_path, "foo_bar"); + = import_alias&)>(shared_library_path, "foo_bar"); BOOST_CHECK(sz(v) == 1000); } @@ -59,7 +59,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { boost::function f; { - boost::function f2 = import_function_alias(shared_library_path, "do_share"); + boost::function f2 = import_alias(shared_library_path, "do_share"); f = f2; } @@ -79,7 +79,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { } { - boost::shared_ptr i = import_variable(shared_library_path, "integer_g"); + boost::shared_ptr i = import(shared_library_path, "integer_g"); BOOST_CHECK(*i == 100); boost::shared_ptr i2; @@ -88,7 +88,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { } { - boost::shared_ptr i = import_variable(shared_library_path, "const_integer_g"); + boost::shared_ptr i = import(shared_library_path, "const_integer_g"); BOOST_CHECK(*i == 777); boost::shared_ptr i2 = i; @@ -97,7 +97,7 @@ void refcountable_test(boost::filesystem::path shared_library_path) { } { - boost::shared_ptr s = import_variable_alias(shared_library_path, "info"); + boost::shared_ptr s = import_alias(shared_library_path, "info"); BOOST_CHECK(*s == "I am a std::string from the test_library (Think of me as of 'Hello world'. Long 'Hello world')."); boost::shared_ptr s2;