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