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