diff options
| -rw-r--r-- | indra/llcommon/CMakeLists.txt | 8 | ||||
| -rw-r--r-- | indra/llcommon/classic_callback.cpp | 16 | ||||
| -rw-r--r-- | indra/llcommon/classic_callback.h | 292 | ||||
| -rw-r--r-- | indra/llcommon/tests/classic_callback_test.cpp | 150 |
4 files changed, 463 insertions, 3 deletions
diff --git a/indra/llcommon/CMakeLists.txt b/indra/llcommon/CMakeLists.txt index 040b0eb23d..abe2a92539 100644 --- a/indra/llcommon/CMakeLists.txt +++ b/indra/llcommon/CMakeLists.txt @@ -125,6 +125,7 @@ set(llcommon_SOURCE_FILES set(llcommon_HEADER_FILES CMakeLists.txt + classic_callback.h ctype_workaround.h fix_macros.h indra_constants.h @@ -325,16 +326,17 @@ if (LL_TESTS) ${BOOST_CONTEXT_LIBRARY} ${BOOST_THREAD_LIBRARY} ${BOOST_SYSTEM_LIBRARY}) - LL_ADD_INTEGRATION_TEST(commonmisc "" "${test_libs}") LL_ADD_INTEGRATION_TEST(bitpack "" "${test_libs}") + LL_ADD_INTEGRATION_TEST(classic_callback "" "${test_libs}") + LL_ADD_INTEGRATION_TEST(commonmisc "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llbase64 "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llcond "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lldate "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lldeadmantimer "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lldependencies "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llerror "" "${test_libs}") - LL_ADD_INTEGRATION_TEST(lleventdispatcher "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lleventcoro "" "${test_libs}") + LL_ADD_INTEGRATION_TEST(lleventdispatcher "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lleventfilter "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llframetimer "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llheteromap "" "${test_libs}") @@ -352,8 +354,8 @@ if (LL_TESTS) LL_ADD_INTEGRATION_TEST(llstring "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lltrace "" "${test_libs}") LL_ADD_INTEGRATION_TEST(lltreeiterators "" "${test_libs}") - LL_ADD_INTEGRATION_TEST(lluri "" "${test_libs}") LL_ADD_INTEGRATION_TEST(llunits "" "${test_libs}") + LL_ADD_INTEGRATION_TEST(lluri "" "${test_libs}") LL_ADD_INTEGRATION_TEST(stringize "" "${test_libs}") ## llexception_test.cpp isn't a regression test, and doesn't need to be run diff --git a/indra/llcommon/classic_callback.cpp b/indra/llcommon/classic_callback.cpp new file mode 100644 index 0000000000..5674e0a44d --- /dev/null +++ b/indra/llcommon/classic_callback.cpp @@ -0,0 +1,16 @@ +/** + * @file classic_callback.cpp + * @author Nat Goodspeed + * @date 2021-09-23 + * @brief Implementation for classic_callback. + * + * $LicenseInfo:firstyear=2021&license=viewerlgpl$ + * Copyright (c) 2021, Linden Research, Inc. + * $/LicenseInfo$ + */ + +namespace { + +const char dummy[] = "cpp file required to build test program"; + +} // anonymous namespace diff --git a/indra/llcommon/classic_callback.h b/indra/llcommon/classic_callback.h new file mode 100644 index 0000000000..76ff9c2339 --- /dev/null +++ b/indra/llcommon/classic_callback.h @@ -0,0 +1,292 @@ +/** + * @file classic_callback.h + * @author Nat Goodspeed + * @date 2016-06-21 + * @brief ClassicCallback and HeapClassicCallback + * + * This header file addresses the problem of passing a method on a C++ object + * to an API that requires a classic-C function pointer. Typically such a + * callback API accepts a void* pointer along with the function pointer, and + * the function pointer signature accepts a void* parameter. The API passes + * the caller's pointer value into the callback function so it can find its + * data. In C++, there are a few ways to deal with this case: + * + * - Use a static method with correct signature. If you don't need access to a + * specific instance, that works fine. + * - Store the object statically (or store a static pointer to a non-static + * instance). As long as you only care about one instance, that works, but + * starts to get a little icky. As soon as there's more than one pertinent + * instance, fight valiantly against the temptation to stuff the instance + * pointer into a static pointer variable "just for a moment." + * - Code a static trampoline callback function that accepts the void* user + * data pointer, casts it to the appropriate class type and calls the actual + * method on that class. + * + * ClassicCallback encapsulates the last. You need only construct a + * ClassicCallback instance somewhere that will survive until the callback is + * called, binding the target C++ callable. You then call its get_callback() + * and get_userdata() methods to pass an appropriate classic-C function + * pointer and void* user data pointer, respectively, to the old-style + * callback API. get_callback() synthesizes a static trampoline function + * that casts the user data pointer and calls the bound C++ callable. + * + * $LicenseInfo:firstyear=2016&license=viewerlgpl$ + * Copyright (c) 2016, Linden Research, Inc. + * $/LicenseInfo$ + */ + +#if ! defined(LL_CLASSIC_CALLBACK_H) +#define LL_CLASSIC_CALLBACK_H + +#include <tuple> +#include <type_traits> // std::is_same + +/***************************************************************************** +* Helpers +*****************************************************************************/ + +// find a type in a parameter pack: http://stackoverflow.com/q/17844867/5533635 +// usage: index_of<0, sought_t, PackName...>::value +template <int idx, typename sought, typename candidate, typename ...rest> +struct index_of +{ + static constexpr int const value = + std::is_same<sought, candidate>::value ? + idx : index_of<idx + 1, sought, rest...>::value; +}; + +// recursion tail +template <int idx, typename sought, typename candidate> +struct index_of<idx, sought, candidate> +{ + static constexpr int const value = + std::is_same<sought, candidate>::value ? idx : -1; +}; + +/***************************************************************************** +* ClassicCallback +*****************************************************************************/ +/** + * Instantiate ClassicCallback in whatever storage will persist long enough + * for the callback to be called. It holds a modern C++ callable, providing a + * static function pointer and a USERDATA (default void*) capable of being + * passed through a classic-C callback API. When the static function is called + * with that USERDATA pointer, ClassicCallback forwards the call to the bound + * C++ callable. + * + * Usage: + * @code + * // callback signature required by the API of interest + * typedef void (*callback_t)(int, const char*, void*, double); + * // old-style API that accepts a classic-C callback function pointer + * void oldAPI(callback_t callback, void* userdata); + * // but I want to pass a lambda that references data local to my function! + * // (We don't need to name the void* parameter in the C++ callable; + * // ClassicCallback already used it to locate the lambda instance.) + * auto ccb{ + * makeClassicCallback<callback_t>( + * [=](int n, const char* s, void*, double f){ ... }) }; + * oldAPI(ccb.get_callback(), ccb.get_userdata()); + * // If the passed callback is called before oldAPI() returns, we can now + * // safely destroy ccb. If the callback might be called later, consider + * // HeapClassicCallback instead. + * @endcode + * + * If you have a callable object in hand, and you want to pass that to + * ClassicCallback, you may either consume it by passing std::move(object), or + * explicitly specify a reference to that object type as the CALLABLE template + * parameter: + * @code + * CallableObject obj; + * ClassicCallback<callback_t, void*, CallableObject&> ccb{obj}; + * @endcode + */ +// CALLABLE should either be deduced, e.g. by makeClassicCallback(), or +// specified explicitly. Its default type is meaningless, coded only so we can +// provide a useful default for USERDATA. +template <typename SIGNATURE, typename USERDATA=void*, typename CALLABLE=void(*)()> +class ClassicCallback +{ + typedef ClassicCallback<SIGNATURE, USERDATA, CALLABLE> self_t; + +public: + /// ClassicCallback binds any modern C++ callable. + ClassicCallback(CALLABLE&& callable): + mCallable(std::forward<CALLABLE>(callable)) + {} + + /** + * ClassicCallback must not itself be copied or moved! Once you've passed + * get_userdata() to some API, this object MUST remain at that address. + */ + // However, we can't yet count on C++17 Class Template Argument Deduction, + // which means makeClassicCallback() is still useful, which means we MUST + // be able to return one to construct into caller's instance (move ctor). + // Possible defense: bool 'referenced' data member set by get_userdata(), + // with an llassert_always(! referenced) check in the move constructor. + ClassicCallback(ClassicCallback const&) = delete; + ClassicCallback(ClassicCallback&&) = default; // delete; + ClassicCallback& operator=(ClassicCallback const&) = delete; + ClassicCallback& operator=(ClassicCallback&&) = delete; + + /// Call get_callback() to get the necessary function pointer. + SIGNATURE get_callback() const + { + // This declaration is where the compiler instantiates the correct + // signature for the call() function template. + SIGNATURE callback = call; + return callback; + } + + /// Call get_userdata() to get the opaque USERDATA pointer to pass + /// through the classic-C callback API. + USERDATA get_userdata() const + { + // The USERDATA userdata is of course a pointer to this object. + return static_cast<USERDATA>(const_cast<self_t*>(this)); + } + +protected: + /** + * This call() method accepts one or more callback arguments. It assumes + * the first USERDATA parameter is the userdata. + */ + // Note that we're not literally using C++ perfect forwarding here -- it + // doesn't work to specify (Args&&... args). But that's okay because we're + // dealing with a classic-C callback! It's not going to pass any move-only + // types. + template <typename... Args> + static auto call(Args... args) + { + auto userdata = extract_userdata(std::forward<Args>(args)...); + // cast the userdata param to 'this' and call mCallable + return static_cast<self_t*>(userdata)-> + mCallable(std::forward<Args>(args)...); + } + + template <typename... Args> + static USERDATA extract_userdata(Args... args) + { + // Search for the first void* parameter type, then extract that pointer. + // extract value from parameter pack: http://stackoverflow.com/a/24710433/5533635 + return std::get<index_of<0, void*, Args...>::value>(std::forward_as_tuple(args...)); + } + + CALLABLE mCallable; +}; + +/** + * Usage: + * @code + * auto ccb{ makeClassicCallback<classic_callback_signature>(actual_callback) }; + * @endcode + */ +template <typename SIGNATURE, typename USERDATA=void*, typename CALLABLE=void(*)()> +auto makeClassicCallback(CALLABLE&& callable) +{ + return std::move(ClassicCallback<SIGNATURE, USERDATA, CALLABLE> + (std::forward<CALLABLE>(callable))); +} + +/***************************************************************************** +* HeapClassicCallback +*****************************************************************************/ +/** + * HeapClassicCallback is like ClassicCallback, with this exception: it MUST + * be allocated on the heap because, once the callback has been called, it + * deletes itself. This addresses the problem of a callback whose lifespan + * must persist beyond the scope in which the callback API is engaged -- but + * naturally this callback must be called exactly ONCE. + * + * Usage: + * @code + * // callback signature required by the API of interest + * typedef void (*callback_t)(int, const char*, void*, double); + * // here's the old-style API + * void oldAPI(callback_t callback, void* userdata); + * // want to call someObjPtr->method() when oldAPI() fires the callback, + * // sometime in the future after the enclosing function has returned + * auto ccb{ + * makeHeapClassicCallback<callback_t>( + * [someObjPtr](int n, const char* s, void*, double f) + * { someObjPtr->method(); }) }; + * oldAPI(ccb.get_callback(), ccb.get_userdata()); + * // We don't need a smart pointer for ccb, because it will be deleted once + * // oldAPI() calls the bound lambda. HeapClassicCallback is for when the + * // callback will be called exactly once. If the classic API might call the + * // passed callback more than once -- or might never call it at all -- + * // manually construct a ClassicCallback on the heap and manage its lifespan + * // explicitly. + * @endcode + */ +template <typename SIGNATURE, typename USERDATA=void*, typename CALLABLE=void(*)()> +class HeapClassicCallback: public ClassicCallback<SIGNATURE, USERDATA, CALLABLE> +{ + typedef ClassicCallback<SIGNATURE, USERDATA, CALLABLE> super; + typedef HeapClassicCallback<SIGNATURE, USERDATA, CALLABLE> self_t; + + // This destructor is intentionally private to prevent allocation anywhere + // but the heap. (The Design and Evolution of C++, section 11.4.2: Control + // of Allocation) + ~HeapClassicCallback() {} + +public: + HeapClassicCallback(CALLABLE&& callable): + super(std::forward<CALLABLE>(callable)) + {} + + // makeHeapClassicCallback() only needs to return a pointer -- not an + // instance -- so we can lock down our move constructor too. + HeapClassicCallback(HeapClassicCallback&&) = delete; + + /// Replicate get_callback() from the base class because we must + /// instantiate OUR call() function template. + SIGNATURE get_callback() const + { + // This declaration is where the compiler instantiates the correct + // signature for the call() function template. + SIGNATURE callback = call; + return callback; + } + + /// Replicate get_userdata() from the base class because our call() + /// method must be able to reconstitute a pointer to this subclass. + USERDATA get_userdata() const + { + // The USERDATA userdata is of course a pointer to this object. + return static_cast<const USERDATA>(const_cast<self_t*>(this)); + } + +private: + // call() uses a helper class to delete the HeapClassicCallback when done, + // for two reasons. Most importantly, this deletes even if the callback + // throws an exception. But also, call() must directly return the callback + // result for return-type deduction. + struct Destroyer + { + Destroyer(self_t* p): mPtr(p) {} + ~Destroyer() { delete mPtr; } + + self_t* mPtr; + }; + + template <typename... Args> + static auto call(Args... args) + { + // extract userdata at this level too + USERDATA userdata = super::extract_userdata(std::forward<Args>(args)...); + // arrange to delete it when we leave by whatever means + Destroyer destroy(static_cast<self_t*>(userdata)); + + return super::call(std::forward<Args>(args)...); + } +}; + +template <typename SIGNATURE, typename USERDATA=void*, typename CALLABLE=void(*)()> +auto makeHeapClassicCallback(CALLABLE&& callable) +{ + return new HeapClassicCallback<SIGNATURE, USERDATA, CALLABLE> + (std::forward<CALLABLE>(callable)); +} + +#endif /* ! defined(LL_CLASSIC_CALLBACK_H) */ diff --git a/indra/llcommon/tests/classic_callback_test.cpp b/indra/llcommon/tests/classic_callback_test.cpp new file mode 100644 index 0000000000..232532b1c1 --- /dev/null +++ b/indra/llcommon/tests/classic_callback_test.cpp @@ -0,0 +1,150 @@ +/** + * @file classic_callback_test.cpp + * @author Nat Goodspeed + * @date 2021-09-22 + * @brief Test ClassicCallback and HeapClassicCallback. + * + * $LicenseInfo:firstyear=2021&license=viewerlgpl$ + * Copyright (c) 2021, Linden Research, Inc. + * $/LicenseInfo$ + */ + +// Precompiled header +#include "linden_common.h" +// associated header +#include "classic_callback.h" +// STL headers +#include <iostream> +#include <string> +// std headers +// external library headers +// other Linden headers +#include "../test/lltut.h" + +/***************************************************************************** +* example callback accepting only (void* userdata) +*****************************************************************************/ +// callback_t is part of the specification of someAPI() +typedef void (*callback_t)(const char*, void*); +void someAPI(callback_t callback, void* userdata) +{ + callback("called", userdata); +} + +// C++ callable I want as the actual callback +struct MyCallback +{ + void operator()(const char* msg, void*) + { + mMsg = msg; + } + + void callback_with_extra(const std::string& extra, const char* msg) + { + mMsg = extra + ' ' + msg; + } + + std::string mMsg; +}; + +// a function for which I want to bind other data +void callback_with_extra(const std::string& extra, void*) +{ + std::cout << "callback_with_extra('" << extra << "', *)\n"; +} + +/***************************************************************************** +* example callback accepting several params, and void* userdata isn't first +*****************************************************************************/ +typedef std::string (*complex_callback)(int, const char*, void*, double); +std::string otherAPI(complex_callback callback, void* userdata) +{ + return callback(17, "hello world", userdata, 3.0); +} + +// struct into which we can capture complex_callback params +static struct Data +{ + void set(int i, const char* s, double f) + { + mi = i; + ms = s; + mf = f; + } + + void clear() { set(0, "", 0.0); } + + int mi; + std::string ms; + double mf; +} sData; + +// C++ callable I want to pass +struct OtherCallback +{ + std::string operator()(int num, const char* str, void*, double approx) + { + sData.set(num, str, approx); + return "hello back!"; + } +}; + +/***************************************************************************** +* TUT +*****************************************************************************/ +namespace tut +{ + struct classic_callback_data + { + }; + typedef test_group<classic_callback_data> classic_callback_group; + typedef classic_callback_group::object object; + classic_callback_group classic_callbackgrp("classic_callback"); + + template<> template<> + void object::test<1>() + { + set_test_name("ClassicCallback"); + // engage someAPI(MyCallback()) + auto ccb{ makeClassicCallback<callback_t>(MyCallback()) }; + someAPI(ccb.get_callback(), ccb.get_userdata()); + // Unfortunately, with the side effect confined to the bound + // MyCallback instance, that call was invisible. Bind a reference to a + // named instance by specifying a ref type. + MyCallback mcb; + ClassicCallback<callback_t, void*, MyCallback&> ccb2(mcb); + someAPI(ccb2.get_callback(), ccb2.get_userdata()); + ensure_equals("failed to call through ClassicCallback", mcb.mMsg, "called"); + + // try with HeapClassicCallback + mcb.mMsg.clear(); + auto hcbp{ makeHeapClassicCallback<callback_t>(mcb) }; + someAPI(hcbp->get_callback(), hcbp->get_userdata()); + ensure_equals("failed to call through HeapClassicCallback", mcb.mMsg, "called"); + + // lambda + // The tricky thing here is that a lambda is an unspecified type, so + // you can't declare a ClassicCallback<signature, void*, that type>. + mcb.mMsg.clear(); + auto xcb( + makeClassicCallback<callback_t>( + [&mcb](const char* msg, void*) + { mcb.callback_with_extra("extra", msg); })); + someAPI(xcb.get_callback(), xcb.get_userdata()); + ensure_equals("failed to call lambda", mcb.mMsg, "extra called"); + + // engage otherAPI(OtherCallback()) + OtherCallback ocb; + // Instead of specifying a reference type for the bound CALLBACK, as + // with ccb2 above, you can alternatively move the callable object + // into the ClassicCallback (of course AFTER any other reference). + // That's why OtherCallback uses external data for its observable side + // effect. + auto occb{ makeClassicCallback<complex_callback>(std::move(ocb)) }; + std::string result{ otherAPI(occb.get_callback(), occb.get_userdata()) }; + ensure_equals("failed to return callback result", result, "hello back!"); + ensure_equals("failed to set int", sData.mi, 17); + ensure_equals("failed to set string", sData.ms, "hello world"); + ensure_equals("failed to set double", sData.mf, 3.0); + } +} // namespace tut |