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