c++-gtk-utils
|
00001 /* Copyright (C) 2008 to 2012 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the c++-gtk-utils 00020 sub-directory); if not, write to the Free Software Foundation, Inc., 00021 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00022 00023 However, it is not intended that the object code of a program whose 00024 source code instantiates a template from this file or uses macros or 00025 inline functions (of any length) should by reason only of that 00026 instantiation or use be subject to the restrictions of use in the GNU 00027 Lesser General Public License. With that in mind, the words "and 00028 macros, inline functions and instantiations of templates (of any 00029 length)" shall be treated as substituted for the words "and small 00030 macros and small inline functions (ten lines or less in length)" in 00031 the fourth paragraph of section 5 of that licence. This does not 00032 affect any other reason why object code may be subject to the 00033 restrictions in that licence (nor for the avoidance of doubt does it 00034 affect the application of section 2 of that licence to modifications 00035 of the source code in this file). 00036 00037 */ 00038 00039 #ifndef CGU_CALLBACK_H 00040 #define CGU_CALLBACK_H 00041 00042 /** 00043 * @file callback.h 00044 * @brief This file provides classes encapsulating callbacks. 00045 * 00046 * \#include <c++-gtk-utils/callback.h> 00047 * 00048 * These classes encapsulate callbacks (they are closures). They 00049 * comprise a generic callback creation and execution interface. 00050 * There is a basic Callback::Callback type, which is an entire 00051 * closure or 'thunk', where all the arguments are bound in the 00052 * constructor and is completely opaque. Callback::CallbackArg<T...> 00053 * is a class which takes unbound arguments of the template types when 00054 * the callback is dispatched, with any other arguments being bound at 00055 * construction time. (The opaque Callback::Callback type is in fact 00056 * just a typedef for Callback::CallbackArg<>: the two types are 00057 * interchangeable.) 00058 * 00059 * The classes can represent static and non-static member functions 00060 * and plain functions. In the case of a non-static member function, 00061 * the object whose member function the callback represents must 00062 * remain in existence until any invocations of the callback have 00063 * completed. The function referred to must be one of void return 00064 * type. A callback object can also be constructed from a 00065 * std::function object, provided that it is of void return type 00066 * (which would amongst other things enable, where necessary, the 00067 * binding of the referenced object of a non-static member function by 00068 * taking an internal copy of it using std::bind). 00069 * 00070 * They are particularly useful where a callback object may need to be 00071 * handed between threads. 00072 * 00073 * The classes can also be useful for general event passing when used 00074 * together with the Callback::post() functions, or as the data 00075 * argument of a call to g_signal_connect_data() in a case where a 00076 * better design arises when passing arguments known at connect time 00077 * by storing them in the callback object itself (say, where otherwise 00078 * you would pass a plain struct as the data argument). 00079 * 00080 * These classes are also used in the Emitter/EmitterArg classes in 00081 * emitter.h, which enable callbacks to be connected to an emitter and 00082 * provide for automatic disconnection where a class object whose 00083 * member a callback represents ceases to exist. 00084 * 00085 * @b The @b Callback::make() @b functions 00086 * 00087 * The templated helper Callback::make() functions make it trivial to 00088 * create a callback object of the correct type. The ordinary 00089 * Callback::make() functions (that is, those not taking a 00090 * std::function object) provide for a maximum of five bound arguments 00091 * to pass to the relevant function or class method, and an unlimited 00092 * number of unbound arguments, but unbound arguments must be the last 00093 * (trailing) arguments of the relevant function or method to be 00094 * called if there is a bound argument. Callback/CallbackArg classes 00095 * do not provide for a return value. If a result is wanted, users 00096 * should pass an unbound argument by reference or pointer (or pointer 00097 * to pointer). 00098 * 00099 * Although as mentioned above only five bound arguments are provided 00100 * for by callbacks constructed by the ordinary Callback::make() 00101 * functions, as any of those arguments can be a struct, any number of 00102 * arguments can be passed as members of a struct or a std::tuple. In 00103 * addition, a callback object can be constructed from a std::function 00104 * object, which can have any number of arguments bound to it, and in 00105 * any order (that is, unbound arguments may precede bound arguments). 00106 * 00107 * The Callback::make() functions not taking a std::function object do 00108 * a direct type mapping from the bound arguments of the function or 00109 * method represented by the callback object to the arguments stored 00110 * by the callback object. Bound value arguments of the relevant 00111 * function or method to be called are therefore stored by value in 00112 * the callback object. A bound argument can comprise a reference 00113 * argument (T& or const T&) if the template parameters of the 00114 * Callback::make() call are qualified by hand to avoid a type 00115 * mismatch: see under "Usage" below for further particulars, and if 00116 * the reference argument is non-const this allows the referenced 00117 * argument to be mutated. However as this would result in the 00118 * lifetime of the argument not being controlled by the callback 00119 * object (it would not keep its own copy), it will often be unsafe to 00120 * do so. (The documentation on Thread::JoinableHandle gives a usage 00121 * where where binding a reference argument would be safe.) 00122 * 00123 * From version 2.0.0-rc3, the library also provides 00124 * Callback::make_ref() functions, which force the callback object to 00125 * keep a copy of the value passed where a target function argument is 00126 * a const reference. It is therefore safe with const reference 00127 * arguments. No explicit type qualification is required by 00128 * Callback::make_ref(). In addition the Callback::make_ref() 00129 * functions provide for more efficient passing of class type bound 00130 * arguments (by l-value or r-value reference) than does 00131 * Callback::make(): see further below. 00132 * 00133 * @b The @b Callback::make_ref() @b functions 00134 * 00135 * In order to enable the widest variety of types to be accepted as 00136 * arguments (including reference arguments in those cases where it is 00137 * safe, and also string literals), as mentioned above when 00138 * constructing a callback object from other than a std::function 00139 * object, Callback::make() receives non-reference bound arguments by 00140 * value, and if unoptimised these may be copied up to two times, and 00141 * once more when the target function is dispatched. Where a bound 00142 * argument is a pointer or a fundamental type (an integral or 00143 * floating-point type), optimization by copy elision will reduce the 00144 * number of times argument copying takes place when constructing a 00145 * callback object to once, but the standard does not permit that with 00146 * class types where the constructor or destructor have side effects 00147 * or it cannot be ascertained whether they have side effects. 00148 * 00149 * Therefore, to cater for cases where a target function takes a class 00150 * type argument by const reference or value, from version 2.0.0-rc3 00151 * the Callback::make_ref() functions are provided. Unlike 00152 * Callback::make(), when constructing a callback for a target 00153 * function taking a const reference bound argument, 00154 * Callback::make_ref() will force the callback object to keep a copy 00155 * of the argument instead of a reference to that argument. This 00156 * makes the use of const reference arguments safe (at the cost of the 00157 * storing of that copy). It cannot be used with non-const 00158 * references. In addition Callback::make_ref() automatically chooses 00159 * the most efficient means of passing class type arguments for 00160 * storage by the callback object, that is by l-value reference or 00161 * r-value reference, as appropriate. 00162 * 00163 * In the case of a value argument, at callback dispatch time one 00164 * additional copy will be made in the normal way when the target 00165 * function is called, but in the case of a const reference argument 00166 * no such additional copy will be made. What all this means is that, 00167 * where bound arguments include a non-trivial class type, the most 00168 * efficient and exception safe strategy is usually: 00169 * 00170 * 1. If that class type has a rvalue constructor, to have the target 00171 * function take that type by const reference argument, and pass a 00172 * newly constructed object of that type to Callback::make_ref() as a 00173 * temporary (so that it is passed by r-value reference and stored in 00174 * the callback object without any copying at all), or 00175 * 00176 * 2. To construct the object of the class type on free store and held 00177 * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the 00178 * target function take it by const Cgu::SharedPtr&, const 00179 * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the 00180 * callback object using Callback::make_ref(). 00181 * 00182 * This flexibility of Callback::make_ref() has a downside: unlike 00183 * Callback::make(), Callback::make_ref() cannot resolve overloaded 00184 * functions by argument type. Where a function has two or more 00185 * overloads taking the same number of arguments, explicit 00186 * disambiguation by the user is required (see further below under 00187 * Overloaded Functions). 00188 * 00189 * Summary: If a callback object's bound arguments are all simple 00190 * fundamental types such as pointers (including C strings), integers 00191 * or floating points, use Callback::make(). Where bound arguments 00192 * include class types, use Callback::make_ref(). 00193 * 00194 * @b The @b Callback::make_val() @b functions 00195 * 00196 * The library also provides Callback::make_val() functions. These 00197 * are provided to retain code compatibility with version 1.2 of the 00198 * library. They were optimised for use where a target function takes 00199 * bound arguments of class type by value, but are now deprecated and 00200 * superseded by the automatic variable type mapping of 00201 * Callback::make_ref(). Callback::make_ref() should now be used 00202 * instead of Callback::make_val(). 00203 * 00204 * @b Constructing @b callbacks @b from @b std::function @b objects 00205 * 00206 * The Callback::make() factory functions can also construct a 00207 * callback object from a std::function object, which would enable a 00208 * callback to take more than 5 bound arguments, or to have a bound 00209 * argument which is passed after (or mixed with) unbound arguments, 00210 * or to have its own copy of the referenced object of a non-static 00211 * member function bound to it. 00212 * 00213 * However, the genericity of the binding of arguments implemented in 00214 * std::function and std::bind comes at a cost. Arguments bound to a 00215 * std::function object can be copied a significant number of times 00216 * (libstdc++ for example can copy class types four times when 00217 * constructing a std::function object and two more times when 00218 * executing the function, unless they have a r-value constructor, in 00219 * which case they are copied twice and once respectively with two and 00220 * one additional calls to the r-value constructor). Non-trivial 00221 * class types should therefore only be passed as bound arguments to 00222 * std::function objects by pointer or smart pointer. 00223 * 00224 * Note that the overload of Callback::make() for std::function 00225 * objects has a version taking a r-value reference for the lossless 00226 * passing through of temporaries to the callback object, and a 00227 * version taking a const reference for std::function objects which 00228 * are l-values. For std::function objects, Callback::make() and 00229 * Callback::make_ref() are all synonyms (the way arguments are dealt 00230 * with for std::function objects is determined by std::bind() and 00231 * std::ref()). 00232 * 00233 * @b The @b Callback::lambda() @b functions 00234 * 00235 * Callback objects for C++11 lambda functions can be constructed 00236 * using Callback::make() by passing the lambda object via a temporary 00237 * std::function object (see under Usage below for an example). 00238 * However, from version 2.0.9 the Callback::lambda() factory function 00239 * is provided enabling callbacks for C++11 lambda functions to be 00240 * constructed more directly. This is nice, as by using 00241 * Callback::lambda() a callback can, for example, be executed by a 00242 * glib main loop using Callback::post() with: 00243 * @code 00244 * using namespace Cgu; 00245 * post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup 00246 * @endcode 00247 * Further examples are given under Usage below. 00248 * 00249 * Using Callback::lambda() to construct a callback object from a 00250 * C++11 lambda function, rather than using Callback::make() with a 00251 * temporary std::function object, will also be more efficient, as 00252 * when executed it would normally avoid the additional virtual 00253 * function call that would arise with std::function. 00254 * 00255 * When using Callback::lambda(), the unbound argument types must be 00256 * specified explicitly (they cannot be deduced from the lambda 00257 * expression). 00258 * 00259 * Callback::lambda() can be used to construct a callback object from 00260 * any arbitrary callable object. It could therefore be used to 00261 * construct callback objects from plain function pointers where no 00262 * arguments are to be bound, and from std::function objects. 00263 * However, that is rarely useful as employing Callback::make() with 00264 * function pointers and std::function objects provides the benefit of 00265 * automatic type deduction of the arguments. One possible case where 00266 * Callback::lambda() might be useful with non-lambda callable objects 00267 * relates to another feature of Callback::lambda(), namely that the 00268 * callable object passed to it need not be of void return type. 00269 * However, if the callable object does return a value, that value is 00270 * discarded. If a result is wanted, an unbound reference or pointer 00271 * argument should be passed when the callback is executed, to which 00272 * the result can be assigned. 00273 * 00274 * If using lambda expressions with gcc, gcc-4.5 or greater is needed. 00275 * The header file callback.h can be included without error with 00276 * gcc-4.4, but callable objects cannot be constructed using C++11 00277 * lambda syntax. 00278 * 00279 * @b Functors 00280 * 00281 * If a functor class of void return type is required (say for passing 00282 * to a c++ algorithm or container, or for automatic lifetime 00283 * management of the Callback object), the Callback::Functor and 00284 * Callback::FunctorArg wrapper classes can be used. However, for 00285 * many c++ algorithms where anonymous functors created as temporaries 00286 * can be used, the std::ptr_fun(), std::mem_fn() and std::bind() 00287 * factory functions or a lambda function will be a more obvious 00288 * choice. Callback::Functor and Callback::FunctorArg are to be 00289 * preferred to std::function where value arguments are to be bound 00290 * (see above), unless something other than a void return type is 00291 * required. 00292 * 00293 * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the 00294 * same as Callback::Functor and Callback::FunctorArg classes, except 00295 * that objects of the safe version may be passed and copied between 00296 * threads and put in different containers in different threads (that 00297 * is, the reference count maintained with respect to the contained 00298 * callback object is thread-safe). They use a SharedLockPtr object 00299 * to hold the referenced callback object. 00300 * 00301 * @b Memory @b allocation 00302 * 00303 * If the library is installed using the 00304 * --with-glib-memory-slices-compat or 00305 * --with-glib-memory-slices-no-compat configuration options, any 00306 * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or 00307 * Callback::SafeFunctorArg objects constructed on free store (usually 00308 * they won't be) will be constructed in glib memory slices. A 00309 * contained Callback::Callback or Callback::CallbackArg object, which 00310 * will always be constructed on free store, will be constructed in 00311 * glib memory slices if the --with-glib-memory-slices-no-compat 00312 * configuration option is chosen. 00313 * 00314 * @b Usage 00315 * 00316 * For a class object my_obj of type MyClass, with a method void 00317 * MyClass::my_method(int, int, const char*), usage for a fully bound 00318 * callback or functor would be: 00319 * 00320 * @code 00321 * using namespace Cgu; 00322 * int arg1 = 1, arg2 = 5; 00323 * Callback::Callback* cb = 00324 * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n"); 00325 * cb->dispatch(); 00326 * delete cb; 00327 * 00328 * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")}; 00329 * f(); 00330 * @endcode 00331 * 00332 * Or for a partially bound callback or functor: 00333 * 00334 * @code 00335 * using namespace Cgu; 00336 * int arg1 = 1, arg2 = 5; 00337 * Callback::CallbackArg<int, const char*>* cb = 00338 * Callback::make(my_obj, &MyClass::my_method, arg1); 00339 * cb->dispatch(arg2, "Hello\n"); 00340 * delete cb; 00341 * 00342 * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)}; 00343 * f(arg2, "Hello\n"); 00344 * @endcode 00345 * 00346 * The syntax for the construction of a callback object representing a 00347 * static member function with a signature void MyClass::my_func(int, 00348 * const char*), or for a normal function, is similar to the 00349 * non-static member function case, except that the call to 00350 * Callback::make would comprise: 00351 * 00352 * @code 00353 * Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n"); 00354 * @endcode 00355 * (fully bound), or 00356 * @code 00357 * Callback::make(&MyClass::my_func, arg1); 00358 * @endcode 00359 * (partially bound), and so on. 00360 * 00361 * To bind to reference arguments, the call to Callback::make() must 00362 * be explicitly typed. For a class object my_obj of type MyClass, 00363 * with a method void MyClass::my_method(int&), usage for a fully 00364 * bound callback or functor would be: 00365 * 00366 * @code 00367 * int arg = 1; 00368 * Callback::Callback* cb = 00369 * Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg); 00370 * @endcode 00371 * 00372 * Note however the caveats above about binding to reference 00373 * arguments. 00374 * 00375 * No similar explicit typing is required by Callback::make_ref(). 00376 * Thus for a class object my_obj of type MyClass, with a method void 00377 * MyClass::my_method(int, const Something&), usage for a fully bound 00378 * callback or functor would be: 00379 * 00380 * @code 00381 * int arg1 = 1; 00382 * Something arg2; 00383 * Callback::Callback* cb = 00384 * Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2); 00385 * @endcode 00386 * 00387 * Usage for constructing a callback object from a std::function 00388 * object is as follows, for a class object my_obj of type MyClass, 00389 * with a method void MyClass::my_method(int, int, int, double, const 00390 * char*), where a value is to be bound to the second argument: 00391 * 00392 * @code 00393 * using namespace std::placeholders; // for _1, _2, _3 and _4 00394 * int arg = 1; 00395 * Callback::CallbackArg<int, int, double, const char*>* cb = 00396 * Callback::make(std::function<void(int, int, double, const char*)>{ 00397 * std::bind(std::mem_fn(&MyClass::my_method), &my_obj, 00398 * _1, arg, _2, _3, _4) 00399 * }); 00400 * cb->dispatch(5, 3, 10.2, "Hello\n"); 00401 * delete cb; 00402 * @endcode 00403 * 00404 * In this example, if the bound argument were a reference (that is, 00405 * the signature of MyClass::my_method were (int, int&, int, double, 00406 * const char*) and it were safe to do so (see above), it could be 00407 * bound with std::ref(), as in: 00408 * 00409 * @code 00410 * Callback::CallbackArg<int, int, double, const char*>* cb = 00411 * Callback::make(std::function<void(int, int, double, const char*)>{ 00412 * std::bind(std::mem_fn(&MyClass::my_method), &my_obj, 00413 * _1, std::ref(arg), _2, _3, _4) 00414 * }); 00415 * @endcode 00416 * 00417 * Lambda expressions can also be passed to callback objects via 00418 * std::function, and arguments can be bound with the [=] capture 00419 * expression, as in: 00420 * 00421 * @code 00422 * Callback::Callback* cb; 00423 * { 00424 * std::string s("Hello"); 00425 * cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}}); 00426 * } 00427 * cb->dispatch(); // 's' is now out of scope, but it has been copied by value to 00428 * // the lambda object and is now held by the callback object 00429 * delete cb; 00430 * @endcode 00431 * 00432 * However, from version 2.0.9, Callback::lambda() provides an easier 00433 * way of dealing with lambda expressions. The same code could be 00434 * implemented as: 00435 * 00436 * @code 00437 * Callback::Callback* cb; 00438 * { 00439 * std::string s("Hello"); 00440 * cb = Callback::lambda<>([=](){std::cout << s << std::endl;}); 00441 * } 00442 * cb->dispatch(); 00443 * delete cb; 00444 * @endcode 00445 * 00446 * With Callback::lambda(), the types of the unbound arguments must be 00447 * explicitly specified as they cannot be deduced. Unbound arguments 00448 * can comprise reference arguments. For example: 00449 * @code 00450 * int res; 00451 * auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;}); 00452 * cb->dispatch(2, 3, res); 00453 * std::cout << res << std::endl; 00454 * delete cb; 00455 * @endcode 00456 * 00457 * @b Overloaded @b functions 00458 * 00459 * Note that creating callbacks for overloaded functions can give rise 00460 * to an ambiguity when using Callback::make(), arising from the fact 00461 * that the callback object may have an unbound argument. For 00462 * example: 00463 * 00464 * @code 00465 * class MyClass { 00466 * ... 00467 * void add(int i); 00468 * void add(int i, int j); 00469 * void add(double d); 00470 * }; 00471 * MyClass obj; 00472 * using namespace Cgu; 00473 * Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok 00474 * Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0); // ok 00475 * Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1); // ambiguous - compilation failure 00476 * @endcode 00477 * 00478 * The third call to Callback::make() is ambiguous, as it could be 00479 * creating a callback for either the function MyClass::add(int) with 00480 * no unbound argument (that is, creating a Callback::Callback 00481 * object), or the function MyClass::add(int, int) with an unbound int 00482 * argument (that is, creating a Callback::CallbackArg<int> object). 00483 * This situation could be disambiguated by specifically stating the 00484 * type of the function which is to be chosen, namely, to instantiate 00485 * the callback in the third call with: 00486 * 00487 * @code 00488 * // either: 00489 * Callback::Callback* cb3 = 00490 * Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1); 00491 * // or: 00492 * Callback::CallbackArg<int>* cb3 = 00493 * Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1); 00494 * @endcode 00495 * 00496 * Callback::make_ref() is less capable than Callback::make() at 00497 * deducing template types. It cannot resolve overloaded functions by 00498 * examining the arguments passed to it. For example, take a class 00499 * MyClass as follows: 00500 * 00501 * @code 00502 * class MyClass { 00503 * ... 00504 * void add(int i, const double& d); 00505 * void add(const int& j, const int& k); 00506 * }; 00507 * @endcode 00508 * 00509 * Callback::make_ref() would require explicit disambiguation like 00510 * this: 00511 * 00512 * @code 00513 * Callback::Callback* cb1 = 00514 * Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2); 00515 * Callback::Callback* cb2 = 00516 * Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5); 00517 * @endcode 00518 * 00519 * Note also that, for CallbackArg objects created from std::function 00520 * objects, the std::function constructors and the std::mem_fn() and 00521 * std::bind() functions normally do not allow any function 00522 * overloading without explicit disambiguation. 00523 * 00524 * @b Posting @b of @b callbacks 00525 * 00526 * This file also provides Callback::post() functions which will 00527 * execute a callback in a glib main loop and can be used (amongst 00528 * other things) to pass an event from a worker thread to the main 00529 * program thread. In that respect, it provides an alternative to the 00530 * Notifier class. It is passed a pointer to a Callback::CallbackArg 00531 * object created with a call to Callback::make. 00532 * 00533 * To provide for thread-safe automatic disconnection of the callback 00534 * if the object whose method it represents is destroyed before the 00535 * callback executes in the main loop, include a Releaser as a public 00536 * member of that object and pass the Releaser object as the second 00537 * argument of Callback::post(). Note that for this to be race free, 00538 * the lifetime of the remote object whose method is to be invoked 00539 * must be determined by the thread to whose main loop the callback 00540 * has been attached. When the main loop begins invoking the 00541 * execution of the callback, the remote object must either wholly 00542 * exist (in which case the callback will be invoked) or have been 00543 * destroyed (in which case the callback will be ignored), and not be 00544 * in some transient half-state governed by another thread. 00545 * 00546 * Advantages as against Notifier: 00547 * 00548 * 1. If there are a lot of different events requiring callbacks to be 00549 * dispatched in the program from worker threads to the main 00550 * thread, this avoids having separate Notifier objects for each 00551 * event. 00552 * 00553 * 2. It is easier to pass arguments with varying values - they can be 00554 * passed as arguments to the Callback::make functions and no 00555 * special synchronisation is normally required (the call to 00556 * g_source_attach() invokes locking of the main loop which will 00557 * have the effect of ensuring memory visibility). With a Notifier 00558 * object it may be necessary to use an asynchronous queue to pass 00559 * variable values (or to bind a reference to the data, thus 00560 * normally requiring separate synchronisation). 00561 * 00562 * 3. Although the callback would normally be sent for execution by 00563 * the main program loop, and that is the default, it can be sent 00564 * for execution by any thread which has its own 00565 * GMainContext/GMainLoop objects. Thus callbacks can be passed 00566 * for execution between worker threads, or from the main program 00567 * thread to worker threads, as well as from worker threads to the 00568 * main program thread. 00569 * 00570 * Disadvantages as against Notifier: 00571 * 00572 * 1. Less efficient, as a new callback object has to be created on 00573 * freestore every time the callback is invoked, together with a 00574 * new Emitter object if a Releaser is used to track the callback. 00575 * 00576 * 2. Multiple callbacks relevant to a single event cannot be invoked 00577 * from a single call for the event - each callback has to be 00578 * separately dispatched. 00579 */ 00580 00581 /** 00582 * @namespace Cgu::Callback 00583 * @brief This namespace provides classes encapsulating callbacks. 00584 * 00585 * \#include <c++-gtk-utils/callback.h> 00586 * 00587 * These classes encapsulate callbacks (they are closures). They 00588 * comprise a generic callback creation and execution interface. 00589 * There is a basic Callback::Callback type, which is an entire 00590 * closure or 'thunk', where all the arguments are bound in the 00591 * constructor and is completely opaque. Callback::CallbackArg<T...> 00592 * is a class which takes unbound arguments of the template types when 00593 * the callback is dispatched, with any other arguments being bound at 00594 * construction time. (The opaque Callback::Callback type is in fact 00595 * just a typedef for Callback::CallbackArg<>: the two types are 00596 * interchangeable.) 00597 * 00598 * The classes can represent static and non-static member functions 00599 * and plain functions. In the case of a non-static member function, 00600 * the object whose member function the callback represents must 00601 * remain in existence until any invocations of the callback have 00602 * completed. The function referred to must be one of void return 00603 * type. A callback object can also be constructed from a 00604 * std::function object, provided that it is of void return type 00605 * (which would amongst other things enable, where necessary, the 00606 * binding of the referenced object of a non-static member function by 00607 * taking an internal copy of it using std::bind). 00608 * 00609 * They are particularly useful where a callback object may need to be 00610 * handed between threads. 00611 * 00612 * The classes can also be useful for general event passing when used 00613 * together with the Callback::post() functions, or as the data 00614 * argument of a call to g_signal_connect_data() in a case where a 00615 * better design arises when passing arguments known at connect time 00616 * by storing them in the callback object itself (say, where otherwise 00617 * you would pass a plain struct as the data argument). 00618 * 00619 * These classes are also used in the Emitter/EmitterArg classes in 00620 * emitter.h, which enable callbacks to be connected to an emitter and 00621 * provide for automatic disconnection where a class object whose 00622 * member a callback represents ceases to exist. 00623 * 00624 * @b The @b Callback::make() @b functions 00625 * 00626 * The templated helper Callback::make() functions make it trivial to 00627 * create a callback object of the correct type. The ordinary 00628 * Callback::make() functions (that is, those not taking a 00629 * std::function object) provide for a maximum of five bound arguments 00630 * to pass to the relevant function or class method, and an unlimited 00631 * number of unbound arguments, but unbound arguments must be the last 00632 * (trailing) arguments of the relevant function or method to be 00633 * called if there is a bound argument. Callback/CallbackArg classes 00634 * do not provide for a return value. If a result is wanted, users 00635 * should pass an unbound argument by reference or pointer (or pointer 00636 * to pointer). 00637 * 00638 * Although as mentioned above only five bound arguments are provided 00639 * for by callbacks constructed by the ordinary Callback::make() 00640 * functions, as any of those arguments can be a struct, any number of 00641 * arguments can be passed as members of a struct or a std::tuple. In 00642 * addition, a callback object can be constructed from a std::function 00643 * object, which can have any number of arguments bound to it, and in 00644 * any order (that is, unbound arguments may precede bound arguments). 00645 * 00646 * The Callback::make() functions not taking a std::function object do 00647 * a direct type mapping from the bound arguments of the function or 00648 * method represented by the callback object to the arguments stored 00649 * by the callback object. Bound value arguments of the relevant 00650 * function or method to be called are therefore stored by value in 00651 * the callback object. A bound argument can comprise a reference 00652 * argument (T& or const T&) if the template parameters of the 00653 * Callback::make() call are qualified by hand to avoid a type 00654 * mismatch: see under "Usage" below for further particulars, and if 00655 * the reference argument is non-const this allows the referenced 00656 * argument to be mutated. However as this would result in the 00657 * lifetime of the argument not being controlled by the callback 00658 * object (it would not keep its own copy), it will often be unsafe to 00659 * do so. (The documentation on Thread::JoinableHandle gives a usage 00660 * where where binding a reference argument would be safe.) 00661 * 00662 * From version 2.0.0-rc3, the library also provides 00663 * Callback::make_ref() functions, which force the callback object to 00664 * keep a copy of the value passed where a target function argument is 00665 * a const reference. It is therefore safe with const reference 00666 * arguments. No explicit type qualification is required by 00667 * Callback::make_ref(). In addition the Callback::make_ref() 00668 * functions provide for more efficient passing of class type bound 00669 * arguments (by l-value or r-value reference) than does 00670 * Callback::make(): see further below. 00671 * 00672 * @b The @b Callback::make_ref() @b functions 00673 * 00674 * In order to enable the widest variety of types to be accepted as 00675 * arguments (including reference arguments in those cases where it is 00676 * safe, and also string literals), as mentioned above when 00677 * constructing a callback object from other than a std::function 00678 * object, Callback::make() receives non-reference bound arguments by 00679 * value, and if unoptimised these may be copied up to two times, and 00680 * once more when the target function is dispatched. Where a bound 00681 * argument is a pointer or a fundamental type (an integral or 00682 * floating-point type), optimization by copy elision will reduce the 00683 * number of times argument copying takes place when constructing a 00684 * callback object to once, but the standard does not permit that with 00685 * class types where the constructor or destructor have side effects 00686 * or it cannot be ascertained whether they have side effects. 00687 * 00688 * Therefore, to cater for cases where a target function takes a class 00689 * type argument by const reference or value, from version 2.0.0-rc3 00690 * the Callback::make_ref() functions are provided. Unlike 00691 * Callback::make(), when constructing a callback for a target 00692 * function taking a const reference bound argument, 00693 * Callback::make_ref() will force the callback object to keep a copy 00694 * of the argument instead of a reference to that argument. This 00695 * makes the use of const reference arguments safe (at the cost of the 00696 * storing of that copy). It cannot be used with non-const 00697 * references. In addition Callback::make_ref() automatically chooses 00698 * the most efficient means of passing class type arguments for 00699 * storage by the callback object, that is by l-value reference or 00700 * r-value reference, as appropriate. 00701 * 00702 * In the case of a value argument, at callback dispatch time one 00703 * additional copy will be made in the normal way when the target 00704 * function is called, but in the case of a const reference argument 00705 * no such additional copy will be made. What all this means is that, 00706 * where bound arguments include a non-trivial class type, the most 00707 * efficient and exception safe strategy is usually: 00708 * 00709 * 1. If that class type has a rvalue constructor, to have the target 00710 * function take that type by const reference argument, and pass a 00711 * newly constructed object of that type to Callback::make_ref() as a 00712 * temporary (so that it is passed by r-value reference and stored in 00713 * the callback object without any copying at all), or 00714 * 00715 * 2. To construct the object of the class type on free store and held 00716 * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the 00717 * target function take it by const Cgu::SharedPtr&, const 00718 * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the 00719 * callback object using Callback::make_ref(). 00720 * 00721 * This flexibility of Callback::make_ref() has a downside: unlike 00722 * Callback::make(), Callback::make_ref() cannot resolve overloaded 00723 * functions by argument type. Where a function has two or more 00724 * overloads taking the same number of arguments, explicit 00725 * disambiguation by the user is required (see further below under 00726 * Overloaded Functions). 00727 * 00728 * Summary: If a callback object's bound arguments are all simple 00729 * fundamental types such as pointers (including C strings), integers 00730 * or floating points, use Callback::make(). Where bound arguments 00731 * include class types, use Callback::make_ref(). 00732 * 00733 * @b The @b Callback::make_val() @b functions 00734 * 00735 * The library also provides Callback::make_val() functions. These 00736 * are provided to retain code compatibility with version 1.2 of the 00737 * library. They were optimised for use where a target function takes 00738 * bound arguments of class type by value, but are now deprecated and 00739 * superseded by the automatic variable type mapping of 00740 * Callback::make_ref(). Callback::make_ref() should now be used 00741 * instead of Callback::make_val(). 00742 * 00743 * @b Constructing @b callbacks @b from @b std::function @b objects 00744 * 00745 * The Callback::make() factory functions can also construct a 00746 * callback object from a std::function object, which would enable a 00747 * callback to take more than 5 bound arguments, or to have a bound 00748 * argument which is passed after (or mixed with) unbound arguments, 00749 * or to have its own copy of the referenced object of a non-static 00750 * member function bound to it. 00751 * 00752 * However, the genericity of the binding of arguments implemented in 00753 * std::function and std::bind comes at a cost. Arguments bound to a 00754 * std::function object can be copied a significant number of times 00755 * (libstdc++ for example can copy class types four times when 00756 * constructing a std::function object and two more times when 00757 * executing the function, unless they have a r-value constructor, in 00758 * which case they are copied twice and once respectively with two and 00759 * one additional calls to the r-value constructor). Non-trivial 00760 * class types should therefore only be passed as bound arguments to 00761 * std::function objects by pointer or smart pointer. 00762 * 00763 * Note that the overload of Callback::make() for std::function 00764 * objects has a version taking a r-value reference for the lossless 00765 * passing through of temporaries to the callback object, and a 00766 * version taking a const reference for std::function objects which 00767 * are l-values. For std::function objects, Callback::make() and 00768 * Callback::make_ref() are all synonyms (the way arguments are dealt 00769 * with for std::function objects is determined by std::bind() and 00770 * std::ref()). 00771 * 00772 * @b The @b Callback::lambda() @b functions 00773 * 00774 * Callback objects for C++11 lambda functions can be constructed 00775 * using Callback::make() by passing the lambda object via a temporary 00776 * std::function object (see under Usage below for an example). 00777 * However, from version 2.0.9 the Callback::lambda() factory function 00778 * is provided enabling callbacks for C++11 lambda functions to be 00779 * constructed more directly. This is nice, as by using 00780 * Callback::lambda() a callback can, for example, be executed by a 00781 * glib main loop using Callback::post() with: 00782 * @code 00783 * using namespace Cgu; 00784 * post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup 00785 * @endcode 00786 * Further examples are given under Usage below. 00787 * 00788 * Using Callback::lambda() to construct a callback object from a 00789 * C++11 lambda function, rather than using Callback::make() with a 00790 * temporary std::function object, will also be more efficient, as 00791 * when executed it would normally avoid the additional virtual 00792 * function call that would arise with std::function. 00793 * 00794 * When using Callback::lambda(), the unbound argument types must be 00795 * specified explicitly (they cannot be deduced from the lambda 00796 * expression). 00797 * 00798 * Callback::lambda() can be used to construct a callback object from 00799 * any arbitrary callable object. It could therefore be used to 00800 * construct callback objects from plain function pointers where no 00801 * arguments are to be bound, and from std::function objects. 00802 * However, that is rarely useful as employing Callback::make() with 00803 * function pointers and std::function objects provides the benefit of 00804 * automatic type deduction of the arguments. One possible case where 00805 * Callback::lambda() might be useful with non-lambda callable objects 00806 * relates to another feature of Callback::lambda(), namely that the 00807 * callable object passed to it need not be of void return type. 00808 * However, if the callable object does return a value, that value is 00809 * discarded. If a result is wanted, an unbound reference or pointer 00810 * argument should be passed when the callback is executed, to which 00811 * the result can be assigned. 00812 * 00813 * If using lambda expressions with gcc, gcc-4.5 or greater is needed. 00814 * The header file callback.h can be included without error with 00815 * gcc-4.4, but callable objects cannot be constructed using C++11 00816 * lambda syntax. 00817 * 00818 * @b Functors 00819 * 00820 * If a functor class of void return type is required (say for passing 00821 * to a c++ algorithm or container, or for automatic lifetime 00822 * management of the Callback object), the Callback::Functor and 00823 * Callback::FunctorArg wrapper classes can be used. However, for 00824 * many c++ algorithms where anonymous functors created as temporaries 00825 * can be used, the std::ptr_fun(), std::mem_fn() and std::bind() 00826 * factory functions or a lambda function will be a more obvious 00827 * choice. Callback::Functor and Callback::FunctorArg are to be 00828 * preferred to std::function where value arguments are to be bound 00829 * (see above), unless something other than a void return type is 00830 * required. 00831 * 00832 * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the 00833 * same as Callback::Functor and Callback::FunctorArg classes, except 00834 * that objects of the safe version may be passed and copied between 00835 * threads and put in different containers in different threads (that 00836 * is, the reference count maintained with respect to the contained 00837 * callback object is thread-safe). They use a SharedLockPtr object 00838 * to hold the referenced callback object. 00839 * 00840 * @b Memory @b allocation 00841 * 00842 * If the library is installed using the 00843 * --with-glib-memory-slices-compat or 00844 * --with-glib-memory-slices-no-compat configuration options, any 00845 * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or 00846 * Callback::SafeFunctorArg objects constructed on free store (usually 00847 * they won't be) will be constructed in glib memory slices. A 00848 * contained Callback::Callback or Callback::CallbackArg object, which 00849 * will always be constructed on free store, will be constructed in 00850 * glib memory slices if the --with-glib-memory-slices-no-compat 00851 * configuration option is chosen. 00852 * 00853 * @b Usage 00854 * 00855 * For a class object my_obj of type MyClass, with a method void 00856 * MyClass::my_method(int, int, const char*), usage for a fully bound 00857 * callback or functor would be: 00858 * 00859 * @code 00860 * using namespace Cgu; 00861 * int arg1 = 1, arg2 = 5; 00862 * Callback::Callback* cb = 00863 * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n"); 00864 * cb->dispatch(); 00865 * delete cb; 00866 * 00867 * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")}; 00868 * f(); 00869 * @endcode 00870 * 00871 * Or for a partially bound callback or functor: 00872 * 00873 * @code 00874 * using namespace Cgu; 00875 * int arg1 = 1, arg2 = 5; 00876 * Callback::CallbackArg<int, const char*>* cb = 00877 * Callback::make(my_obj, &MyClass::my_method, arg1); 00878 * cb->dispatch(arg2, "Hello\n"); 00879 * delete cb; 00880 * 00881 * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)}; 00882 * f(arg2, "Hello\n"); 00883 * @endcode 00884 * 00885 * The syntax for the construction of a callback object representing a 00886 * static member function with a signature void MyClass::my_func(int, 00887 * const char*), or for a normal function, is similar to the 00888 * non-static member function case, except that the call to 00889 * Callback::make would comprise: 00890 * 00891 * @code 00892 * Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n"); 00893 * @endcode 00894 * (fully bound), or 00895 * @code 00896 * Callback::make(&MyClass::my_func, arg1); 00897 * @endcode 00898 * (partially bound), and so on. 00899 * 00900 * To bind to reference arguments, the call to Callback::make() must 00901 * be explicitly typed. For a class object my_obj of type MyClass, 00902 * with a method void MyClass::my_method(int&), usage for a fully 00903 * bound callback or functor would be: 00904 * 00905 * @code 00906 * int arg = 1; 00907 * Callback::Callback* cb = 00908 * Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg); 00909 * @endcode 00910 * 00911 * Note however the caveats above about binding to reference 00912 * arguments. 00913 * 00914 * No similar explicit typing is required by Callback::make_ref(). 00915 * Thus for a class object my_obj of type MyClass, with a method void 00916 * MyClass::my_method(int, const Something&), usage for a fully bound 00917 * callback or functor would be: 00918 * 00919 * @code 00920 * int arg1 = 1; 00921 * Something arg2; 00922 * Callback::Callback* cb = 00923 * Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2); 00924 * @endcode 00925 * 00926 * Usage for constructing a callback object from a std::function 00927 * object is as follows, for a class object my_obj of type MyClass, 00928 * with a method void MyClass::my_method(int, int, int, double, const 00929 * char*), where a value is to be bound to the second argument: 00930 * 00931 * @code 00932 * using namespace std::placeholders; // for _1, _2, _3 and _4 00933 * int arg = 1; 00934 * Callback::CallbackArg<int, int, double, const char*>* cb = 00935 * Callback::make(std::function<void(int, int, double, const char*)>{ 00936 * std::bind(std::mem_fn(&MyClass::my_method), &my_obj, 00937 * _1, arg, _2, _3, _4) 00938 * }); 00939 * cb->dispatch(5, 3, 10.2, "Hello\n"); 00940 * delete cb; 00941 * @endcode 00942 * 00943 * In this example, if the bound argument were a reference (that is, 00944 * the signature of MyClass::my_method were (int, int&, int, double, 00945 * const char*) and it were safe to do so (see above), it could be 00946 * bound with std::ref(), as in: 00947 * 00948 * @code 00949 * Callback::CallbackArg<int, int, double, const char*>* cb = 00950 * Callback::make(std::function<void(int, int, double, const char*)>{ 00951 * std::bind(std::mem_fn(&MyClass::my_method), &my_obj, 00952 * _1, std::ref(arg), _2, _3, _4) 00953 * }); 00954 * @endcode 00955 * 00956 * Lambda expressions can also be passed to callback objects via 00957 * std::function, and arguments can be bound with the [=] capture 00958 * expression, as in: 00959 * 00960 * @code 00961 * Callback::Callback* cb; 00962 * { 00963 * std::string s("Hello"); 00964 * cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}}); 00965 * } 00966 * cb->dispatch(); // 's' is now out of scope, but it has been copied by value to 00967 * // the lambda object and is now held by the callback object 00968 * delete cb; 00969 * @endcode 00970 * 00971 * However, from version 2.0.9, Callback::lambda() provides an easier 00972 * way of dealing with lambda expressions. The same code could be 00973 * implemented as: 00974 * 00975 * @code 00976 * Callback::Callback* cb; 00977 * { 00978 * std::string s("Hello"); 00979 * cb = Callback::lambda<>([=](){std::cout << s << std::endl;}); 00980 * } 00981 * cb->dispatch(); 00982 * delete cb; 00983 * @endcode 00984 * 00985 * With Callback::lambda(), the types of the unbound arguments must be 00986 * explicitly specified as they cannot be deduced. Unbound arguments 00987 * can comprise reference arguments. For example: 00988 * @code 00989 * int res; 00990 * auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;}); 00991 * cb->dispatch(2, 3, res); 00992 * std::cout << res << std::endl; 00993 * delete cb; 00994 * @endcode 00995 * 00996 * @b Overloaded @b functions 00997 * 00998 * Note that creating callbacks for overloaded functions can give rise 00999 * to an ambiguity when using Callback::make(), arising from the fact 01000 * that the callback object may have an unbound argument. For 01001 * example: 01002 * 01003 * @code 01004 * class MyClass { 01005 * ... 01006 * void add(int i); 01007 * void add(int i, int j); 01008 * void add(double d); 01009 * }; 01010 * MyClass obj; 01011 * using namespace Cgu; 01012 * Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok 01013 * Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0); // ok 01014 * Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1); // ambiguous - compilation failure 01015 * @endcode 01016 * 01017 * The third call to Callback::make() is ambiguous, as it could be 01018 * creating a callback for either the function MyClass::add(int) with 01019 * no unbound argument (that is, creating a Callback::Callback 01020 * object), or the function MyClass::add(int, int) with an unbound int 01021 * argument (that is, creating a Callback::CallbackArg<int> object). 01022 * This situation could be disambiguated by specifically stating the 01023 * type of the function which is to be chosen, namely, to instantiate 01024 * the callback in the third call with: 01025 * 01026 * @code 01027 * // either: 01028 * Callback::Callback* cb3 = 01029 * Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1); 01030 * // or: 01031 * Callback::CallbackArg<int>* cb3 = 01032 * Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1); 01033 * @endcode 01034 * 01035 * Callback::make_ref() is less capable than Callback::make() at 01036 * deducing template types. It cannot resolve overloaded functions by 01037 * examining the arguments passed to it. For example, take a class 01038 * MyClass as follows: 01039 * 01040 * @code 01041 * class MyClass { 01042 * ... 01043 * void add(int i, const double& d); 01044 * void add(const int& j, const int& k); 01045 * }; 01046 * @endcode 01047 * 01048 * Callback::make_ref() would require explicit disambiguation like 01049 * this: 01050 * 01051 * @code 01052 * Callback::Callback* cb1 = 01053 * Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2); 01054 * Callback::Callback* cb2 = 01055 * Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5); 01056 * @endcode 01057 * 01058 * Note also that, for CallbackArg objects created from std::function 01059 * objects, the std::function constructors and the std::mem_fn() and 01060 * std::bind() functions normally do not allow any function 01061 * overloading without explicit disambiguation. 01062 * 01063 * @b Posting @b of @b callbacks 01064 * 01065 * This file also provides Callback::post() functions which will 01066 * execute a callback in a glib main loop and can be used (amongst 01067 * other things) to pass an event from a worker thread to the main 01068 * program thread. In that respect, it provides an alternative to the 01069 * Notifier class. It is passed a pointer to a Callback::CallbackArg 01070 * object created with a call to Callback::make. 01071 * 01072 * To provide for thread-safe automatic disconnection of the callback 01073 * if the object whose method it represents is destroyed before the 01074 * callback executes in the main loop, include a Releaser as a public 01075 * member of that object and pass the Releaser object as the second 01076 * argument of Callback::post(). Note that for this to be race free, 01077 * the lifetime of the remote object whose method is to be invoked 01078 * must be determined by the thread to whose main loop the callback 01079 * has been attached. When the main loop begins invoking the 01080 * execution of the callback, the remote object must either wholly 01081 * exist (in which case the callback will be invoked) or have been 01082 * destroyed (in which case the callback will be ignored), and not be 01083 * in some transient half-state governed by another thread. 01084 * 01085 * Advantages as against Notifier: 01086 * 01087 * 1. If there are a lot of different events requiring callbacks to be 01088 * dispatched in the program from worker threads to the main 01089 * thread, this avoids having separate Notifier objects for each 01090 * event. 01091 * 01092 * 2. It is easier to pass arguments with varying values - they can be 01093 * passed as arguments to the Callback::make functions and no 01094 * special synchronisation is normally required (the call to 01095 * g_source_attach() invokes locking of the main loop which will 01096 * have the effect of ensuring memory visibility). With a Notifier 01097 * object it may be necessary to use an asynchronous queue to pass 01098 * variable values (or to bind a reference to the data, thus 01099 * normally requiring separate synchronisation). 01100 * 01101 * 3. Although the callback would normally be sent for execution by 01102 * the main program loop, and that is the default, it can be sent 01103 * for execution by any thread which has its own 01104 * GMainContext/GMainLoop objects. Thus callbacks can be passed 01105 * for execution between worker threads, or from the main program 01106 * thread to worker threads, as well as from worker threads to the 01107 * main program thread. 01108 * 01109 * Disadvantages as against Notifier: 01110 * 01111 * 1. Less efficient, as a new callback object has to be created on 01112 * freestore every time the callback is invoked, together with a 01113 * new Emitter object if a Releaser is used to track the callback. 01114 * 01115 * 2. Multiple callbacks relevant to a single event cannot be invoked 01116 * from a single call for the event - each callback has to be 01117 * separately dispatched. 01118 */ 01119 01120 #include <functional> // for std::less, std::function and std::hash<T*> 01121 #include <utility> // for std::move and std::forward 01122 #include <cstddef> // for std::size_t 01123 01124 #include <glib.h> 01125 01126 #include <c++-gtk-utils/shared_ptr.h> 01127 #include <c++-gtk-utils/param.h> 01128 #include <c++-gtk-utils/cgu_config.h> 01129 01130 namespace Cgu { 01131 01132 namespace Callback { 01133 01134 /* 01135 The CallbackArg class could be additionally templated to provide a 01136 return value, but that would affect the simplicity of the 01137 interface, and if a case were to arise where a result is needed, an 01138 alternative is for users to pass an argument by pointer (or pointer 01139 to pointer) rather than have a return value. 01140 */ 01141 01142 /* Declare the two basic interface types */ 01143 01144 template <class... FreeArgs> class CallbackArg; 01145 typedef CallbackArg<> Callback; 01146 01147 /* now the class definitions */ 01148 01149 /** 01150 * @class CallbackArg callback.h c++-gtk-utils/callback.h 01151 * @brief The callback interface class 01152 * @sa Callback namespace 01153 * @sa FunctorArg SafeFunctorArg 01154 * 01155 * This provides the basic interface class that users will generally 01156 * see. The template types are the types of the unbound arguments, if 01157 * any. Callback::CallbackArg<> is typedef'ed to Callback::Callback. 01158 * 01159 * @b Usage 01160 * 01161 * For a class object my_obj of type MyClass, with a method void 01162 * MyClass::my_method(int, int, const char*), usage for a fully bound 01163 * callback would be: 01164 * 01165 * @code 01166 * using namespace Cgu; 01167 * int arg1 = 1, arg2 = 5; 01168 * Callback::Callback* cb = 01169 * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n"); 01170 * cb->dispatch(); 01171 * delete cb; 01172 * @endcode 01173 * 01174 * Or for a partially bound callback: 01175 * 01176 * @code 01177 * using namespace Cgu; 01178 * int arg1 = 1, arg2 = 5; 01179 * Callback::CallbackArg<int, const char*>* cb = 01180 * Callback::make(my_obj, &MyClass::my_method, arg1); 01181 * cb->dispatch(arg2, "Hello\n"); 01182 * delete cb; 01183 * @endcode 01184 * 01185 * Callback/CallbackArg classes do not provide for a return value. If 01186 * a result is wanted, users should pass an unbound argument by 01187 * reference or pointer (or pointer to pointer). 01188 * 01189 * For further background, including about the Callback::make(), 01190 * Callback::make_ref() and Callback::lambda() functions, and the use 01191 * of these classes with std::function objects, read this: Callback 01192 */ 01193 01194 template <class... FreeArgs> 01195 class CallbackArg { 01196 public: 01197 /* Because dispatch() is a virtual function, we cannot templatise it 01198 * with a view to preserving r-value forwarding of temporary objects 01199 * passed as a free argument. But this would rarely be relevant 01200 * anyway - it would only be relevant if the target function were to 01201 * take an argument by r-value reference and a temporary were to be 01202 * passed to it. In such a case virtual dispatch is at the cost of a 01203 * copy of the temporary. 01204 */ 01205 /** 01206 * This will execute the referenced function or class method 01207 * encapsulated by this class. It will only throw if the dispatched 01208 * function or class method throws, or if the copy constructor of the 01209 * free or a bound argument throws and it is not a reference argument. 01210 * It is thread safe if the referenced function or class method is 01211 * thread safe. 01212 * @param args The unbound arguments to be passed to the referenced 01213 * function or class method, if any. 01214 * @note We use dispatch() to execute the callback, because the 01215 * callback would normally be invoked through a base class pointer. 01216 * To invoke it through operator()(), use the FunctorArg wrapper 01217 * class. 01218 */ 01219 virtual void dispatch(typename Cgu::Param<FreeArgs>::ParamType... args) const = 0; 01220 01221 /** 01222 * The constructor will not throw unless the copy constructor of an 01223 * argument bound to the derived implementation class throws. 01224 */ 01225 CallbackArg() {} 01226 01227 /** 01228 * The destructor will not throw unless the destructor of an argument 01229 * bound to the derived implementation class throws. 01230 */ 01231 virtual ~CallbackArg() {} 01232 01233 /* these functions will be inherited by the derived callback classes */ 01234 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT 01235 CGU_GLIB_MEMORY_SLICES_FUNCS 01236 #endif 01237 }; 01238 01239 /* The four basic functor types */ 01240 01241 template <class... FreeArgs> class FunctorArg; 01242 template <class... FreeArgs> class SafeFunctorArg; 01243 typedef FunctorArg<> Functor; 01244 typedef SafeFunctorArg<> SafeFunctor; 01245 01246 /* Functor friend functions */ 01247 01248 // we can use built-in operator == when comparing pointers referencing 01249 // different objects of the same type 01250 /** 01251 * Two FunctorArg objects compare equal if the addresses of the 01252 * CallbackArg objects they contain are the same. This comparison 01253 * operator does not throw. 01254 */ 01255 template <class... T> 01256 bool operator==(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) { 01257 return (f1.cb_s.get() == f2.cb_s.get()); 01258 } 01259 01260 /** 01261 * Two FunctorArg objects compare unequal if the addresses of the 01262 * CallbackArg objects they contain are not the same. This comparison 01263 * operator does not throw. 01264 */ 01265 template <class... T> 01266 bool operator!=(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) { 01267 return !(f1 == f2); 01268 } 01269 01270 // we must use std::less rather than the < built-in operator for 01271 // pointers to objects not within the same array or object: "For 01272 // templates greater, less, greater_equal, and less_equal, the 01273 // specializations for any pointer type yield a total order, even if 01274 // the built-in operators <, >, <=, >= do not." (para 20.3.3/8). 01275 /** 01276 * One FunctorArg object is less than another if the address of the 01277 * CallbackArg object contained by the first is regarded by std::less 01278 * as less than the address of the CallbackArg object contained by the 01279 * other. This comparison operator does not throw. 01280 */ 01281 template <class... T> 01282 bool operator<(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) { 01283 return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get()); 01284 } 01285 01286 /** 01287 * Two SafeFunctorArg objects compare equal if the addresses of the 01288 * CallbackArg objects they contain are the same. This comparison 01289 * operator does not throw. 01290 */ 01291 template <class... T> 01292 bool operator==(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) { 01293 return (f1.cb_s.get() == f2.cb_s.get()); 01294 } 01295 01296 /** 01297 * Two SafeFunctorArg objects compare unequal if the addresses of the 01298 * CallbackArg objects they contain are not the same. This comparison 01299 * operator does not throw. 01300 */ 01301 template <class... T> 01302 bool operator!=(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) { 01303 return !(f1 == f2); 01304 } 01305 01306 /** 01307 * One SafeFunctorArg object is less than another if the address of 01308 * the CallbackArg object contained by the first is regarded by 01309 * std::less as less than the address of the CallbackArg object 01310 * contained by the other. This comparison operator does not throw. 01311 */ 01312 template <class... T> 01313 bool operator<(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) { 01314 return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get()); 01315 } 01316 01317 } // namespace Callback 01318 } // namespace Cgu 01319 01320 // doxygen produces long filenames that tar can't handle: 01321 // we have generic documentation for std::hash specialisations 01322 // in doxygen.main.in 01323 #ifndef DOXYGEN_PARSING 01324 01325 /* These structs allow FunctorArg and SafeFunctorArg objects to be 01326 keys in unordered associative containers */ 01327 namespace std { 01328 template <class... T> 01329 struct hash<Cgu::Callback::FunctorArg<T...>> { 01330 typedef std::size_t result_type; 01331 typedef Cgu::Callback::FunctorArg<T...> argument_type; 01332 result_type operator()(const argument_type& f) const { 01333 // this is fine: std::hash structs do not normally contain data and 01334 // std::hash<T*> certainly won't, so we don't have overhead constructing 01335 // std::hash<T*> on the fly 01336 return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get()); 01337 } 01338 }; 01339 template <class... T> 01340 struct hash<Cgu::Callback::SafeFunctorArg<T...>> { 01341 typedef std::size_t result_type; 01342 typedef Cgu::Callback::SafeFunctorArg<T...> argument_type; 01343 result_type operator()(const argument_type& f) const { 01344 // this is fine: std::hash structs do not normally contain data and 01345 // std::hash<T*> certainly won't, so we don't have overhead constructing 01346 // std::hash<T*> on the fly 01347 return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get()); 01348 } 01349 }; 01350 } // namespace std 01351 01352 #endif // DOXYGEN_PARSING 01353 01354 namespace Cgu { 01355 namespace Callback { 01356 01357 /* the functor classes */ 01358 01359 /** 01360 * @class FunctorArg callback.h c++-gtk-utils/callback.h 01361 * @brief Functor class holding a Callback::CallbackArg object. 01362 * @sa SafeFunctorArg 01363 * @sa Callback namespace 01364 * 01365 * This class wraps a CallbackArg object. The callback object is kept 01366 * by SharedPtr so the functor can be copied and offers automatic 01367 * lifetime management of the wrapped callback object, as well as 01368 * providing an operator()() function. Ownership is taken of the 01369 * CallbackArg object passed to the constructor taking a CallbackArg 01370 * pointer, so that constructor should be treated like a shared 01371 * pointer constructor - only pass a newly allocated object to it (or 01372 * copy construct it or assign to it from another existing FunctorArg 01373 * object). The template types are the types of the unbound 01374 * arguments, if any. Callback::FunctorArg<> is typedef'ed to 01375 * Callback::Functor. 01376 * 01377 * The constructor taking a Callback::CallbackArg pointer is not 01378 * marked explicit, so the results of Callback::make() can be passed 01379 * directly to a function taking a Callback::FunctorArg argument, and 01380 * implicit conversion will take place. 01381 * 01382 * @b Usage 01383 * 01384 * For a class object my_obj of type MyClass, with a method void 01385 * MyClass::my_method(int, int, const char*), usage for a fully bound 01386 * functor would be: 01387 * 01388 * @code 01389 * using namespace Cgu; 01390 * int arg1 = 1, arg2 = 5; 01391 * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")}; 01392 * f(); 01393 * @endcode 01394 * 01395 * Or for a partially bound functor: 01396 * 01397 * @code 01398 * using namespace Cgu; 01399 * int arg1 = 1, arg2 = 5; 01400 * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)}; 01401 * f(arg2, "Hello\n"); 01402 * @endcode 01403 * 01404 * Callback/CallbackArg classes do not provide for a return value. If 01405 * a result is wanted, users should pass an unbound argument by 01406 * reference or pointer (or pointer to pointer). 01407 * 01408 * For further background, including about the Callback::make() and 01409 * Callback::make_ref() functions, and the use of these classes with 01410 * std::function objects, read this: Callback 01411 */ 01412 01413 template <class... FreeArgs> 01414 class FunctorArg { 01415 SharedPtr<const CallbackArg<FreeArgs...>> cb_s; 01416 public: 01417 /* Because CallbackArg::dispatch() is a virtual function, it is 01418 * pointless templatising this function with a view to preserving 01419 * r-value forwarding of temporary objects passed as a free argument, 01420 * because the r-value typeness will be discarded in dispatch(). But 01421 * this would rarely be relevant anyway - it would only be relevant if 01422 * the target function were to take an argument by r-value reference 01423 * and a temporary were to be passed to it. In such a case virtual 01424 * dispatch is at the cost of a copy of the temporary. 01425 */ 01426 /** 01427 * This will execute the referenced function or class method 01428 * encapsulated by this class. It will only throw if the executed 01429 * function or class method throws, or if the copy constructor of the 01430 * free or a bound argument throws and it is not a reference argument. 01431 * It is thread safe if the referenced function or class method is 01432 * thread safe. 01433 * @param args The unbound arguments to be passed to the referenced 01434 * function or class method, if any. 01435 */ 01436 void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const { 01437 if (cb_s.get()) cb_s->dispatch(args...); 01438 } 01439 01440 /** 01441 * This function does not throw. 01442 * @param f The assignor. 01443 * @return The functor object after assignment. 01444 */ 01445 FunctorArg& operator=(const FunctorArg& f) {cb_s = f.cb_s; return *this;} 01446 01447 /** 01448 * This function does not throw. 01449 * @param f The functor to be moved. 01450 * @return The functor object after the move operation. 01451 */ 01452 FunctorArg& operator=(FunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;} 01453 01454 /** 01455 * Two FunctorArg objects compare equal if the addresses of the 01456 * CallbackArg objects they contain are the same. This comparison 01457 * operator does not throw. 01458 */ 01459 friend bool operator== <>(const FunctorArg&, const FunctorArg&); 01460 01461 /** 01462 * One FunctorArg object is less than another if the address of the 01463 * CallbackArg object contained by the first is regarded by std::less 01464 * as less than the address of the CallbackArg object contained by the 01465 * other. This comparison operator does not throw. 01466 */ 01467 friend bool operator< <>(const FunctorArg&, const FunctorArg&); 01468 01469 friend struct std::hash<FunctorArg>; 01470 01471 /** 01472 * Constructor of first FunctorArg holding the referenced callback. 01473 * As it is not marked explicit, it is also a type conversion 01474 * constructor. 01475 * @param cb The CallbackArg object which the functor is to manage. 01476 * @exception std::bad_alloc This might throw std::bad_alloc if 01477 * memory is exhausted and the system throws in that case. Note that 01478 * if such an exception is thrown, then this constructor will clean 01479 * itself up and also delete the callback object passed to it. 01480 * @note std::bad_alloc will not be thrown if the library has been 01481 * installed using the --with-glib-memory-slices-no-compat 01482 * configuration option: instead glib will terminate the program if it 01483 * is unable to obtain memory from the operating system. 01484 */ 01485 FunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {} 01486 01487 /** 01488 * The copy constructor does not throw. 01489 * @param f The assignor 01490 */ 01491 FunctorArg(const FunctorArg& f): cb_s(f.cb_s) {} 01492 01493 /** 01494 * The move constructor does not throw. 01495 * @param f The functor to be moved. 01496 */ 01497 FunctorArg(FunctorArg&& f): cb_s(std::move(f.cb_s)) {} 01498 01499 /** 01500 * Default constructor, where a Callback::CallbackArg object is to be 01501 * assigned later (via the type conversion constructor and/or the 01502 * assignment operator). This constructor does not throw. 01503 */ 01504 FunctorArg() {} 01505 01506 /* Only has effect if --with-glib-memory-slices-compat or 01507 --with-glib-memory-slices-no-compat option picked */ 01508 CGU_GLIB_MEMORY_SLICES_FUNCS 01509 }; 01510 01511 /** 01512 * @class SafeFunctorArg callback.h c++-gtk-utils/callback.h 01513 * @brief Functor class holding a Callback::CallbackArg object, with 01514 * thread-safe reference count. 01515 * @sa FunctorArg 01516 * @sa Callback namespace 01517 * 01518 * This class is the same as Callback::FunctorArg except that it will 01519 * provide synchronisation of the reference count between threads. 01520 * Use it where a functor wrapper object is to be passed between 01521 * threads. The FunctorArg documentation gives details on usage. 01522 * 01523 * Callback::SafeFunctorArg<> is typedef'ed to Callback::SafeFunctor. 01524 * 01525 * For further background, read this: Callback 01526 */ 01527 01528 template <class... FreeArgs> 01529 class SafeFunctorArg { 01530 SharedLockPtr<const CallbackArg<FreeArgs...>> cb_s; 01531 public: 01532 /** 01533 * This will execute the referenced function or class method 01534 * encapsulated by this class. It will only throw if the executed 01535 * function or class method throws, or if the copy constructor of the 01536 * free or a bound argument throws and it is not a reference argument. 01537 * It is thread safe if the referenced function or class method is 01538 * thread safe. 01539 * @param args The unbound arguments to be passed to the referenced 01540 * function or class method, if any. 01541 */ 01542 void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const { 01543 if (cb_s.get()) cb_s->dispatch(args...); 01544 } 01545 01546 /** 01547 * This function does not throw. 01548 * @param f The assignor. 01549 * @return The functor object after assignment. 01550 */ 01551 SafeFunctorArg& operator=(const SafeFunctorArg& f) {cb_s = f.cb_s; return *this;} 01552 01553 /** 01554 * This function does not throw. 01555 * @param f The functor to be moved. 01556 * @return The functor object after the move operation. 01557 */ 01558 SafeFunctorArg& operator=(SafeFunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;} 01559 01560 /** 01561 * Two SafeFunctorArg objects compare equal if the addresses of the 01562 * CallbackArg objects they contain are the same. This comparison 01563 * operator does not throw. 01564 */ 01565 friend bool operator== <>(const SafeFunctorArg&, const SafeFunctorArg&); 01566 01567 /** 01568 * One SafeFunctorArg object is less than another if the address of 01569 * the CallbackArg object contained by the first is regarded by 01570 * std::less as less than the address of the CallbackArg object 01571 * contained by the other. This comparison operator does not throw. 01572 */ 01573 friend bool operator< <>(const SafeFunctorArg&, const SafeFunctorArg&); 01574 01575 friend struct std::hash<SafeFunctorArg>; 01576 01577 /** 01578 * Constructor of first SafeFunctorArg holding the referenced 01579 * callback. As it is not marked explicit, it is also a type 01580 * conversion constructor. 01581 * @param cb The CallbackArg object which the functor is to manage. 01582 * @exception std::bad_alloc This might throw std::bad_alloc if 01583 * memory is exhausted and the system throws in that case. Note that 01584 * if such an exception is thrown, then this constructor will clean 01585 * itself up and also delete the callback object passed to it. 01586 * @note std::bad_alloc will not be thrown if the library has been 01587 * installed using the --with-glib-memory-slices-no-compat 01588 * configuration option: instead glib will terminate the program if it 01589 * is unable to obtain memory from the operating system. 01590 */ 01591 SafeFunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {} 01592 01593 /** 01594 * The copy constructor does not throw. 01595 * @param f The assignor. 01596 */ 01597 SafeFunctorArg(const SafeFunctorArg& f): cb_s(f.cb_s) {} 01598 01599 /** 01600 * The move constructor does not throw. 01601 * @param f The functor to be moved. 01602 */ 01603 SafeFunctorArg(SafeFunctorArg&& f): cb_s(std::move(f.cb_s)) {} 01604 01605 /** 01606 * Default constructor, where a Callback::CallbackArg object is to be 01607 * assigned later (via the type conversion constructor and/or the 01608 * assignment operator). This constructor does not throw. 01609 * @note The reference count maintained with respect to the contained 01610 * callback object is thread-safe, so SafeFunctorArg objects may be 01611 * copied between threads by the implicit assignment operator and put 01612 * in different containers in different threads. They use a 01613 * SharedLockPtr object to hold the referenced callback object. 01614 */ 01615 SafeFunctorArg() {} 01616 01617 /* Only has effect if --with-glib-memory-slices-compat or 01618 --with-glib-memory-slices-no-compat option picked */ 01619 CGU_GLIB_MEMORY_SLICES_FUNCS 01620 }; 01621 01622 /* the callback implementation classes */ 01623 01624 template <class T, class... FreeArgs> 01625 class Callback0: public CallbackArg<FreeArgs...> { 01626 public: 01627 typedef void (T::* MemFunc)(FreeArgs...); 01628 private: 01629 T* obj; 01630 MemFunc func; 01631 public: 01632 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01633 (obj->*func)(free_args...); 01634 } 01635 Callback0(T& obj_, MemFunc func_): obj(&obj_), func(func_) {} 01636 }; 01637 01638 template <bool unref, class T, class BoundArg, class... FreeArgs> 01639 class Callback1: public CallbackArg<FreeArgs...> { 01640 public: 01641 typedef void (T::* MemFunc)(BoundArg, FreeArgs...); 01642 private: 01643 T* obj; 01644 MemFunc func; 01645 typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg; 01646 public: 01647 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01648 (obj->*func)(arg, free_args...); 01649 } 01650 template <class Arg> 01651 Callback1(T& obj_, MemFunc func_, 01652 Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {} 01653 }; 01654 01655 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs> 01656 class Callback2: public CallbackArg<FreeArgs...> { 01657 public: 01658 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...); 01659 private: 01660 T* obj; 01661 MemFunc func; 01662 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01663 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01664 public: 01665 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01666 (obj->*func)(arg1, arg2, free_args...); 01667 } 01668 template <class Arg1, class Arg2> 01669 Callback2(T& obj_, MemFunc func_, 01670 Arg1&& arg1_, 01671 Arg2&& arg2_): obj(&obj_), func(func_), 01672 arg1(std::forward<Arg1>(arg1_)), 01673 arg2(std::forward<Arg2>(arg2_)) {} 01674 }; 01675 01676 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 01677 class Callback3: public CallbackArg<FreeArgs...> { 01678 public: 01679 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...); 01680 private: 01681 T* obj; 01682 MemFunc func; 01683 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01684 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01685 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01686 public: 01687 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01688 (obj->*func)(arg1, arg2, arg3, free_args...); 01689 } 01690 template <class Arg1, class Arg2, class Arg3> 01691 Callback3(T& obj_, MemFunc func_, 01692 Arg1&& arg1_, 01693 Arg2&& arg2_, 01694 Arg3&& arg3_): 01695 obj(&obj_), func(func_), 01696 arg1(std::forward<Arg1>(arg1_)), 01697 arg2(std::forward<Arg2>(arg2_)), 01698 arg3(std::forward<Arg3>(arg3_)) {} 01699 }; 01700 01701 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 01702 class BoundArg4, class... FreeArgs> 01703 class Callback4: public CallbackArg<FreeArgs...> { 01704 public: 01705 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...); 01706 private: 01707 T* obj; 01708 MemFunc func; 01709 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01710 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01711 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01712 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 01713 public: 01714 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01715 (obj->*func)(arg1, arg2, arg3, arg4, free_args...); 01716 } 01717 template <class Arg1, class Arg2, class Arg3, class Arg4> 01718 Callback4(T& obj_, MemFunc func_, 01719 Arg1&& arg1_, 01720 Arg2&& arg2_, 01721 Arg3&& arg3_, 01722 Arg4&& arg4_): 01723 obj(&obj_), func(func_), 01724 arg1(std::forward<Arg1>(arg1_)), 01725 arg2(std::forward<Arg2>(arg2_)), 01726 arg3(std::forward<Arg3>(arg3_)), 01727 arg4(std::forward<Arg4>(arg4_)) {} 01728 }; 01729 01730 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 01731 class BoundArg4, class BoundArg5, class... FreeArgs> 01732 class Callback5: public CallbackArg<FreeArgs...> { 01733 public: 01734 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, 01735 BoundArg4, BoundArg5, FreeArgs...); 01736 private: 01737 T* obj; 01738 MemFunc func; 01739 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01740 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01741 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01742 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 01743 typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5; 01744 public: 01745 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01746 (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...); 01747 } 01748 template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5> 01749 Callback5(T& obj_, MemFunc func_, 01750 Arg1&& arg1_, 01751 Arg2&& arg2_, 01752 Arg3&& arg3_, 01753 Arg4&& arg4_, 01754 Arg5&& arg5_): 01755 obj(&obj_), func(func_), 01756 arg1(std::forward<Arg1>(arg1_)), 01757 arg2(std::forward<Arg2>(arg2_)), 01758 arg3(std::forward<Arg3>(arg3_)), 01759 arg4(std::forward<Arg4>(arg4_)), 01760 arg5(std::forward<Arg5>(arg5_)) {} 01761 }; 01762 01763 /* const versions, for binding to const methods */ 01764 01765 template <class T, class... FreeArgs> 01766 class Callback0_const: public CallbackArg<FreeArgs...> { 01767 public: 01768 typedef void (T::* MemFunc)(FreeArgs...) const; 01769 private: 01770 const T* obj; 01771 MemFunc func; 01772 public: 01773 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01774 (obj->*func)(free_args...); 01775 } 01776 Callback0_const(const T& obj_, MemFunc func_): obj(&obj_), func(func_) {} 01777 }; 01778 01779 template <bool unref, class T, class BoundArg, class... FreeArgs> 01780 class Callback1_const: public CallbackArg<FreeArgs...> { 01781 public: 01782 typedef void (T::* MemFunc)(BoundArg, FreeArgs...) const; 01783 private: 01784 const T* obj; 01785 MemFunc func; 01786 typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg; 01787 public: 01788 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01789 (obj->*func)(arg, free_args...); 01790 } 01791 template <class Arg> 01792 Callback1_const(const T& obj_, MemFunc func_, 01793 Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {} 01794 }; 01795 01796 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs> 01797 class Callback2_const: public CallbackArg<FreeArgs...> { 01798 public: 01799 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...) const; 01800 private: 01801 const T* obj; 01802 MemFunc func; 01803 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01804 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01805 public: 01806 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01807 (obj->*func)(arg1, arg2, free_args...); 01808 } 01809 template <class Arg1, class Arg2> 01810 Callback2_const(const T& obj_, MemFunc func_, 01811 Arg1&& arg1_, 01812 Arg2&& arg2_): obj(&obj_), func(func_), 01813 arg1(std::forward<Arg1>(arg1_)), 01814 arg2(std::forward<Arg2>(arg2_)) {} 01815 }; 01816 01817 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 01818 class Callback3_const: public CallbackArg<FreeArgs...> { 01819 public: 01820 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const; 01821 private: 01822 const T* obj; 01823 MemFunc func; 01824 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01825 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01826 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01827 public: 01828 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01829 (obj->*func)(arg1, arg2, arg3, free_args...); 01830 } 01831 template <class Arg1, class Arg2, class Arg3> 01832 Callback3_const(const T& obj_, MemFunc func_, 01833 Arg1&& arg1_, 01834 Arg2&& arg2_, 01835 Arg3&& arg3_): 01836 obj(&obj_), func(func_), 01837 arg1(std::forward<Arg1>(arg1_)), 01838 arg2(std::forward<Arg2>(arg2_)), 01839 arg3(std::forward<Arg3>(arg3_)) {} 01840 }; 01841 01842 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 01843 class BoundArg4, class... FreeArgs> 01844 class Callback4_const: public CallbackArg<FreeArgs...> { 01845 public: 01846 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const; 01847 private: 01848 const T* obj; 01849 MemFunc func; 01850 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01851 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01852 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01853 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 01854 public: 01855 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01856 (obj->*func)(arg1, arg2, arg3, arg4, free_args...); 01857 } 01858 template <class Arg1, class Arg2, class Arg3, class Arg4> 01859 Callback4_const(const T& obj_, MemFunc func_, 01860 Arg1&& arg1_, 01861 Arg2&& arg2_, 01862 Arg3&& arg3_, 01863 Arg4&& arg4_): 01864 obj(&obj_), func(func_), 01865 arg1(std::forward<Arg1>(arg1_)), 01866 arg2(std::forward<Arg2>(arg2_)), 01867 arg3(std::forward<Arg3>(arg3_)), 01868 arg4(std::forward<Arg4>(arg4_)) {} 01869 }; 01870 01871 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 01872 class BoundArg4, class BoundArg5, class... FreeArgs> 01873 class Callback5_const: public CallbackArg<FreeArgs...> { 01874 public: 01875 typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, 01876 BoundArg4, BoundArg5, FreeArgs...) const; 01877 private: 01878 const T* obj; 01879 MemFunc func; 01880 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01881 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01882 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01883 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 01884 typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5; 01885 public: 01886 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01887 (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...); 01888 } 01889 template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5> 01890 Callback5_const(const T& obj_, MemFunc func_, 01891 Arg1&& arg1_, 01892 Arg2&& arg2_, 01893 Arg3&& arg3_, 01894 Arg4&& arg4_, 01895 Arg5&& arg5_): 01896 obj(&obj_), func(func_), 01897 arg1(std::forward<Arg1>(arg1_)), 01898 arg2(std::forward<Arg2>(arg2_)), 01899 arg3(std::forward<Arg3>(arg3_)), 01900 arg4(std::forward<Arg4>(arg4_)), 01901 arg5(std::forward<Arg5>(arg5_)) {} 01902 }; 01903 01904 /* for static class methods and non-class functions */ 01905 01906 template <class... FreeArgs> 01907 class Callback0_static: public CallbackArg<FreeArgs...> { 01908 public: 01909 typedef void (*Func)(FreeArgs...); 01910 private: 01911 Func func; 01912 public: 01913 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01914 func(free_args...); 01915 } 01916 Callback0_static(Func func_): func(func_) {} 01917 }; 01918 01919 template <bool unref, class BoundArg, class... FreeArgs> 01920 class Callback1_static: public CallbackArg<FreeArgs...> { 01921 public: 01922 typedef void (*Func)(BoundArg, FreeArgs...); 01923 private: 01924 Func func; 01925 typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg; 01926 public: 01927 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01928 func(arg, free_args...); 01929 } 01930 template <class Arg> 01931 Callback1_static(Func func_, Arg&& arg_): func(func_), arg(std::forward<Arg>(arg_)) {} 01932 }; 01933 01934 template <bool unref, class BoundArg1, class BoundArg2, class... FreeArgs> 01935 class Callback2_static: public CallbackArg<FreeArgs...> { 01936 public: 01937 typedef void (*Func)(BoundArg1, BoundArg2, FreeArgs...); 01938 private: 01939 Func func; 01940 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01941 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01942 public: 01943 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01944 func(arg1, arg2, free_args...); 01945 } 01946 template <class Arg1, class Arg2> 01947 Callback2_static(Func func_, Arg1&& arg1_, 01948 Arg2&& arg2_): func(func_), 01949 arg1(std::forward<Arg1>(arg1_)), 01950 arg2(std::forward<Arg2>(arg2_)) {} 01951 }; 01952 01953 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 01954 class Callback3_static: public CallbackArg<FreeArgs...> { 01955 public: 01956 typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...); 01957 private: 01958 Func func; 01959 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01960 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01961 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01962 public: 01963 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01964 func(arg1, arg2, arg3, free_args...); 01965 } 01966 template <class Arg1, class Arg2, class Arg3> 01967 Callback3_static(Func func_, 01968 Arg1&& arg1_, 01969 Arg2&& arg2_, 01970 Arg3&& arg3_): 01971 func(func_), 01972 arg1(std::forward<Arg1>(arg1_)), 01973 arg2(std::forward<Arg2>(arg2_)), 01974 arg3(std::forward<Arg3>(arg3_)) {} 01975 }; 01976 01977 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, 01978 class BoundArg4, class... FreeArgs> 01979 class Callback4_static: public CallbackArg<FreeArgs...> { 01980 public: 01981 typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...); 01982 private: 01983 Func func; 01984 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 01985 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 01986 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 01987 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 01988 public: 01989 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 01990 func(arg1, arg2, arg3, arg4, free_args...); 01991 } 01992 template <class Arg1, class Arg2, class Arg3, class Arg4> 01993 Callback4_static(Func func_, 01994 Arg1&& arg1_, 01995 Arg2&& arg2_, 01996 Arg3&& arg3_, 01997 Arg4&& arg4_): 01998 func(func_), 01999 arg1(std::forward<Arg1>(arg1_)), 02000 arg2(std::forward<Arg2>(arg2_)), 02001 arg3(std::forward<Arg3>(arg3_)), 02002 arg4(std::forward<Arg4>(arg4_)) {} 02003 }; 02004 02005 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, 02006 class BoundArg4, class BoundArg5, class... FreeArgs> 02007 class Callback5_static: public CallbackArg<FreeArgs...> { 02008 public: 02009 typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, 02010 BoundArg4, BoundArg5, FreeArgs...); 02011 private: 02012 Func func; 02013 typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1; 02014 typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2; 02015 typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3; 02016 typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4; 02017 typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5; 02018 public: 02019 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const { 02020 func(arg1, arg2, arg3, arg4, arg5, free_args...); 02021 } 02022 template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5> 02023 Callback5_static(Func func_, 02024 Arg1&& arg1_, 02025 Arg2&& arg2_, 02026 Arg3&& arg3_, 02027 Arg4&& arg4_, 02028 Arg5&& arg5_): 02029 func(func_), 02030 arg1(std::forward<Arg1>(arg1_)), 02031 arg2(std::forward<Arg2>(arg2_)), 02032 arg3(std::forward<Arg3>(arg3_)), 02033 arg4(std::forward<Arg4>(arg4_)), 02034 arg5(std::forward<Arg5>(arg5_)) {} 02035 }; 02036 02037 // TODO: Version 2.0.9 provides a Callback_lambda class for callable 02038 // objects which makes the specialized Callback_function class 02039 // redundant. At an API break we can remove the Callback_function 02040 // class and modify the Callback::make() helper function overload for 02041 // std::function objects to construct a Callback_lambda object 02042 // instead. Doing it now would not affect ABI compatibility as the 02043 // library produces these only by base pointer, but a user may have 02044 // instantiated them by hand in user code. 02045 template <class... FreeArgs> 02046 class Callback_function: public CallbackArg<FreeArgs...> { 02047 std::function<void(FreeArgs...)> f; 02048 public: 02049 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {f(free_args...);} 02050 Callback_function(const std::function<void(FreeArgs...)>& f_): f(f_) {} 02051 Callback_function(std::function<void(FreeArgs...)>&& f_): f(std::move(f_)) {} 02052 }; 02053 02054 // generic class for callable objects such as lambdas 02055 template <class Lambda, class... FreeArgs> 02056 class Callback_lambda: public CallbackArg<FreeArgs...> { 02057 Lambda l; 02058 public: 02059 void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {l(free_args...);} 02060 template <class L> Callback_lambda(L&& l_): l(std::forward<L>(l_)) {} 02061 }; 02062 02063 /* Convenience functions making callback objects on freestore. These 02064 * can for example be passed as the first argument of the 02065 * Thread::start() method in thread.h. They are also used by the 02066 * Callback::post() function. 02067 */ 02068 02069 /** 02070 * A convenience function to make Callback::CallbackArg objects 02071 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02072 * is exhausted and the system throws in that case. This exception 02073 * will not be thrown if the library has been installed using the 02074 * --with-glib-memory-slices-no-compat configuration option (instead 02075 * glib will terminate the program if it is unable to obtain memory 02076 * from the operating system). 02077 */ 02078 template <class T, class... FreeArgs> 02079 CallbackArg<FreeArgs...>* make(T& t, 02080 void (T::*func)(FreeArgs...)) { 02081 return new Callback0<T, FreeArgs...>{t, func}; 02082 } 02083 02084 /** 02085 * DEPRECATED. 02086 * 02087 * Since this function constructs a callback which does not take a 02088 * bound argument, it is a synonym for make() (the two are identical). 02089 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02090 * is exhausted and the system throws in that case. This exception 02091 * will not be thrown if the library has been installed using the 02092 * --with-glib-memory-slices-no-compat configuration option (instead 02093 * glib will terminate the program if it is unable to obtain memory 02094 * from the operating system). 02095 */ 02096 template <class T, class... FreeArgs> 02097 CallbackArg<FreeArgs...>* make_val(T& t, 02098 void (T::*func)(FreeArgs...)) { 02099 return new Callback0<T, FreeArgs...>{t, func}; 02100 } 02101 02102 /** 02103 * Since this function constructs a callback which does not take a 02104 * bound argument, it is a synonym for make() (the two are identical). 02105 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02106 * is exhausted and the system throws in that case. This exception 02107 * will not be thrown if the library has been installed using the 02108 * --with-glib-memory-slices-no-compat configuration option (instead 02109 * glib will terminate the program if it is unable to obtain memory 02110 * from the operating system). 02111 * 02112 * Since 2.0.0-rc3 02113 */ 02114 template <class T, class... FreeArgs> 02115 CallbackArg<FreeArgs...>* make_ref(T& t, 02116 void (T::*func)(FreeArgs...)) { 02117 return new Callback0<T, FreeArgs...>{t, func}; 02118 } 02119 02120 /** 02121 * A convenience function to make Callback::CallbackArg objects 02122 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02123 * is exhausted and the system throws in that case (this exception 02124 * will not be thrown if the library has been installed using the 02125 * --with-glib-memory-slices-no-compat configuration option: instead 02126 * glib will terminate the program if it is unable to obtain memory 02127 * from the operating system). It will also throw if the copy 02128 * constructor of a bound argument throws and it is not a reference 02129 * argument. 02130 */ 02131 template <class T, class BoundArg, class... FreeArgs> 02132 CallbackArg<FreeArgs...>* make(T& t, 02133 void (T::*func)(BoundArg, FreeArgs...), 02134 BoundArg arg) { 02135 return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg}; 02136 } 02137 02138 /** 02139 * DEPRECATED: use Callback::make_ref() instead. 02140 * 02141 * An alternative function to make Callback::CallbackArg objects, 02142 * which is for use where a target function receives an argument of 02143 * class type by value which is to be a bound argument, so the 02144 * compiler is not able to carry out copy elision when constructing 02145 * the callback object. 02146 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02147 * is exhausted and the system throws in that case (this exception 02148 * will not be thrown if the library has been installed using the 02149 * --with-glib-memory-slices-no-compat configuration option: instead 02150 * glib will terminate the program if it is unable to obtain memory 02151 * from the operating system). It will also throw if the copy 02152 * constructor of a bound argument throws and it is not a reference 02153 * argument. 02154 */ 02155 template <class T, class BoundArg, class... FreeArgs> 02156 CallbackArg<FreeArgs...>* make_val(T& t, 02157 void (T::*func)(BoundArg, FreeArgs...), 02158 const BoundArg& arg) { 02159 return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg}; 02160 } 02161 02162 /** 02163 * An alternative function to make Callback::CallbackArg objects, 02164 * which is for use where a target function either receives a class 02165 * type bound argument by value, or receives a bound argument by 02166 * reference to const in a case where the generated CallbackArg object 02167 * is to store a copy of that argument instead of just keeping a 02168 * reference. 02169 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02170 * is exhausted and the system throws in that case (this exception 02171 * will not be thrown if the library has been installed using the 02172 * --with-glib-memory-slices-no-compat configuration option: instead 02173 * glib will terminate the program if it is unable to obtain memory 02174 * from the operating system). It will also throw if the copy or move 02175 * constructor of a bound argument throws and it is not a reference 02176 * argument. 02177 * 02178 * Since 2.0.0-rc3 02179 */ 02180 template <class T, class BoundArg, class Arg, class... FreeArgs> 02181 CallbackArg<FreeArgs...>* make_ref(T& t, 02182 void (T::*func)(BoundArg, FreeArgs...), 02183 Arg&& arg) { 02184 return new Callback1<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)}; 02185 } 02186 02187 /** 02188 * A convenience function to make Callback::CallbackArg objects 02189 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02190 * is exhausted and the system throws in that case (this exception 02191 * will not be thrown if the library has been installed using the 02192 * --with-glib-memory-slices-no-compat configuration option: instead 02193 * glib will terminate the program if it is unable to obtain memory 02194 * from the operating system). It will also throw if the copy 02195 * constructor of a bound argument throws and it is not a reference 02196 * argument. 02197 */ 02198 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs> 02199 CallbackArg<FreeArgs...>* make(T& t, 02200 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...), 02201 BoundArg1 arg1, 02202 BoundArg2 arg2) { 02203 return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2}; 02204 } 02205 02206 /** 02207 * DEPRECATED: use Callback::make_ref() instead. 02208 * 02209 * An alternative function to make Callback::CallbackArg objects, 02210 * which is for use where a target function receives an argument of 02211 * class type by value which is to be a bound argument, so the 02212 * compiler is not able to carry out copy elision when constructing 02213 * the callback object. 02214 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02215 * is exhausted and the system throws in that case (this exception 02216 * will not be thrown if the library has been installed using the 02217 * --with-glib-memory-slices-no-compat configuration option: instead 02218 * glib will terminate the program if it is unable to obtain memory 02219 * from the operating system). It will also throw if the copy 02220 * constructor of a bound argument throws and it is not a reference 02221 * argument. 02222 */ 02223 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs> 02224 CallbackArg<FreeArgs...>* make_val(T& t, 02225 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...), 02226 const BoundArg1& arg1, 02227 const BoundArg2& arg2) { 02228 return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2}; 02229 } 02230 02231 /** 02232 * An alternative function to make Callback::CallbackArg objects, 02233 * which is for use where a target function either receives a class 02234 * type bound argument by value, or receives a bound argument by 02235 * reference to const in a case where the generated CallbackArg object 02236 * is to store a copy of that argument instead of just keeping a 02237 * reference. 02238 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02239 * is exhausted and the system throws in that case (this exception 02240 * will not be thrown if the library has been installed using the 02241 * --with-glib-memory-slices-no-compat configuration option: instead 02242 * glib will terminate the program if it is unable to obtain memory 02243 * from the operating system). It will also throw if the copy or move 02244 * constructor of a bound argument throws and it is not a reference 02245 * argument. 02246 * 02247 * Since 2.0.0-rc3 02248 */ 02249 template <class T, class BoundArg1, class BoundArg2, 02250 class Arg1, class Arg2, class... FreeArgs> 02251 CallbackArg<FreeArgs...>* make_ref(T& t, 02252 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...), 02253 Arg1&& arg1, 02254 Arg2&& arg2) { 02255 return new Callback2<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, 02256 std::forward<Arg1>(arg1), 02257 std::forward<Arg2>(arg2)}; 02258 } 02259 02260 /** 02261 * A convenience function to make Callback::CallbackArg objects 02262 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02263 * is exhausted and the system throws in that case (this exception 02264 * will not be thrown if the library has been installed using the 02265 * --with-glib-memory-slices-no-compat configuration option: instead 02266 * glib will terminate the program if it is unable to obtain memory 02267 * from the operating system). It will also throw if the copy 02268 * constructor of a bound argument throws and it is not a reference 02269 * argument. 02270 */ 02271 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 02272 CallbackArg<FreeArgs...>* make(T& t, 02273 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 02274 BoundArg1 arg1, 02275 BoundArg2 arg2, 02276 BoundArg3 arg3) { 02277 return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3}; 02278 } 02279 02280 /** 02281 * DEPRECATED: use Callback::make_ref() instead. 02282 * 02283 * An alternative function to make Callback::CallbackArg objects, 02284 * which is for use where a target function receives an argument of 02285 * class type by value which is to be a bound argument, so the 02286 * compiler is not able to carry out copy elision when constructing 02287 * the callback object. 02288 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02289 * is exhausted and the system throws in that case (this exception 02290 * will not be thrown if the library has been installed using the 02291 * --with-glib-memory-slices-no-compat configuration option: instead 02292 * glib will terminate the program if it is unable to obtain memory 02293 * from the operating system). It will also throw if the copy 02294 * constructor of a bound argument throws and it is not a reference 02295 * argument. 02296 */ 02297 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 02298 CallbackArg<FreeArgs...>* make_val(T& t, 02299 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 02300 const BoundArg1& arg1, 02301 const BoundArg2& arg2, 02302 const BoundArg3& arg3) { 02303 return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3}; 02304 } 02305 02306 /** 02307 * An alternative function to make Callback::CallbackArg objects, 02308 * which is for use where a target function either receives a class 02309 * type bound argument by value, or receives a bound argument by 02310 * reference to const in a case where the generated CallbackArg object 02311 * is to store a copy of that argument instead of just keeping a 02312 * reference. 02313 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02314 * is exhausted and the system throws in that case (this exception 02315 * will not be thrown if the library has been installed using the 02316 * --with-glib-memory-slices-no-compat configuration option: instead 02317 * glib will terminate the program if it is unable to obtain memory 02318 * from the operating system). It will also throw if the copy or move 02319 * constructor of a bound argument throws and it is not a reference 02320 * argument. 02321 * 02322 * Since 2.0.0-rc3 02323 */ 02324 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02325 class Arg1, class Arg2, class Arg3, class... FreeArgs> 02326 CallbackArg<FreeArgs...>* make_ref(T& t, 02327 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 02328 Arg1&& arg1, 02329 Arg2&& arg2, 02330 Arg3&& arg3) { 02331 return new Callback3<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, 02332 std::forward<Arg1>(arg1), 02333 std::forward<Arg2>(arg2), 02334 std::forward<Arg3>(arg3)}; 02335 } 02336 02337 /** 02338 * A convenience function to make Callback::CallbackArg objects 02339 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02340 * is exhausted and the system throws in that case (this exception 02341 * will not be thrown if the library has been installed using the 02342 * --with-glib-memory-slices-no-compat configuration option: instead 02343 * glib will terminate the program if it is unable to obtain memory 02344 * from the operating system). It will also throw if the copy 02345 * constructor of a bound argument throws and it is not a reference 02346 * argument. 02347 */ 02348 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02349 class BoundArg4, class... FreeArgs> 02350 CallbackArg<FreeArgs...>* make(T& t, 02351 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02352 BoundArg4, FreeArgs...), 02353 BoundArg1 arg1, 02354 BoundArg2 arg2, 02355 BoundArg3 arg3, 02356 BoundArg4 arg4) { 02357 return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3, 02358 BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4}; 02359 } 02360 02361 /** 02362 * DEPRECATED: use Callback::make_ref() instead. 02363 * 02364 * An alternative function to make Callback::CallbackArg objects, 02365 * which is for use where a target function receives an argument of 02366 * class type by value which is to be a bound argument, so the 02367 * compiler is not able to carry out copy elision when constructing 02368 * the callback object. 02369 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02370 * is exhausted and the system throws in that case (this exception 02371 * will not be thrown if the library has been installed using the 02372 * --with-glib-memory-slices-no-compat configuration option: instead 02373 * glib will terminate the program if it is unable to obtain memory 02374 * from the operating system). It will also throw if the copy 02375 * constructor of a bound argument throws and it is not a reference 02376 * argument. 02377 */ 02378 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02379 class BoundArg4, class... FreeArgs> 02380 CallbackArg<FreeArgs...>* make_val(T& t, 02381 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02382 BoundArg4, FreeArgs...), 02383 const BoundArg1& arg1, 02384 const BoundArg2& arg2, 02385 const BoundArg3& arg3, 02386 const BoundArg4& arg4) { 02387 return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3, 02388 BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4}; 02389 } 02390 02391 /** 02392 * An alternative function to make Callback::CallbackArg objects, 02393 * which is for use where a target function either receives a class 02394 * type bound argument by value, or receives a bound argument by 02395 * reference to const in a case where the generated CallbackArg object 02396 * is to store a copy of that argument instead of just keeping a 02397 * reference. 02398 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02399 * is exhausted and the system throws in that case (this exception 02400 * will not be thrown if the library has been installed using the 02401 * --with-glib-memory-slices-no-compat configuration option: instead 02402 * glib will terminate the program if it is unable to obtain memory 02403 * from the operating system). It will also throw if the copy or move 02404 * constructor of a bound argument throws and it is not a reference 02405 * argument. 02406 * 02407 * Since 2.0.0-rc3 02408 */ 02409 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, 02410 class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs> 02411 CallbackArg<FreeArgs...>* make_ref(T& t, 02412 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02413 BoundArg4, FreeArgs...), 02414 Arg1&& arg1, 02415 Arg2&& arg2, 02416 Arg3&& arg3, 02417 Arg4&& arg4) { 02418 return new Callback4<true, T, BoundArg1, BoundArg2, BoundArg3, 02419 BoundArg4, FreeArgs...>{t, func, 02420 std::forward<Arg1>(arg1), 02421 std::forward<Arg2>(arg2), 02422 std::forward<Arg3>(arg3), 02423 std::forward<Arg4>(arg4)}; 02424 } 02425 02426 /** 02427 * A convenience function to make Callback::CallbackArg objects 02428 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02429 * is exhausted and the system throws in that case (this exception 02430 * will not be thrown if the library has been installed using the 02431 * --with-glib-memory-slices-no-compat configuration option: instead 02432 * glib will terminate the program if it is unable to obtain memory 02433 * from the operating system). It will also throw if the copy 02434 * constructor of a bound argument throws and it is not a reference 02435 * argument. 02436 */ 02437 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02438 class BoundArg4, class BoundArg5, class... FreeArgs> 02439 CallbackArg<FreeArgs...>* make(T& t, 02440 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02441 BoundArg4, BoundArg5, FreeArgs...), 02442 BoundArg1 arg1, 02443 BoundArg2 arg2, 02444 BoundArg3 arg3, 02445 BoundArg4 arg4, 02446 BoundArg5 arg5) { 02447 return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3, 02448 BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5}; 02449 } 02450 02451 /** 02452 * DEPRECATED: use Callback::make_ref() instead. 02453 * 02454 * An alternative function to make Callback::CallbackArg objects, 02455 * which is for use where a target function receives an argument of 02456 * class type by value which is to be a bound argument, so the 02457 * compiler is not able to carry out copy elision when constructing 02458 * the callback object. 02459 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02460 * is exhausted and the system throws in that case (this exception 02461 * will not be thrown if the library has been installed using the 02462 * --with-glib-memory-slices-no-compat configuration option: instead 02463 * glib will terminate the program if it is unable to obtain memory 02464 * from the operating system). It will also throw if the copy 02465 * constructor of a bound argument throws and it is not a reference 02466 * argument. 02467 */ 02468 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02469 class BoundArg4, class BoundArg5, class... FreeArgs> 02470 CallbackArg<FreeArgs...>* make_val(T& t, 02471 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02472 BoundArg4, BoundArg5, FreeArgs...), 02473 const BoundArg1& arg1, 02474 const BoundArg2& arg2, 02475 const BoundArg3& arg3, 02476 const BoundArg4& arg4, 02477 const BoundArg5& arg5) { 02478 return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3, 02479 BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5}; 02480 } 02481 02482 /** 02483 * An alternative function to make Callback::CallbackArg objects, 02484 * which is for use where a target function either receives a class 02485 * type bound argument by value, or receives a bound argument by 02486 * reference to const in a case where the generated CallbackArg object 02487 * is to store a copy of that argument instead of just keeping a 02488 * reference. 02489 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02490 * is exhausted and the system throws in that case (this exception 02491 * will not be thrown if the library has been installed using the 02492 * --with-glib-memory-slices-no-compat configuration option: instead 02493 * glib will terminate the program if it is unable to obtain memory 02494 * from the operating system). It will also throw if the copy or move 02495 * constructor of a bound argument throws and it is not a reference 02496 * argument. 02497 * 02498 * Since 2.0.0-rc3 02499 */ 02500 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5, 02501 class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs> 02502 CallbackArg<FreeArgs...>* make_ref(T& t, 02503 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02504 BoundArg4, BoundArg5, FreeArgs...), 02505 Arg1&& arg1, 02506 Arg2&& arg2, 02507 Arg3&& arg3, 02508 Arg4&& arg4, 02509 Arg5&& arg5) { 02510 return new Callback5<true, T, BoundArg1, BoundArg2, BoundArg3, 02511 BoundArg4, BoundArg5, FreeArgs...>{t, func, 02512 std::forward<Arg1>(arg1), 02513 std::forward<Arg2>(arg2), 02514 std::forward<Arg3>(arg3), 02515 std::forward<Arg4>(arg4), 02516 std::forward<Arg5>(arg5)}; 02517 } 02518 02519 /* const versions, for binding to const methods */ 02520 02521 /** 02522 * A convenience function to make Callback::CallbackArg objects 02523 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02524 * is exhausted and the system throws in that case. This exception 02525 * will not be thrown if the library has been installed using the 02526 * --with-glib-memory-slices-no-compat configuration option (instead 02527 * glib will terminate the program if it is unable to obtain memory 02528 * from the operating system). 02529 */ 02530 template <class T, class... FreeArgs> 02531 CallbackArg<FreeArgs...>* make(const T& t, 02532 void (T::*func)(FreeArgs...) const) { 02533 return new Callback0_const<T, FreeArgs...>{t, func}; 02534 } 02535 02536 /** 02537 * DEPRECATED. 02538 * 02539 * Since this function constructs a callback which does not take a 02540 * bound argument, it is a synonym for make() (the two are identical). 02541 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02542 * is exhausted and the system throws in that case. This exception 02543 * will not be thrown if the library has been installed using the 02544 * --with-glib-memory-slices-no-compat configuration option (instead 02545 * glib will terminate the program if it is unable to obtain memory 02546 * from the operating system). 02547 */ 02548 template <class T, class... FreeArgs> 02549 CallbackArg<FreeArgs...>* make_val(const T& t, 02550 void (T::*func)(FreeArgs...) const) { 02551 return new Callback0_const<T, FreeArgs...>{t, func}; 02552 } 02553 02554 /** 02555 * Since this function constructs a callback which does not take a 02556 * bound argument, it is a synonym for make() (the two are identical). 02557 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02558 * is exhausted and the system throws in that case. This exception 02559 * will not be thrown if the library has been installed using the 02560 * --with-glib-memory-slices-no-compat configuration option (instead 02561 * glib will terminate the program if it is unable to obtain memory 02562 * from the operating system). 02563 * 02564 * Since 2.0.0-rc3 02565 */ 02566 template <class T, class... FreeArgs> 02567 CallbackArg<FreeArgs...>* make_ref(const T& t, 02568 void (T::*func)(FreeArgs...) const) { 02569 return new Callback0_const<T, FreeArgs...>{t, func}; 02570 } 02571 02572 /** 02573 * A convenience function to make Callback::CallbackArg objects 02574 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02575 * is exhausted and the system throws in that case (this exception 02576 * will not be thrown if the library has been installed using the 02577 * --with-glib-memory-slices-no-compat configuration option: instead 02578 * glib will terminate the program if it is unable to obtain memory 02579 * from the operating system). It will also throw if the copy 02580 * constructor of a bound argument throws and it is not a reference 02581 * argument. 02582 */ 02583 template <class T, class BoundArg, class... FreeArgs> 02584 CallbackArg<FreeArgs...>* make(const T& t, 02585 void (T::*func)(BoundArg, FreeArgs...) const, 02586 BoundArg arg) { 02587 return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg}; 02588 } 02589 02590 /** 02591 * DEPRECATED: use Callback::make_ref() instead. 02592 * 02593 * An alternative function to make Callback::CallbackArg objects, 02594 * which is for use where a target function receives an argument of 02595 * class type by value which is to be a bound argument, so the 02596 * compiler is not able to carry out copy elision when constructing 02597 * the callback object. 02598 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02599 * is exhausted and the system throws in that case (this exception 02600 * will not be thrown if the library has been installed using the 02601 * --with-glib-memory-slices-no-compat configuration option: instead 02602 * glib will terminate the program if it is unable to obtain memory 02603 * from the operating system). It will also throw if the copy 02604 * constructor of a bound argument throws and it is not a reference 02605 * argument. 02606 */ 02607 template <class T, class BoundArg, class... FreeArgs> 02608 CallbackArg<FreeArgs...>* make_val(const T& t, 02609 void (T::*func)(BoundArg, FreeArgs...) const, 02610 const BoundArg& arg) { 02611 return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg}; 02612 } 02613 02614 /** 02615 * An alternative function to make Callback::CallbackArg objects, 02616 * which is for use where a target function either receives a class 02617 * type bound argument by value, or receives a bound argument by 02618 * reference to const in a case where the generated CallbackArg object 02619 * is to store a copy of that argument instead of just keeping a 02620 * reference. 02621 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02622 * is exhausted and the system throws in that case (this exception 02623 * will not be thrown if the library has been installed using the 02624 * --with-glib-memory-slices-no-compat configuration option: instead 02625 * glib will terminate the program if it is unable to obtain memory 02626 * from the operating system). It will also throw if the copy or move 02627 * constructor of a bound argument throws and it is not a reference 02628 * argument. 02629 * 02630 * Since 2.0.0-rc3 02631 */ 02632 template <class T, class BoundArg, class Arg, class... FreeArgs> 02633 CallbackArg<FreeArgs...>* make_ref(const T& t, 02634 void (T::*func)(BoundArg, FreeArgs...) const, 02635 Arg&& arg) { 02636 return new Callback1_const<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)}; 02637 } 02638 02639 /** 02640 * A convenience function to make Callback::CallbackArg objects 02641 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02642 * is exhausted and the system throws in that case (this exception 02643 * will not be thrown if the library has been installed using the 02644 * --with-glib-memory-slices-no-compat configuration option: instead 02645 * glib will terminate the program if it is unable to obtain memory 02646 * from the operating system). It will also throw if the copy 02647 * constructor of a bound argument throws and it is not a reference 02648 * argument. 02649 */ 02650 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs> 02651 CallbackArg<FreeArgs...>* make(const T& t, 02652 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, 02653 BoundArg1 arg1, 02654 BoundArg2 arg2) { 02655 return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2}; 02656 } 02657 02658 /** 02659 * DEPRECATED: use Callback::make_ref() instead. 02660 * 02661 * An alternative function to make Callback::CallbackArg objects, 02662 * which is for use where a target function receives an argument of 02663 * class type by value which is to be a bound argument, so the 02664 * compiler is not able to carry out copy elision when constructing 02665 * the callback object. 02666 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02667 * is exhausted and the system throws in that case (this exception 02668 * will not be thrown if the library has been installed using the 02669 * --with-glib-memory-slices-no-compat configuration option: instead 02670 * glib will terminate the program if it is unable to obtain memory 02671 * from the operating system). It will also throw if the copy 02672 * constructor of a bound argument throws and it is not a reference 02673 * argument. 02674 */ 02675 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs> 02676 CallbackArg<FreeArgs...>* make_val(const T& t, 02677 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, 02678 const BoundArg1& arg1, 02679 const BoundArg2& arg2) { 02680 return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2}; 02681 } 02682 02683 /** 02684 * An alternative function to make Callback::CallbackArg objects, 02685 * which is for use where a target function either receives a class 02686 * type bound argument by value, or receives a bound argument by 02687 * reference to const in a case where the generated CallbackArg object 02688 * is to store a copy of that argument instead of just keeping a 02689 * reference. 02690 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02691 * is exhausted and the system throws in that case (this exception 02692 * will not be thrown if the library has been installed using the 02693 * --with-glib-memory-slices-no-compat configuration option: instead 02694 * glib will terminate the program if it is unable to obtain memory 02695 * from the operating system). It will also throw if the copy or move 02696 * constructor of a bound argument throws and it is not a reference 02697 * argument. 02698 * 02699 * Since 2.0.0-rc3 02700 */ 02701 template <class T, class BoundArg1, class BoundArg2, 02702 class Arg1, class Arg2, class... FreeArgs> 02703 CallbackArg<FreeArgs...>* make_ref(const T& t, 02704 void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, 02705 Arg1&& arg1, 02706 Arg2&& arg2) { 02707 return new Callback2_const<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, 02708 std::forward<Arg1>(arg1), 02709 std::forward<Arg2>(arg2)}; 02710 } 02711 02712 /** 02713 * A convenience function to make Callback::CallbackArg objects 02714 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02715 * is exhausted and the system throws in that case (this exception 02716 * will not be thrown if the library has been installed using the 02717 * --with-glib-memory-slices-no-compat configuration option: instead 02718 * glib will terminate the program if it is unable to obtain memory 02719 * from the operating system). It will also throw if the copy 02720 * constructor of a bound argument throws and it is not a reference 02721 * argument. 02722 */ 02723 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 02724 CallbackArg<FreeArgs...>* make(const T& t, 02725 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, 02726 BoundArg1 arg1, 02727 BoundArg2 arg2, 02728 BoundArg3 arg3) { 02729 return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3}; 02730 } 02731 02732 /** 02733 * DEPRECATED: use Callback::make_ref() instead. 02734 * 02735 * An alternative function to make Callback::CallbackArg objects, 02736 * which is for use where a target function receives an argument of 02737 * class type by value which is to be a bound argument, so the 02738 * compiler is not able to carry out copy elision when constructing 02739 * the callback object. 02740 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02741 * is exhausted and the system throws in that case (this exception 02742 * will not be thrown if the library has been installed using the 02743 * --with-glib-memory-slices-no-compat configuration option: instead 02744 * glib will terminate the program if it is unable to obtain memory 02745 * from the operating system). It will also throw if the copy 02746 * constructor of a bound argument throws and it is not a reference 02747 * argument. 02748 */ 02749 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 02750 CallbackArg<FreeArgs...>* make_val(const T& t, 02751 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, 02752 const BoundArg1& arg1, 02753 const BoundArg2& arg2, 02754 const BoundArg3& arg3) { 02755 return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3}; 02756 } 02757 02758 /** 02759 * An alternative function to make Callback::CallbackArg objects, 02760 * which is for use where a target function either receives a class 02761 * type bound argument by value, or receives a bound argument by 02762 * reference to const in a case where the generated CallbackArg object 02763 * is to store a copy of that argument instead of just keeping a 02764 * reference. 02765 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02766 * is exhausted and the system throws in that case (this exception 02767 * will not be thrown if the library has been installed using the 02768 * --with-glib-memory-slices-no-compat configuration option: instead 02769 * glib will terminate the program if it is unable to obtain memory 02770 * from the operating system). It will also throw if the copy or move 02771 * constructor of a bound argument throws and it is not a reference 02772 * argument. 02773 * 02774 * Since 2.0.0-rc3 02775 */ 02776 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02777 class Arg1, class Arg2, class Arg3, class... FreeArgs> 02778 CallbackArg<FreeArgs...>* make_ref(const T& t, 02779 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, 02780 Arg1&& arg1, 02781 Arg2&& arg2, 02782 Arg3&& arg3) { 02783 return new Callback3_const<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, 02784 std::forward<Arg1>(arg1), 02785 std::forward<Arg2>(arg2), 02786 std::forward<Arg3>(arg3)}; 02787 } 02788 02789 /** 02790 * A convenience function to make Callback::CallbackArg objects 02791 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02792 * is exhausted and the system throws in that case (this exception 02793 * will not be thrown if the library has been installed using the 02794 * --with-glib-memory-slices-no-compat configuration option: instead 02795 * glib will terminate the program if it is unable to obtain memory 02796 * from the operating system). It will also throw if the copy 02797 * constructor of a bound argument throws and it is not a reference 02798 * argument. 02799 */ 02800 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02801 class BoundArg4, class... FreeArgs> 02802 CallbackArg<FreeArgs...>* make(const T& t, 02803 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02804 BoundArg4, FreeArgs...) const, 02805 BoundArg1 arg1, 02806 BoundArg2 arg2, 02807 BoundArg3 arg3, 02808 BoundArg4 arg4) { 02809 return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3, 02810 BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4}; 02811 } 02812 02813 /** 02814 * DEPRECATED: use Callback::make_ref() instead. 02815 * 02816 * An alternative function to make Callback::CallbackArg objects, 02817 * which is for use where a target function receives an argument of 02818 * class type by value which is to be a bound argument, so the 02819 * compiler is not able to carry out copy elision when constructing 02820 * the callback object. 02821 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02822 * is exhausted and the system throws in that case (this exception 02823 * will not be thrown if the library has been installed using the 02824 * --with-glib-memory-slices-no-compat configuration option: instead 02825 * glib will terminate the program if it is unable to obtain memory 02826 * from the operating system). It will also throw if the copy 02827 * constructor of a bound argument throws and it is not a reference 02828 * argument. 02829 */ 02830 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02831 class BoundArg4, class... FreeArgs> 02832 CallbackArg<FreeArgs...>* make_val(const T& t, 02833 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02834 BoundArg4, FreeArgs...) const, 02835 const BoundArg1& arg1, 02836 const BoundArg2& arg2, 02837 const BoundArg3& arg3, 02838 const BoundArg4& arg4) { 02839 return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3, 02840 BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4}; 02841 } 02842 02843 /** 02844 * An alternative function to make Callback::CallbackArg objects, 02845 * which is for use where a target function either receives a class 02846 * type bound argument by value, or receives a bound argument by 02847 * reference to const in a case where the generated CallbackArg object 02848 * is to store a copy of that argument instead of just keeping a 02849 * reference. 02850 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02851 * is exhausted and the system throws in that case (this exception 02852 * will not be thrown if the library has been installed using the 02853 * --with-glib-memory-slices-no-compat configuration option: instead 02854 * glib will terminate the program if it is unable to obtain memory 02855 * from the operating system). It will also throw if the copy or move 02856 * constructor of a bound argument throws and it is not a reference 02857 * argument. 02858 * 02859 * Since 2.0.0-rc3 02860 */ 02861 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, 02862 class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs> 02863 CallbackArg<FreeArgs...>* make_ref(const T& t, 02864 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02865 BoundArg4, FreeArgs...) const, 02866 Arg1&& arg1, 02867 Arg2&& arg2, 02868 Arg3&& arg3, 02869 Arg4&& arg4) { 02870 return new Callback4_const<true, T, BoundArg1, BoundArg2, BoundArg3, 02871 BoundArg4, FreeArgs...>{t, func, 02872 std::forward<Arg1>(arg1), 02873 std::forward<Arg2>(arg2), 02874 std::forward<Arg3>(arg3), 02875 std::forward<Arg4>(arg4)}; 02876 } 02877 02878 /** 02879 * A convenience function to make Callback::CallbackArg objects 02880 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02881 * is exhausted and the system throws in that case (this exception 02882 * will not be thrown if the library has been installed using the 02883 * --with-glib-memory-slices-no-compat configuration option: instead 02884 * glib will terminate the program if it is unable to obtain memory 02885 * from the operating system). It will also throw if the copy 02886 * constructor of a bound argument throws and it is not a reference 02887 * argument. 02888 */ 02889 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02890 class BoundArg4, class BoundArg5, class... FreeArgs> 02891 CallbackArg<FreeArgs...>* make(const T& t, 02892 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02893 BoundArg4, BoundArg5, FreeArgs...) const, 02894 BoundArg1 arg1, 02895 BoundArg2 arg2, 02896 BoundArg3 arg3, 02897 BoundArg4 arg4, 02898 BoundArg5 arg5) { 02899 return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3, 02900 BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5}; 02901 } 02902 02903 /** 02904 * DEPRECATED: use Callback::make_ref() instead. 02905 * 02906 * An alternative function to make Callback::CallbackArg objects, 02907 * which is for use where a target function receives an argument of 02908 * class type by value which is to be a bound argument, so the 02909 * compiler is not able to carry out copy elision when constructing 02910 * the callback object. 02911 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02912 * is exhausted and the system throws in that case (this exception 02913 * will not be thrown if the library has been installed using the 02914 * --with-glib-memory-slices-no-compat configuration option: instead 02915 * glib will terminate the program if it is unable to obtain memory 02916 * from the operating system). It will also throw if the copy 02917 * constructor of a bound argument throws and it is not a reference 02918 * argument. 02919 */ 02920 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, 02921 class BoundArg4, class BoundArg5, class... FreeArgs> 02922 CallbackArg<FreeArgs...>* make_val(const T& t, 02923 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02924 BoundArg4, BoundArg5, FreeArgs...) const, 02925 const BoundArg1& arg1, 02926 const BoundArg2& arg2, 02927 const BoundArg3& arg3, 02928 const BoundArg4& arg4, 02929 const BoundArg5& arg5) { 02930 return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3, 02931 BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5}; 02932 } 02933 02934 /** 02935 * An alternative function to make Callback::CallbackArg objects, 02936 * which is for use where a target function either receives a class 02937 * type bound argument by value, or receives a bound argument by 02938 * reference to const in a case where the generated CallbackArg object 02939 * is to store a copy of that argument instead of just keeping a 02940 * reference. 02941 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02942 * is exhausted and the system throws in that case (this exception 02943 * will not be thrown if the library has been installed using the 02944 * --with-glib-memory-slices-no-compat configuration option: instead 02945 * glib will terminate the program if it is unable to obtain memory 02946 * from the operating system). It will also throw if the copy or move 02947 * constructor of a bound argument throws and it is not a reference 02948 * argument. 02949 * 02950 * Since 2.0.0-rc3 02951 */ 02952 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5, 02953 class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs> 02954 CallbackArg<FreeArgs...>* make_ref(const T& t, 02955 void (T::*func)(BoundArg1, BoundArg2, BoundArg3, 02956 BoundArg4, BoundArg5, FreeArgs...) const, 02957 Arg1&& arg1, 02958 Arg2&& arg2, 02959 Arg3&& arg3, 02960 Arg4&& arg4, 02961 Arg5&& arg5) { 02962 return new Callback5_const<true, T, BoundArg1, BoundArg2, BoundArg3, 02963 BoundArg4, BoundArg5, FreeArgs...>{t, func, 02964 std::forward<Arg1>(arg1), 02965 std::forward<Arg2>(arg2), 02966 std::forward<Arg3>(arg3), 02967 std::forward<Arg4>(arg4), 02968 std::forward<Arg5>(arg5)}; 02969 } 02970 02971 /* for static class methods and non-class functions */ 02972 02973 /** 02974 * A convenience function to make Callback::CallbackArg objects 02975 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02976 * is exhausted and the system throws in that case. This exception 02977 * will not be thrown if the library has been installed using the 02978 * --with-glib-memory-slices-no-compat configuration option (instead 02979 * glib will terminate the program if it is unable to obtain memory 02980 * from the operating system). 02981 */ 02982 template <class... FreeArgs> 02983 CallbackArg<FreeArgs...>* make(void (*func)(FreeArgs...)) { 02984 return new Callback0_static<FreeArgs...>{func}; 02985 } 02986 02987 /** 02988 * DEPRECATED. 02989 * 02990 * Since this function constructs a callback which does not take a 02991 * bound argument, it is a synonym for make() (the two are identical). 02992 * @exception std::bad_alloc It might throw std::bad_alloc if memory 02993 * is exhausted and the system throws in that case. This exception 02994 * will not be thrown if the library has been installed using the 02995 * --with-glib-memory-slices-no-compat configuration option (instead 02996 * glib will terminate the program if it is unable to obtain memory 02997 * from the operating system). 02998 */ 02999 template <class... FreeArgs> 03000 CallbackArg<FreeArgs...>* make_val(void (*func)(FreeArgs...)) { 03001 return new Callback0_static<FreeArgs...>{func}; 03002 } 03003 03004 /** 03005 * Since this function constructs a callback which does not take a 03006 * bound argument, it is a synonym for make() (the two are identical). 03007 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03008 * is exhausted and the system throws in that case. This exception 03009 * will not be thrown if the library has been installed using the 03010 * --with-glib-memory-slices-no-compat configuration option (instead 03011 * glib will terminate the program if it is unable to obtain memory 03012 * from the operating system). 03013 * 03014 * Since 2.0.0-rc3 03015 */ 03016 template <class... FreeArgs> 03017 CallbackArg<FreeArgs...>* make_ref(void (*func)(FreeArgs...)) { 03018 return new Callback0_static<FreeArgs...>{func}; 03019 } 03020 03021 /** 03022 * A convenience function to make Callback::CallbackArg objects 03023 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03024 * is exhausted and the system throws in that case (this exception 03025 * will not be thrown if the library has been installed using the 03026 * --with-glib-memory-slices-no-compat configuration option: instead 03027 * glib will terminate the program if it is unable to obtain memory 03028 * from the operating system). It will also throw if the copy 03029 * constructor of a bound argument throws and it is not a reference 03030 * argument. 03031 */ 03032 template <class BoundArg, class... FreeArgs> 03033 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg, FreeArgs...), 03034 BoundArg arg) { 03035 return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg}; 03036 } 03037 03038 /** 03039 * DEPRECATED: use Callback::make_ref() instead. 03040 * 03041 * An alternative function to make Callback::CallbackArg objects, 03042 * which is for use where a target function receives an argument of 03043 * class type by value which is to be a bound argument, so the 03044 * compiler is not able to carry out copy elision when constructing 03045 * the callback object. 03046 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03047 * is exhausted and the system throws in that case (this exception 03048 * will not be thrown if the library has been installed using the 03049 * --with-glib-memory-slices-no-compat configuration option: instead 03050 * glib will terminate the program if it is unable to obtain memory 03051 * from the operating system). It will also throw if the copy 03052 * constructor of a bound argument throws and it is not a reference 03053 * argument. 03054 */ 03055 template <class BoundArg, class... FreeArgs> 03056 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg, FreeArgs...), 03057 const BoundArg& arg) { 03058 return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg}; 03059 } 03060 03061 /** 03062 * An alternative function to make Callback::CallbackArg objects, 03063 * which is for use where a target function either receives a class 03064 * type bound argument by value, or receives a bound argument by 03065 * reference to const in a case where the generated CallbackArg object 03066 * is to store a copy of that argument instead of just keeping a 03067 * reference. 03068 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03069 * is exhausted and the system throws in that case (this exception 03070 * will not be thrown if the library has been installed using the 03071 * --with-glib-memory-slices-no-compat configuration option: instead 03072 * glib will terminate the program if it is unable to obtain memory 03073 * from the operating system). It will also throw if the copy or move 03074 * constructor of a bound argument throws and it is not a reference 03075 * argument. 03076 * 03077 * Since 2.0.0-rc3 03078 */ 03079 template <class BoundArg, class Arg, class... FreeArgs> 03080 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg, FreeArgs...), 03081 Arg&& arg) { 03082 return new Callback1_static<true, BoundArg, FreeArgs...>{func, std::forward<Arg>(arg)}; 03083 } 03084 03085 /** 03086 * A convenience function to make Callback::CallbackArg objects 03087 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03088 * is exhausted and the system throws in that case (this exception 03089 * will not be thrown if the library has been installed using the 03090 * --with-glib-memory-slices-no-compat configuration option: instead 03091 * glib will terminate the program if it is unable to obtain memory 03092 * from the operating system). It will also throw if the copy 03093 * constructor of a bound argument throws and it is not a reference 03094 * argument. 03095 */ 03096 template <class BoundArg1, class BoundArg2, class... FreeArgs> 03097 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, FreeArgs...), 03098 BoundArg1 arg1, 03099 BoundArg2 arg2) { 03100 return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2}; 03101 } 03102 03103 /** 03104 * DEPRECATED: use Callback::make_ref() instead. 03105 * 03106 * An alternative function to make Callback::CallbackArg objects, 03107 * which is for use where a target function receives an argument of 03108 * class type by value which is to be a bound argument, so the 03109 * compiler is not able to carry out copy elision when constructing 03110 * the callback object. 03111 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03112 * is exhausted and the system throws in that case (this exception 03113 * will not be thrown if the library has been installed using the 03114 * --with-glib-memory-slices-no-compat configuration option: instead 03115 * glib will terminate the program if it is unable to obtain memory 03116 * from the operating system). It will also throw if the copy 03117 * constructor of a bound argument throws and it is not a reference 03118 * argument. 03119 */ 03120 template <class BoundArg1, class BoundArg2, class... FreeArgs> 03121 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, FreeArgs...), 03122 const BoundArg1& arg1, 03123 const BoundArg2& arg2) { 03124 return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2}; 03125 } 03126 03127 /** 03128 * An alternative function to make Callback::CallbackArg objects, 03129 * which is for use where a target function either receives a class 03130 * type bound argument by value, or receives a bound argument by 03131 * reference to const in a case where the generated CallbackArg object 03132 * is to store a copy of that argument instead of just keeping a 03133 * reference. 03134 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03135 * is exhausted and the system throws in that case (this exception 03136 * will not be thrown if the library has been installed using the 03137 * --with-glib-memory-slices-no-compat configuration option: instead 03138 * glib will terminate the program if it is unable to obtain memory 03139 * from the operating system). It will also throw if the copy or move 03140 * constructor of a bound argument throws and it is not a reference 03141 * argument. 03142 * 03143 * Since 2.0.0-rc3 03144 */ 03145 template <class BoundArg1, class BoundArg2, class Arg1, class Arg2, class... FreeArgs> 03146 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, FreeArgs...), 03147 Arg1&& arg1, 03148 Arg2&& arg2) { 03149 return new Callback2_static<true, BoundArg1, BoundArg2, FreeArgs...>{func, 03150 std::forward<Arg1>(arg1), 03151 std::forward<Arg2>(arg2)}; 03152 } 03153 03154 /** 03155 * A convenience function to make Callback::CallbackArg objects 03156 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03157 * is exhausted and the system throws in that case (this exception 03158 * will not be thrown if the library has been installed using the 03159 * --with-glib-memory-slices-no-compat configuration option: instead 03160 * glib will terminate the program if it is unable to obtain memory 03161 * from the operating system). It will also throw if the copy 03162 * constructor of a bound argument throws and it is not a reference 03163 * argument. 03164 */ 03165 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 03166 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 03167 BoundArg1 arg1, 03168 BoundArg2 arg2, 03169 BoundArg3 arg3) { 03170 return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3}; 03171 } 03172 03173 /** 03174 * DEPRECATED: use Callback::make_ref() instead. 03175 * 03176 * An alternative function to make Callback::CallbackArg objects, 03177 * which is for use where a target function receives an argument of 03178 * class type by value which is to be a bound argument, so the 03179 * compiler is not able to carry out copy elision when constructing 03180 * the callback object. 03181 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03182 * is exhausted and the system throws in that case (this exception 03183 * will not be thrown if the library has been installed using the 03184 * --with-glib-memory-slices-no-compat configuration option: instead 03185 * glib will terminate the program if it is unable to obtain memory 03186 * from the operating system). It will also throw if the copy 03187 * constructor of a bound argument throws and it is not a reference 03188 * argument. 03189 */ 03190 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs> 03191 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 03192 const BoundArg1& arg1, 03193 const BoundArg2& arg2, 03194 const BoundArg3& arg3) { 03195 return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3}; 03196 } 03197 03198 /** 03199 * An alternative function to make Callback::CallbackArg objects, 03200 * which is for use where a target function either receives a class 03201 * type bound argument by value, or receives a bound argument by 03202 * reference to const in a case where the generated CallbackArg object 03203 * is to store a copy of that argument instead of just keeping a 03204 * reference. 03205 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03206 * is exhausted and the system throws in that case (this exception 03207 * will not be thrown if the library has been installed using the 03208 * --with-glib-memory-slices-no-compat configuration option: instead 03209 * glib will terminate the program if it is unable to obtain memory 03210 * from the operating system). It will also throw if the copy or move 03211 * constructor of a bound argument throws and it is not a reference 03212 * argument. 03213 * 03214 * Since 2.0.0-rc3 03215 */ 03216 template <class BoundArg1, class BoundArg2, class BoundArg3, 03217 class Arg1, class Arg2, class Arg3, class... FreeArgs> 03218 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), 03219 Arg1&& arg1, 03220 Arg2&& arg2, 03221 Arg3&& arg3) { 03222 return new Callback3_static<true, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, 03223 std::forward<Arg1>(arg1), 03224 std::forward<Arg2>(arg2), 03225 std::forward<Arg3>(arg3)}; 03226 } 03227 03228 /** 03229 * A convenience function to make Callback::CallbackArg objects 03230 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03231 * is exhausted and the system throws in that case (this exception 03232 * will not be thrown if the library has been installed using the 03233 * --with-glib-memory-slices-no-compat configuration option: instead 03234 * glib will terminate the program if it is unable to obtain memory 03235 * from the operating system). It will also throw if the copy 03236 * constructor of a bound argument throws and it is not a reference 03237 * argument. 03238 */ 03239 template <class BoundArg1, class BoundArg2, class BoundArg3, 03240 class BoundArg4, class... FreeArgs> 03241 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03242 BoundArg4, FreeArgs...), 03243 BoundArg1 arg1, 03244 BoundArg2 arg2, 03245 BoundArg3 arg3, 03246 BoundArg4 arg4) { 03247 return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3, 03248 BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4}; 03249 } 03250 03251 /** 03252 * DEPRECATED: use Callback::make_ref() instead. 03253 * 03254 * An alternative function to make Callback::CallbackArg objects, 03255 * which is for use where a target function receives an argument of 03256 * class type by value which is to be a bound argument, so the 03257 * compiler is not able to carry out copy elision when constructing 03258 * the callback object. 03259 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03260 * is exhausted and the system throws in that case (this exception 03261 * will not be thrown if the library has been installed using the 03262 * --with-glib-memory-slices-no-compat configuration option: instead 03263 * glib will terminate the program if it is unable to obtain memory 03264 * from the operating system). It will also throw if the copy 03265 * constructor of a bound argument throws and it is not a reference 03266 * argument. 03267 */ 03268 template <class BoundArg1, class BoundArg2, class BoundArg3, 03269 class BoundArg4, class... FreeArgs> 03270 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03271 BoundArg4, FreeArgs...), 03272 const BoundArg1& arg1, 03273 const BoundArg2& arg2, 03274 const BoundArg3& arg3, 03275 const BoundArg4& arg4) { 03276 return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3, 03277 BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4}; 03278 } 03279 03280 /** 03281 * An alternative function to make Callback::CallbackArg objects, 03282 * which is for use where a target function either receives a class 03283 * type bound argument by value, or receives a bound argument by 03284 * reference to const in a case where the generated CallbackArg object 03285 * is to store a copy of that argument instead of just keeping a 03286 * reference. 03287 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03288 * is exhausted and the system throws in that case (this exception 03289 * will not be thrown if the library has been installed using the 03290 * --with-glib-memory-slices-no-compat configuration option: instead 03291 * glib will terminate the program if it is unable to obtain memory 03292 * from the operating system). It will also throw if the copy or move 03293 * constructor of a bound argument throws and it is not a reference 03294 * argument. 03295 * 03296 * Since 2.0.0-rc3 03297 */ 03298 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, 03299 class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs> 03300 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03301 BoundArg4, FreeArgs...), 03302 Arg1&& arg1, 03303 Arg2&& arg2, 03304 Arg3&& arg3, 03305 Arg4&& arg4) { 03306 return new Callback4_static<true, BoundArg1, BoundArg2, BoundArg3, 03307 BoundArg4, FreeArgs...>{func, 03308 std::forward<Arg1>(arg1), 03309 std::forward<Arg2>(arg2), 03310 std::forward<Arg3>(arg3), 03311 std::forward<Arg4>(arg4)}; 03312 } 03313 03314 /** 03315 * A convenience function to make Callback::CallbackArg objects 03316 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03317 * is exhausted and the system throws in that case (this exception 03318 * will not be thrown if the library has been installed using the 03319 * --with-glib-memory-slices-no-compat configuration option: instead 03320 * glib will terminate the program if it is unable to obtain memory 03321 * from the operating system). It will also throw if the copy 03322 * constructor of a bound argument throws and it is not a reference 03323 * argument. 03324 */ 03325 template <class BoundArg1, class BoundArg2, class BoundArg3, 03326 class BoundArg4, class BoundArg5, class... FreeArgs> 03327 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03328 BoundArg4, BoundArg5, FreeArgs...), 03329 BoundArg1 arg1, 03330 BoundArg2 arg2, 03331 BoundArg3 arg3, 03332 BoundArg4 arg4, 03333 BoundArg5 arg5) { 03334 return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3, 03335 BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5}; 03336 } 03337 03338 /** 03339 * DEPRECATED: use Callback::make_ref() instead. 03340 * 03341 * An alternative function to make Callback::CallbackArg objects, 03342 * which is for use where a target function receives an argument of 03343 * class type by value which is to be a bound argument, so the 03344 * compiler is not able to carry out copy elision when constructing 03345 * the callback object. 03346 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03347 * is exhausted and the system throws in that case (this exception 03348 * will not be thrown if the library has been installed using the 03349 * --with-glib-memory-slices-no-compat configuration option: instead 03350 * glib will terminate the program if it is unable to obtain memory 03351 * from the operating system). It will also throw if the copy 03352 * constructor of a bound argument throws and it is not a reference 03353 * argument. 03354 */ 03355 template <class BoundArg1, class BoundArg2, class BoundArg3, 03356 class BoundArg4, class BoundArg5, class... FreeArgs> 03357 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03358 BoundArg4, BoundArg5, FreeArgs...), 03359 const BoundArg1& arg1, 03360 const BoundArg2& arg2, 03361 const BoundArg3& arg3, 03362 const BoundArg4& arg4, 03363 const BoundArg5& arg5) { 03364 return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3, 03365 BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5}; 03366 } 03367 03368 /** 03369 * An alternative function to make Callback::CallbackArg objects, 03370 * which is for use where a target function either receives a class 03371 * type bound argument by value, or receives a bound argument by 03372 * reference to const in a case where the generated CallbackArg object 03373 * is to store a copy of that argument instead of just keeping a 03374 * reference. 03375 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03376 * is exhausted and the system throws in that case (this exception 03377 * will not be thrown if the library has been installed using the 03378 * --with-glib-memory-slices-no-compat configuration option: instead 03379 * glib will terminate the program if it is unable to obtain memory 03380 * from the operating system). It will also throw if the copy or move 03381 * constructor of a bound argument throws and it is not a reference 03382 * argument. 03383 * 03384 * Since 2.0.0-rc3 03385 */ 03386 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5, 03387 class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs> 03388 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, 03389 BoundArg4, BoundArg5, FreeArgs...), 03390 Arg1&& arg1, 03391 Arg2&& arg2, 03392 Arg3&& arg3, 03393 Arg4&& arg4, 03394 Arg5&& arg5) { 03395 return new Callback5_static<true, BoundArg1, BoundArg2, BoundArg3, 03396 BoundArg4, BoundArg5, FreeArgs...>{func, 03397 std::forward<Arg1>(arg1), 03398 std::forward<Arg2>(arg2), 03399 std::forward<Arg3>(arg3), 03400 std::forward<Arg4>(arg4), 03401 std::forward<Arg5>(arg5)}; 03402 } 03403 03404 /* for std::function objects */ 03405 03406 /** 03407 * A convenience function to make Callback::CallbackArg objects from 03408 * std::function objects. 03409 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03410 * is exhausted and the system throws in that case (this exception 03411 * will not be thrown if the library has been installed using the 03412 * --with-glib-memory-slices-no-compat configuration option: instead 03413 * glib will terminate the program if it is unable to obtain memory 03414 * from the operating system). It will also throw if the copy 03415 * constructor of a bound argument throws and it is not a reference 03416 * argument. 03417 */ 03418 template <class... FreeArgs> 03419 CallbackArg<FreeArgs...>* make(const std::function<void(FreeArgs...)>& f) { 03420 return new Callback_function<FreeArgs...>{f}; 03421 } 03422 03423 /** 03424 * DEPRECATED. 03425 * 03426 * A convenience function to make Callback::Callback objects from 03427 * std::function objects. Since this function takes no bound argument 03428 * (and bound arguments are bound into the std::function object), it 03429 * is a synonym for make() (the two are identical). 03430 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03431 * is exhausted and the system throws in that case (this exception 03432 * will not be thrown if the library has been installed using the 03433 * --with-glib-memory-slices-no-compat configuration option: instead 03434 * glib will terminate the program if it is unable to obtain memory 03435 * from the operating system). It will also throw if the copy 03436 * constructor of a bound argument throws and it is not a reference 03437 * argument. 03438 */ 03439 template <class... FreeArgs> 03440 CallbackArg<FreeArgs...>* make_val(const std::function<void(FreeArgs...)>& f) { 03441 return new Callback_function<FreeArgs...>{f}; 03442 } 03443 03444 /** 03445 * A convenience function to make Callback::Callback objects from 03446 * std::function objects. Since this function takes no bound argument 03447 * (and bound arguments are bound into the std::function object), it 03448 * is a synonym for make() (the two are identical). 03449 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03450 * is exhausted and the system throws in that case (this exception 03451 * will not be thrown if the library has been installed using the 03452 * --with-glib-memory-slices-no-compat configuration option: instead 03453 * glib will terminate the program if it is unable to obtain memory 03454 * from the operating system). It will also throw if the copy 03455 * constructor of a bound argument throws and it is not a reference 03456 * argument. 03457 */ 03458 template <class... FreeArgs> 03459 CallbackArg<FreeArgs...>* make_ref(const std::function<void(FreeArgs...)>& f) { 03460 return new Callback_function<FreeArgs...>{f}; 03461 } 03462 03463 /** 03464 * A convenience function to make Callback::CallbackArg objects from 03465 * std::function objects. 03466 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03467 * is exhausted and the system throws in that case (this exception 03468 * will not be thrown if the library has been installed using the 03469 * --with-glib-memory-slices-no-compat configuration option: instead 03470 * glib will terminate the program if it is unable to obtain memory 03471 * from the operating system). It will also throw if the copy 03472 * constructor of a bound argument throws and it is not a reference 03473 * argument. 03474 */ 03475 template <class... FreeArgs> 03476 CallbackArg<FreeArgs...>* make(std::function<void(FreeArgs...)>&& f) { 03477 return new Callback_function<FreeArgs...>{std::move(f)}; 03478 } 03479 03480 /** 03481 * DEPRECATED. 03482 * 03483 * A convenience function to make Callback::Callback objects from 03484 * std::function objects. Since this function takes no bound argument 03485 * (and bound arguments are bound into the std::function object), it 03486 * is a synonym for make() (the two are identical). 03487 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03488 * is exhausted and the system throws in that case (this exception 03489 * will not be thrown if the library has been installed using the 03490 * --with-glib-memory-slices-no-compat configuration option: instead 03491 * glib will terminate the program if it is unable to obtain memory 03492 * from the operating system). It will also throw if the copy or move 03493 * constructor of a bound argument throws and it is not a reference 03494 * argument. 03495 */ 03496 template <class... FreeArgs> 03497 CallbackArg<FreeArgs...>* make_val(std::function<void(FreeArgs...)>&& f) { 03498 return new Callback_function<FreeArgs...>{std::move(f)}; 03499 } 03500 03501 /** 03502 * A convenience function to make Callback::Callback objects from 03503 * std::function objects. Since this function takes no bound argument 03504 * (and bound arguments are bound into the std::function object), it 03505 * is a synonym for make() (the two are identical). 03506 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03507 * is exhausted and the system throws in that case (this exception 03508 * will not be thrown if the library has been installed using the 03509 * --with-glib-memory-slices-no-compat configuration option: instead 03510 * glib will terminate the program if it is unable to obtain memory 03511 * from the operating system). It will also throw if the copy or move 03512 * constructor of a bound argument throws and it is not a reference 03513 * argument. 03514 */ 03515 template <class... FreeArgs> 03516 CallbackArg<FreeArgs...>* make_ref(std::function<void(FreeArgs...)>&& f) { 03517 return new Callback_function<FreeArgs...>{std::move(f)}; 03518 } 03519 03520 // This helper function to construct Callback_lambda objects could be 03521 // implemented as a further overload of Callback::make(). No best 03522 // match ambiguities would arise, because even when Callback::make() 03523 // is passed a function pointer without bound arguments, the overload 03524 // of Callback::make taking a function pointer (as opposed to a 03525 // generic callable object) would still comprise the best match. 03526 // However, to construct Callback_lambda objects, the unbound 03527 // arguments need to be specified by hand, which doesn't happen with 03528 // Callback::make() (it would only be necessary to specify an explicit 03529 // type where a mutable reference argument is to be bound to the 03530 // callback object). It seems to me to be less confusing to the user 03531 // therefore to have a separate Callback::lambda() helper function. 03532 // However, if you disagree please let me know. 03533 03534 // template parameter packs do not need to be placed last in the case 03535 // of function templates, as type deduction is available for the last 03536 // parameter: there is in fact no function parameter pack in 03537 // Callback::lambda() (function parameter packs must come last). 03538 /** 03539 * A convenience function to make Callback::CallbackArg objects from 03540 * C++11 lambda expressions, or from any other arbitrary callable 03541 * object. 03542 * @exception std::bad_alloc It might throw std::bad_alloc if memory 03543 * is exhausted and the system throws in that case. It will also 03544 * throw if the copy or move constructor of an object captured by the 03545 * lambda expression throws. 03546 * 03547 * Since 2.0.9 03548 */ 03549 template <class... FreeArgs, class Lambda> 03550 CallbackArg<FreeArgs...>* lambda(Lambda&& l) { 03551 return new Callback_lambda<Lambda, FreeArgs...>{std::forward<Lambda>(l)}; 03552 } 03553 03554 } // namespace Callback 03555 03556 class Releaser; 03557 03558 namespace Callback { 03559 03560 /** 03561 * Posts a callback for execution by a glib main loop. It is 03562 * thread-safe provided that (if glib < 2.32 is used) g_thread_init() 03563 * has been called. glib >= 2.32 does not require g_thread_init() to 03564 * be called. This function will not throw. 03565 * @param cb The callback object. Ownership is taken of this object, 03566 * and it will be deleted when it has been finished with. 03567 * @param priority The priority to be given to the callback in the 03568 * main loop. In ascending order of priorities, priorities are 03569 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 03570 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 03571 * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the 03572 * callback will appear in the event list in the main loop, not the 03573 * priority which the OS will adopt 03574 * @param context The glib main loop context in which the callback is 03575 * to be executed (the default of NULL will cause the callback to be 03576 * executed in the main program loop, and this is usually what is 03577 * wanted). 03578 * @note Cancellation of the receiving thread is blocked when the 03579 * callback executes. 03580 */ 03581 void post(const Callback* cb, gint priority = G_PRIORITY_DEFAULT_IDLE, 03582 GMainContext* context = 0); 03583 03584 /** 03585 * Posts a callback for execution by a glib main loop. It is 03586 * thread-safe provided that (if glib < 2.32 is used) g_thread_init() 03587 * has been called. glib >= 2.32 does not require g_thread_init() to 03588 * be called. This function will not throw. 03589 * @param cb The callback object. Ownership is taken of this object, 03590 * and it will be deleted when it has been finished with. 03591 * @param r A Releaser object for automatic disconnection of the 03592 * callback from the main loop. 03593 * @param priority The priority to be given to the callback in the 03594 * main loop. In ascending order of priorities, priorities are 03595 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 03596 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 03597 * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the 03598 * callback will appear in the event list in the main loop, not the 03599 * priority which the OS will adopt. 03600 * @param context The glib main loop context in which the callback is 03601 * to be executed (the default of NULL will cause the callback to be 03602 * executed in the main program loop, and this is usually what is 03603 * wanted). 03604 * @exception std::bad_alloc This function might throw std::bad_alloc 03605 * if memory is exhausted and the system throws in that case. If it 03606 * does so, the Callback object will be disposed of. 03607 * @exception Cgu::Thread::MutexError This method might throw 03608 * Cgu:Thread::MutexError if initialisation of the mutex in a 03609 * SafeEmitterArg object constructed by this method fails. If it does 03610 * so, the Callback object will be disposed of. (It is often not 03611 * worth checking for this exception, as it means either memory is 03612 * exhausted or pthread has run out of other resources to create new 03613 * mutexes.) 03614 * @note Cancellation of the receiving thread is blocked when the 03615 * callback executes. 03616 */ 03617 void post(const Callback* cb, Releaser& r, 03618 gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0); 03619 03620 } // namespace Callback 03621 03622 } // namespace Cgu 03623 03624 #endif