c++-gtk-utils
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
Cgu::Thread::TaskManager Class Reference

A thread-pool class for managing tasks in multi-threaded programs. More...

#include <c++-gtk-utils/task_manager.h>

Classes

class  IncHandle
 A scoped handle for exception safe incrementing of the maximum number of threads that a TaskManager object will run. More...
 

Public Types

enum  StopMode { wait_for_running, wait_for_all }
 

Public Member Functions

unsigned int get_max_threads () const
 
unsigned int get_min_threads () const
 
unsigned int get_used_threads () const
 
void set_max_threads (unsigned int max)
 
void change_max_threads (int delta)
 
unsigned int get_tasks () const
 
unsigned int get_idle_time () const
 
void set_idle_time (unsigned int idle)
 
bool get_blocking () const
 
void set_blocking (bool blocking)
 
StopMode get_stop_mode () const
 
void set_stop_mode (StopMode mode)
 
void stop_all ()
 
void add_task (const Callback::Callback *task)
 
void add_task (std::auto_ptr< const Callback::Callback > task, std::auto_ptr< const Callback::Callback > fail)
 
bool is_error () const
 
template<class Ret , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (T &t, Ret(T::*func)())
 
template<class Ret , class Arg1 , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (T &t, Ret(T::*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (T &t, Ret(T::*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, T &t, Ret(T::*func)())
 
template<class Ret , class Arg1 , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, T &t, Ret(T::*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, T &t, Ret(T::*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, T &t, Ret(T::*func)())
 
template<class Ret , class Arg1 , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, T &t, Ret(T::*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, T &t, Ret(T::*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (const T &t, Ret(T::*func)() const)
 
template<class Ret , class Arg1 , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (const T &t, Ret(T::*func)(Arg1) const, typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (const T &t, Ret(T::*func)(Arg1, Arg2) const, typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, const T &t, Ret(T::*func)() const)
 
template<class Ret , class Arg1 , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, const T &t, Ret(T::*func)(Arg1) const, typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, const T &t, Ret(T::*func)(Arg1, Arg2) const, typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, const T &t, Ret(T::*func)() const)
 
template<class Ret , class Arg1 , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, const T &t, Ret(T::*func)(Arg1) const, typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 , class T >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, const T &t, Ret(T::*func)(Arg1, Arg2) const, typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (Ret(*func)())
 
template<class Ret , class Arg1 >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (Ret(*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 >
Cgu::SharedLockPtr< Cgu::AsyncResult< Ret > > make_task_result (Ret(*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, Ret(*func)())
 
template<class Ret , class Arg1 >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, Ret(*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 >
void make_task_when_full (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, Cgu::Releaser *when_releaser, std::auto_ptr< const Cgu::Callback::Callback > fail, Cgu::Releaser *fail_releaser, gint priority, GMainContext *context, Ret(*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
template<class Ret >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, Ret(*func)())
 
template<class Ret , class Arg1 >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, Ret(*func)(Arg1), typename Cgu::Param< Arg1 >::ParamType arg1)
 
template<class Ret , class Arg1 , class Arg2 >
void make_task_when (std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > > when, GMainContext *context, Ret(*func)(Arg1, Arg2), typename Cgu::Param< Arg1 >::ParamType arg1, typename Cgu::Param< Arg2 >::ParamType arg2)
 
 TaskManager (unsigned int max=8, unsigned int min=0, unsigned int idle=10000, bool blocking=true, StopMode mode=TaskManager::wait_for_all)
 
 ~TaskManager ()
 

Static Public Member Functions

static unsigned int get_max_tasks ()
 

Detailed Description

A thread-pool class for managing tasks in multi-threaded programs.

See also
Cgu::Thread::Future Cgu::AsyncResult Cgu::AsyncQueueDispatch Cgu::AsyncChannel Cgu::Callback::post() Cgu::Thread::TaskManager::IncHandle

Cgu::Thread::Future operates on the principle of there being one worker thread per task. In some cases however, it may be better to have a limited pool of worker threads executing a larger number of tasks. This class implements this approach via a thread pool.

One common approach for thread pools of this kind is to set the maximum number of threads to the number of cores, or some number less than the number of cores, available on the local machine. How that can be determined is system specific (on linux it can be obtained by, for example, counting the 'processor' fields in /proc/cpuinfo or by using sysconf with the glibc extension for _SC_NPROCESSORS_ONLN). From version 2.36, glib has a g_get_num_processors() function. From gcc-4.7, C++11's std::thread::hardware_concurrency() static member function is also available.

Where the task needs to provide a result, two approaches can be adopted. First, the task callback can have a Cgu::AsyncResult object held by Cgu::SharedLockPtr (or by std::shared_ptr having a thread safe reference count) bound to it. Alternatively, a task can provide a result asynchronously to a glib main loop by calling Cgu::Callback::post() when it is ready to do so. From version 1.2.26, the TaskManager::make_task_result(), TaskManager::make_task_when() and TaskManager::make_task_when_full() convenience wrapper methods are provided which will set this up for you (including constructing appropriate task callbacks) for target functions which return a value. Tasks can add other tasks, enabling the composition of an arbitrary number of tasks to obtain a final result.

TaskManager objects do not provide thread cancellation. Thread cancellation is incompatible with the task-centred thread pool model. If task cancellation is wanted, use a Cgu::Thread::Future (or Cgu::Thread::Thread or Cgu::Thread::JoinableHandle) object instead, and have a dedicated thread for the cancelable task.

If glib < 2.32 is installed, g_thread_init() must be called before any TaskManager objects are constructed, which in turn means that with glib < 2.32 TaskManager objects may not be constructed as static objects in global namespace (that is, before g_thread_init() has been called in the program).

Any exceptions which propagate from a task will be consumed to protect the TaskManager object, and to detect whether this has happened there is a version of the TaskManager::add_task() method which takes a second argument comprising a 'fail' callback. If an exception propagates from the 'fail' callback that is also consumed and a g_critical() message issued. TaskManager::make_task_when_full() also provides for a 'fail' callback.

Tasks can be aborted by throwing Cgu::Thread::Exit (as well as any other exception). Where a task is managed by a TaskManager object, throwing Cgu::Thread::Exit will only terminate the task and not the thread on which it is running (and will cause the 'fail' callback to be executed, if there is one).

Any 'fail' callback passed to TaskManager::add_task() or TaskManager::make_task_when_full() must be fully bound. Whilst a task can pass error status to the 'fail' callback via shared data bound to both the task and the 'fail' callback (held by, say, a SharedLockPtr object), or a global error stack, 'fail' callbacks are generally best reserved for use with entirely unexpected exceptions, where the most reasonable course is to perform some orderly logging and shutdown. For handlable exceptions, in an asynchronous environment the best course is often to catch them and deal with them in the task itself and (where TaskManager::make_task_when_full() or TaskManager::make_task_when() is employed) return a value of the task function's return type indicating no result.

TaskManager objects have no copy constructor or assignment operator, as copying them would have no obvious semantic meaning. Whilst swapping or moving TaskManager objects would be meaningful, this is not implemented either because it would require an additional internal lock to be thread safe, and the circumstances in which moving or swapping would be useful are limited. Where a move option is wanted, a TaskManager object can be constructed on free store and held by std::auto_ptr.

Here is a compilable example of the calculator class referred to in the documentation on the AsyncResult but which uses a TaskManager object so that the calculator class can run more than one thread to service its calculations:

#include <vector>
#include <numeric>
#include <ostream>
#include <iostream>
#include <glib.h>
using namespace Cgu;
class Calcs {
static void mean_impl(const std::vector<double>& nums,
if (nums.empty()) res->set(0.0);
else res->set(std::accumulate(nums.begin(), nums.end(), 0.0)/nums.size());
}
// ... other calculation implementation methods here
public:
SharedLockPtr<AsyncResult<double> > mean(const std::vector<double>& nums) {
tm.add_task(Callback::make_ref(&mean_impl, nums, res));
return res;
}
// ... other calculation methods here
};
int main () {
g_thread_init(0);
Calcs calcs;
const double ar1[] = {1, 2, 8, 0};
const double ar2[] = {101, 53.7, 87, 1.2};
SharedLockPtr<AsyncResult<double> > res1 = calcs.mean(std::vector<double>(ar1, ar1 + 4));
SharedLockPtr<AsyncResult<double> > res2 = calcs.mean(std::vector<double>(ar2, ar2 + 4));
// ... do something else
std::cout << res1->get() << std::endl;
std::cout << res2->get() << std::endl;
}

The TaskManager::make_task_result(), TaskManager::make_task_when_full() and TaskManager::make_task_when() functions

From version 1.2.26 the TaskManager::make_task_result(), TaskManager::make_task_when() and TaskManager::make_task_when_full() convenience wrapper methods are provided, which construct a task from a target function returning a value by calling TaskManager::add_task() with an appropriate callback object. TaskManager::make_task_result() returns a Cgu::AsyncResult object held by Cgu::SharedLockPtr which will hold the result provided by the function; TaskManager::make_task_when() and TaskManager::make_task_when_full() execute a callback in a glib main loop when the task has completed by passing the callback the target function's return value. The wrappers therefore provide a similar interface to the one provided by Cgu::Thread::Future objects. These wrapper methods can make it easier to compose the results of a number of different tasks.

The wrapper methods can take a plain function, static member function or non-static member function as the target function, and can take up to two arguments. The arguments can be taken by the function by value or by reference to const, but not by reference to non-const (that would not be safe, and a compile error will be generated if that is attempted). In the case of a non-static member function, the referenced object whose member function is to be called must remain in existence until the task concerned has completed.

Copies of the objects to be passed to the target function as arguments are taken internally by the implementation to avoid dangling references. This copying of arguments takes place twice when make_task_result(), make_task_when() or make_task_when_full() is called and, if the target function does not take an argument by reference to const, once in the task thread when the task is dispatched. Therefore, if class objects are received by the target function as arguments, it is best for them to be constructed on free store and for the target function to receive them by pointer or by Cgu::SharedLockPtr.

Copying of the return value of the target function represented by the task may also take place. When a task completes, the return value will be stored, either in a Cgu::AsyncResult object (if TaskManager::make_task_result() is called) or for the purposes of executing the 'when' callback in a glib main loop (if TaskManager::make_task_when() or TaskManager::make_task_when_full() are called). This storage will therefore cause the return value type's assignment operator or copy constructor to be called once (unless, that is, the program is compiled under C++11 and that type has a move assignment operator or move constructor, in which case a move operation will be made). Note that a 'when' callback takes the stored return value by reference to const and so without any additional copying upon the 'when' callback being executed in the main loop.

Here is a compilable example of the calculator class using TaskManager::make_task_result():

#include <vector>
#include <numeric>
#include <ostream>
#include <iostream>
#include <glib.h>
using namespace Cgu;
class Calcs {
static double mean_impl(const std::vector<double>& nums) {
if (nums.empty()) return 0.0;
return std::accumulate(nums.begin(), nums.end(), 0.0)/nums.size());
}
// ... other calculation implementation methods here
public:
SharedLockPtr<AsyncResult<double> > mean(const std::vector<double>& nums) {
return tm.make_task_result(&Calcs::mean_impl, nums);
}
// ... other calculation methods here
};
int main () {
g_thread_init(0);
Calcs calcs;
const double ar1[] = {1, 2, 8, 0};
const double ar2[] = {101, 53.7, 87, 1.2};
SharedLockPtr<AsyncResult<double> > res1 = calcs.mean(std::vector<double>(ar1, ar1 + 4));
SharedLockPtr<AsyncResult<double> > res2 = calcs.mean(std::vector<double>(ar2, ar2 + 4));
// ... do something else
std::cout << res1->get() << std::endl;
std::cout << res2->get() << std::endl;
}

Here is a reimplementation, using TaskManager::make_task_when(), of the Number class example with get_primes() method given in the documentation for Cgu::Thread::Future:

class Numbers {
public:
std::vector<long> get_primes(int n); // calculates the first n primes
// and puts them in a vector
...
};
void print_primes(const std::vector<long>& result) {
for (std::vector<long>::const_iterator i = result.begin();
i != result.end();
++i)
std::cout << *i << std::endl;
}
Numbers obj;
// get the first 1,000 primes
using namespace Cgu;
std::auto_ptr<const Callback::CallbackArg<const std::vector<long>&> > when(
Callback::make(&print_primes)
);
0, // default main loop context
obj,
&Numbers::get_primes,
1000);

Where a task running on a TaskManager object is to block, the TaskManager::IncHandle scoped handle class can be used to increment the maximum number of threads running on the object's thread pool temporarily while blocking takes place, so as to enable another thread to keep a core active. This can be useful where a task is to 'join' on another task when composing tasks: and it is usually essential to increment the maximum thread count temporarily where a task is to block on one of its sub-tasks, to avoid any possibility of deadlock through thread starvation (thread starvation occurs where all threads on a thread pool are occupied by tasks blocking on sub-tasks which have still to run on the thread pool, and which cannot run because the maximum thread count has been reached). Here is a compilable example:

#include <iostream>
#include <ostream>
#include <utility>
#include <memory>
#include <glib.h>
using namespace Cgu;
// simulate a blocking operation, say from a server, with g_usleep()
int mult(int x, int y) {
g_usleep(100000);
return x * y;
}
int mult_with_inc(Thread::TaskManager* tm, const std::pair<int, int>& nums) {
// increment maximum thread count again before blocking in
// this task (pretend that some other task in the program
// may also want to run while both the parent task and this
// task block on mult())
return mult(nums.first, nums.second);
}
void print_res(GMainLoop* loop, const int& i) {
std::cout << i << std::endl;
g_main_loop_quit(loop);
}
int task(Thread::TaskManager* tm) {
// this task multiplies 'a' by 2 and 'b' by 3, and adds the products
int a = 10;
int b = 12;
// increment maximum thread count before launching sub-task and
// then blocking
// start a sub-task
SharedLockPtr<AsyncResult<int> > sub = tm->make_task_result(&mult_with_inc, tm, std::make_pair(a, 2));
int res = mult(b, 3)
return sub->get() + res;
}
int main(int argc, char* argv[]) {
g_thread_init(0);
Thread::TaskManager tm(1); // only one thread available unless blocking!
GMainLoop* loop = g_main_loop_new(0, true);
typedef std::auto_ptr<const Callback::CallbackArg<const int&> > When;
When when(Callback::make(&print_res, loop));
tm.make_task_when(when,
0, // default main loop
&task, &tm);
g_main_loop_run(loop);
}

An alternative to using TaskManager::IncHandle for sub-tasks is to run the sub-tasks on their own threads via Thread::Future.

Where a member function or ordinary function to be represented by a task is overloaded, this will cause difficulties in template type deduction when TaskManager::make_task_result(), TaskManager::make_task_when() or TaskManager::make_task_when_full() are called. Explicit disambiguation would be required, for example:

class Numbers {
public:
int calc(int i);
int calc(double d);
...
};
Numbers obj;
using namespace Cgu;
int i = 1;
double d = 2.0;
tm.make_task_result(obj, static_cast<int (Numbers::*)(int)>(&Numbers::calc), i);
tm.make_task_result(obj, static_cast<int (Numbers::*)(double)>(&Numbers::calc), d);

Rate limiting

Resources are not infinite and there is a hard limit to the number of tasks that a TaskManager object may have queued for execution at any one time. From version 1.2.42 the limit to the number of running and queued tasks may be obtained by calling the TaskManager::get_max_tasks() method (note that particularly on 32-bit systems it will in practice be impossible to reach this limit because of memory exhaustion: the value returned by that method represents the limit enforced by TaskManager irrespective of the actual available memory at the system or process level and any intervention of std::bad_alloc exceptions). If that limit is exceeded, the TaskManager::add_task() and TaskManager::make_task_* methods will throw std::length_error.

In practice however, on most systems such a large number of queued tasks (normally around 4,294,967,295 for 64-bit systems) is likely to be unfeasible and program logic constraints will be exceeded long before the limit is reached, even if available memory is not. In some usages therefore, some form of rate limiting may be needed to prevent a work-producing thread overwhelming a TaskManager object by continuously adding more tasks for execution than the object's throughput capacity is capable of dealing with, so pushing the number of unexecuted tasks to an excessive level.

TaskManager objects provide no built-in rate limiting (other than throwing the std::length_error exception referred to above). This is because there is no one-size-fits-all way of doing so. One common approach is to apply throttling to threads which add tasks by enforcing a wait in their thread of execution when the level of queued tasks reaches too high a level, so hindering their ability to add new ones. However this is counter productive where it is a task running on the TaskManager object which is adding the new tasks, particularly with a TaskManager object having only a few threads running in its pool. Another approach is to throw an exception when adding tasks which exceed a user-selectable level which is much lower than the value returned by TaskManager::get_max_tasks(), but this would make it more difficult to use the TaskManager with various container-based algorithms.

The best approach is for user code to provide its own rate limiting in cases where the way that that code is organised means that it could produce an excessive number of accumulating unexecuted tasks, possibly by applying delays when unexecuted tasks rise in number excessively, using timeouts with a glib main loop. This may be checked for by having code call the TaskManager::get_tasks() method before adding a significant batch of new tasks in order to test queue size, and if necessary postpone adding the new tasks until the size of the already accumulated tasks has reduced.

The Cgu::AsyncChannel class has a push() method which will block when a channel is full. That class can therefore be used for rate limiting function objects pushed onto the channel in cases where that is an appropriate alternative solution to TaskManager.

Member Enumeration Documentation

Enumerator
wait_for_running 
wait_for_all 

Constructor & Destructor Documentation

Cgu::Thread::TaskManager::TaskManager ( unsigned int  max = 8,
unsigned int  min = 0,
unsigned int  idle = 10000,
bool  blocking = true,
StopMode  mode = TaskManager::wait_for_all 
)

If the specified minimum number of threads is greater than 0, this constructor will start the required minimum number of threads. If glib < 2.32 is installed, g_thread_init() must be called before any TaskManager objects are constructed.

Parameters
maxThe maximum number of threads which the TaskManager object will run in the thread pool. If the value passed as this argument is less than the value passed as 'min', the maximum number of threads will be set to 'min'. A value of 0 is not valid, and if this is passed the number will be set to the greater of 1 and 'min'.
minThe minimum number of threads which the TaskManager object will run in the thread pool.
idleThe length of time in milliseconds that threads greater in number than 'min' and not executing any tasks will remain in existence. The default is 10000 (10 seconds).
blockingIf true, calls to stop_all() and the destructor will not return until the tasks remaining to be executed have finished (what is meant by "the tasks remaining to be executed" depends on the StopMode setting, for which see the documentation on the stop_all() method). If false, stop_all() and the destructor will return straight away (which in terms of the TaskManager class implementation is safe for the reasons explained in the documentation on the destructor).
modeThe StopMode setting (either Cgu::Thread::TaskManager::wait_for_running or Cgu::Thread::TaskManager::wait_for_all) executed when running stop_all() or when the destructor is called. See the documentation on stop_all() for an explanation of the setting.
Exceptions
std::bad_allocThis exception might be thrown if memory is exhausted and the system throws in that case.
Cgu::Thread::TaskErrorThis exception will be thrown if starting the specified minimum number of threads fails.
Cgu::Thread::MutexErrorThis exception might be thrown if initialisation of the contained mutex fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.)
Cgu::Thread::CondErrorThis exception might be thrown if initialisation of the contained condition variable fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new condition variables.)

Since 1.2.25

Cgu::Thread::TaskManager::~TaskManager ( )

The destructor will call stop_all(), unless that method has previously been called explicitly without throwing std::bad_alloc. If the blocking setting is true, the destructor will not return until the tasks remaining to be executed have finished (what is meant by "the tasks remaining to be executed" depends on the StopMode setting, for which see the documentation on the stop_all() method.) If the blocking setting is false, the destructor will return straight away: this is safe, because TaskManager's internals for running tasks have been implemented using reference counting and will not be deleted until all threads running on the TaskManager object have finished, although the remaining tasks should not attempt to call any of TaskManager's methods once the TaskManager object itself has been destroyed.

The destructor is thread safe (any thread can destroy a TaskManager object) unless the blocking setting is true, in which case no task running on the TaskManager object may destroy the TaskManager object. Subject to that, it is not an error for a thread to destroy a TaskManager object and so invoke this destructor while another thread is already blocking in (if the blocking setting is true) or already out of (if the blocking setting is false) a call to stop_all() and remaining tasks are executing: if blocking, both calls (to stop_all() and to this destructor) would safely block together. Any given thread can similarly safely follow a non-blocking call to stop_all() by a non-blocking call to this destructor even though remaining tasks are executing. However, it is an error for a thread to call stop_all() after another thread has begun destruction of the TaskManager object (that is, after this destructor has been entered): there would then be an unresolvable race with the destructor.

The destructor will not throw.

If stop_all() has not previously been called explicitly and throws std::bad_alloc() when called in this destructor, the exception will be caught and consumed, but then the destructor will not block even if the blocking setting is true, and if the minimum number of threads is not 0 some threads might remain running during the entire program duration (albeit safely). Where the throwing of std::bad_alloc is a meaningful event (usually it isn't) and needs to be guarded against, call stop_all() explicitly before this destructor is entered, or use a minimum thread value of 0 and allow for the case of the destructor not blocking.

Since 1.2.25

Member Function Documentation

void Cgu::Thread::TaskManager::add_task ( const Callback::Callback task)
inline

This method adds a new task. If one or more threads in the pool are currently blocking and waiting for a task, then the task will begin executing immediately in one of the threads. If not, and the value returned by get_used_threads() is less than the value returned by get_max_threads(), a new thread will start and the task will execute immediately in the new thread. Otherwise, the task will be queued for execution as soon as a thread becomes available. Tasks will be executed in the order in which they are added to the ThreadManager object. This method is thread safe (any thread may call it, including any task running on the TaskManager object).

A task may terminate itself prematurely by throwing Cgu::Thread::Exit. In addition, the implementation of TaskManager will consume any other exception escaping from the task callback and safely terminate the task concerned in order to protect the integrity of the TaskManager object. Where detecting any of these outcomes is important (usually it won't be), the two argument version of this method is available so that a 'fail' callback can be executed in these circumstances.

Parameters
taskA callback representing the new task, as constructed by the Callback::make() or Callback::make_ref() factory functions. Ownership is taken of this callback, and it will be disposed of when it has been finished with. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The destructors of any bound arguments in the callback must not throw.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start and the 'task' callback will be disposed of.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start and the 'task' callback will be disposed of.

Since 1.2.25

void Cgu::Thread::TaskManager::add_task ( std::auto_ptr< const Callback::Callback task,
std::auto_ptr< const Callback::Callback fail 
)

This method adds a new task. If one or more threads in the pool are currently blocking and waiting for a task, then the task will begin executing immediately in one of the threads. If not, and the value returned by get_used_threads() is less than the value returned by get_max_threads(), a new thread will start and the task will execute immediately in the new thread. Otherwise, the task will be queued for execution as soon as a thread becomes available. Tasks will be executed in the order in which they are added to the ThreadManager object. This method is thread safe (any thread may call it, including any task running on the TaskManager object).

A task may terminate itself prematurely by throwing Cgu::Thread::Exit. In addition, the implementation of TaskManager will consume any other exception escaping from the task callback and safely terminate the task concerned in order to protect the integrity of the TaskManager object. Where detecting any of these outcomes is important (usually it won't be), a callback can be passed to the 'fail' argument which will execute if, and only if, either Cgu::Thread::Exit is thrown or some other exception has propagated from the task. This 'fail' callback is different from the 'fail' callback of Cgu::Thread::Future objects (programming for many tasks to a lesser number of threads requires different approaches from programming for one thread per task), and it executes in the task thread rather than executing in a glib main loop (however, the 'fail' callback can of course call Cgu::Callback::post() to execute another callback in a main loop, if that is what is wanted).

Parameters
taskA callback representing the new task, as constructed by the Callback::make() or Callback::make_ref() factory functions. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
failA callback which will be executed if the function executed by the 'task' callback exits by throwing Thread::Exit or some other exception. If an exception propagates from the function represented by this callback, this will be consumed to protect the TaskManager object, and a g_critical() warning will be issued.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'fail' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'fail' callback will not execute).
Note
Question: why does the single argument version of add_task() take a pointer, and this version take the callbacks by std::auto_ptr? Answer: The two argument version of add_task() takes its arguments by std::auto_ptr in order to be exception safe if the first callback to be constructed is constructed correctly but construction of the second callback object throws.

Since 1.2.25

void Cgu::Thread::TaskManager::change_max_threads ( int  delta)

This will increase, or if 'delta' is negative reduce, the maximum number of threads which the TaskManager object will currently run in the thread pool by the value of 'delta'. The purpose of this is to enable a task to increment the maximum thread number where it is about to enter a call which may block for some time, with a view to decrementing it later when it has finished making blocking calls, so as to enable another thread to keep a core active. If 'delta' is negative and results in a max_threads value of less than the current number of running threads, the number of threads actually running will only be reduced as tasks complete, or as idle timeouts expire. This method does nothing if stop_all() has previously been called. This method is thread safe. Since version 1.2.31, the scoped handle class TaskManager::IncHandle is available which calls this method.

Parameters
deltaThe change (positive or negative) to the maximum number of threads which the TaskManager object will currently run in the thread pool. This method will not set the maximum value of threads to a value less than that returned by get_min_threads(), nor to a value less than 1.
Exceptions
std::bad_allocIf this call is passed a positive value and tasks are currently queued for execution, a new thread or threads will be started for the queued tasks, so this exception may be thrown on starting a new thread if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion).
Cgu::Thread::TaskErrorIf this call is passed a positive value and tasks are currently queued for execution, a new thread or threads will be started for the queued tasks, so this exception may be thrown on starting a new thread if it fails to start correctly (this would mean that memory is exhausted, the pthread thread limit has been reached or pthread has run out of other resources to start new threads).

Since 1.2.27

bool Cgu::Thread::TaskManager::get_blocking ( ) const

Gets the current blocking setting, which determines whether calls to stop_all() and the destructor will block waiting for all remaining tasks to complete. This value is established initially by the 'blocking' argument passed to the TaskManager constructor and can subequently be changed by calling set_blocking(). This method will not throw and is thread safe.

Returns
The current blocking setting.

Since 1.2.25

unsigned int Cgu::Thread::TaskManager::get_idle_time ( ) const

Gets the length of time in milliseconds that threads greater in number than the minimum and not executing any tasks will remain in existence waiting for new tasks. This value is established initially by the 'idle' argument passed to the TaskManager constructor and can subequently be changed by calling set_idle_time(). The default value is 10000 (10 seconds). This method will not throw and is thread safe.

Returns
The idle time in milliseconds.

Since 1.2.25

static unsigned int Cgu::Thread::TaskManager::get_max_tasks ( )
static

Gets the limit to the sum of the number of tasks which a TaskManager object may have running in the thread pool or queued for execution at any one time. On a 32-bit system, reaching this limit will normally cause the amount of memory which any process may allocate to be exceeded so the limit will in practice never be met (the add_task() or make_task_* methods will throw a std::bad_alloc exception before then). On a 64-bit system this limit will normally be the same as UINT_MAX (4,294,967,295 for a 32-bit unsigned int) which although likely to be unfeasibly large could in theory be reached with a system which can make around 70GB of memory available to the process for the TaskManager object. The add_task() and make_task_* methods will throw std::length_error if an attempt is made to exceed this limit and std::bad_alloc has not got there first.

This method is thread safe.

Returns
The maximum number of tasks which a TaskManager object may have either running or queued for execution at any one time.
Exceptions
std::bad_allocThis exception may be thrown the first time this method is called. Any subsequent calls will not throw if an earlier one did not (this method calculates the limit once only and then caches it using static local initialization).

Since 1.2.42

unsigned int Cgu::Thread::TaskManager::get_max_threads ( ) const

Gets the maximum number of threads which the TaskManager object is currently set to run in the thread pool. This value is established initially by the 'max' argument passed to the TaskManager constructor and can subequently be changed by calling set_max_threads() or change_max_threads(). The default value is 8. This method will not throw and is thread safe. However, if a blocking task might use the TaskManager::IncHandle class (or increase and then decrease the number by hand by calling change_max_threads()), this method will not usually be useful.

Returns
The maximum number of threads.

Since 1.2.25

unsigned int Cgu::Thread::TaskManager::get_min_threads ( ) const

Gets the minimum number of threads which the TaskManager object will run in the thread pool (these threads will last until stop_all() is called or the TaskManager object is destroyed). This value is established by the 'min' argument passed to the TaskManager constructor and cannot subequently be changed. The default is 0. This method will not throw and is thread safe.

Returns
The minimum number of threads.

Since 1.2.25

StopMode Cgu::Thread::TaskManager::get_stop_mode ( ) const

Gets the current StopMode setting (either Cgu::Thread::TaskManager::wait_for_running or Cgu::Thread::TaskManager::wait_for_all) executed when running stop_all() or when the destructor is called. See the documentation on stop_all() for an explanation of the setting. This value is established initially by the 'mode' argument passed to the TaskManager constructor and can subequently be changed by calling set_stop_mode(). This method will not throw and is thread safe.

Returns
The current StopMode setting.

Since 1.2.25

unsigned int Cgu::Thread::TaskManager::get_tasks ( ) const

Gets the number of tasks which the TaskManager object is at present either running in the thread pool or has queued for execution. This value will be less than the number returned by get_used_threads() if threads in the thread pool are currently waiting to receive tasks for execution. This method will not throw and is thread safe.

Returns
The number of tasks either running or queued for execution.

Since 1.2.25

unsigned int Cgu::Thread::TaskManager::get_used_threads ( ) const

Gets the number of threads which the TaskManager object is currently running in the thread pool, including those blocking waiting for a task. This value could be greater than the number returned by get_max_threads() if change_max_threads() has recently been called with a negative number but not enough tasks have since completed to reduce the number of running threads to the new value set. This method will not throw and is thread safe.

Returns
The number of threads running in the thread pool, including those blocking waiting for a task.

Since 1.2.25

bool Cgu::Thread::TaskManager::is_error ( ) const

This will return true if a thread required by the thread pool has failed to start correctly because of memory exhaustion or because pthread has run out of other resources to start new threads, or because an internal operation has thrown std::bad_alloc. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, and even more so where glib is used, as that terminates a program if memory cannot be obtained from the operating system, but there may be some specialized cases where the return value of this method is useful - this class does not use any glib functions which might cause such termination.) This method will not throw and is thread safe.

Since 1.2.25

template<class Ret , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( T &  t,
Ret(T::*)()  func 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns. Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( T &  t,
Ret(T::*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns. Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( T &  t,
Ret(T::*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns.Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( const T &  t,
Ret(T::*)() const  func 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns.Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( const T &  t,
Ret(T::*)(Arg1) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns.Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( const T &  t,
Ret(T::*)(Arg1, Arg2) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns.Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( Ret(*)()  func)

This is a wrapper which takes a pointer to a function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns. Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
funcThe function to be executed as a task.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( Ret(*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which will take a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns. Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
funcThe function to be executed as a task.
arg1The argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 >
Cgu::SharedLockPtr<Cgu::AsyncResult<Ret> > Cgu::Thread::TaskManager::make_task_result ( Ret(*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will provide the value that the function returns. Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. It is thread safe: any thread may call this method, including another task running on the TaskManager object, but see the introductory remarks about the use of the TaskManager::IncHandle scoped handle class where a task running on a TaskManager object is to block on one of its sub-tasks. See also the documentation on add_task() for further information about how task execution works.

If the function passed to this method exits by throwing Thread::Exit or some other exception, then the exception will be consumed and the returned Cgu::AsyncResult object's get() method will unblock and its get_error() method will return -1.

Parameters
funcThe function to be executed as a task.
arg1The first argument to be passed to that function.
arg2The second argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start.
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start.
Note
This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start.

Since 1.2.26

template<class Ret , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
T &  t,
Ret(T::*)()  func 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
T &  t,
Ret(T::*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method, the copy constructor of a non-reference argument of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
T &  t,
Ret(T::*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method, the copy constructors of any non-reference arguments of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
const T &  t,
Ret(T::*)() const  func 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
const T &  t,
Ret(T::*)(Arg1) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method, the copy constructor of a non-reference argument of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
const T &  t,
Ret(T::*)(Arg1, Arg2) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the member function passed to this method, the copy constructors of any non-reference arguments of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
Ret(*)()  func 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the function passed to this method and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a pointer to a function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
Ret(*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the function passed to this method, the copy constructor of a non-reference argument of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 >
void Cgu::Thread::TaskManager::make_task_when ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
GMainContext *  context,
Ret(*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)
inline

This is an abbreviated version of make_task_when_full(), which is for use when it is known that invocation of the function passed to this method, the copy constructors of any non-reference arguments of that function and the copy constructor of that function's return value do not throw anything other than std::bad_alloc, and the user is not interested in std::bad_alloc and does not need a Cgu::Releaser object for the 'when' callback (which is likely to cover the majority of uses, particularly when composing tasks using glib because glib terminates the program if it is unable to obtain memory).

Like make_task_when_full(), this method is a wrapper which takes a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

The 'when' callback will execute with G_PRIORITY_DEFAULT priority in the main loop.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
contextThe glib main context of the main loop in which the 'when' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued.
arg1The first argument to be passed to that function.
arg2The second argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' callback will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' callback will not execute).
2. As mentioned in describing 'func' above, if 'func' exits by throwing an exception the exception will be consumed and (if the thrown object's type is not Cgu::Thread::Exit) a g_critical() warning will be issued. The same will occur if the copy constructor of a non-reference argument of 'func' throws when invoking 'func' or the copy constructor of the return value of 'func' throws, or if the internal implementation of this wrapper throws std::bad_alloc on executing 'func'.

Since 1.2.26

template<class Ret , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
T &  t,
Ret(T::*)()  func 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop.
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
T &  t,
Ret(T::*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
T &  t,
Ret(T::*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
const T &  t,
Ret(T::*)() const  func 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
const T &  t,
Ret(T::*)(Arg1) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception or the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 , class T >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
const T &  t,
Ret(T::*)(Arg1, Arg2) const  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a member function pointer to a member function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the member function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object having the callback function as a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception or the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
tThe object whose member function passed to this method is to execute as a task.
funcThe member function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The first argument to be passed to that member function.
arg2The second argument to be passed to that member function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
Ret(*)()  func 
)

This is a wrapper which takes a pointer to a function which returns a value, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object of which the releaser is a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
Ret(*)(Arg1)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1 
)

This is a wrapper which takes a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object of which the releaser is a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of the bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

template<class Ret , class Arg1 , class Arg2 >
void Cgu::Thread::TaskManager::make_task_when_full ( std::auto_ptr< const Cgu::Callback::CallbackArg< const Ret & > >  when,
Cgu::Releaser when_releaser,
std::auto_ptr< const Cgu::Callback::Callback fail,
Cgu::Releaser fail_releaser,
gint  priority,
GMainContext *  context,
Ret(*)(Arg1, Arg2)  func,
typename Cgu::Param< Arg1 >::ParamType  arg1,
typename Cgu::Param< Arg2 >::ParamType  arg2 
)

This is a wrapper which takes a pointer to a function which returns a value, together with arguments, and constructs a TaskManager task which will execute that function by calling add_task() with an appropriate callback object, and causes the 'when' callback passed as an argument to this method to be executed by a glib main loop if and when the task finishes correctly - the 'when' callback is passed the function's return value when it is invoked. It is thread safe (any thread may call this method, including another task running on the TaskManager object). Apart from the absence of a 'one thread per task' model, this method therefore provides a similar interface to the one provided by Cgu::Thread::Future. See the documentation on add_task() for further information about how task execution works.

Note that unlike add_task(), but like the 'fail' callback of Cgu::Thread::Future objects, if a fail callback is provided to this method and it executes, it will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.

Note also that if releasers are provided for the 'when' or 'fail' callbacks, these are passed by pointer and not by reference (this is so that a NULL pointer can indicate that no releaser is to be provided). If provided, a releaser will enable automatic disconnection of the 'when' or 'fail' callback, if the object of which the releaser is a member is destroyed. For this to be race free, the lifetime of that object must be controlled by the thread in whose main loop the 'when' or 'fail' callback will execute.

The make_task_when() method is similar to this method but provides an abbreviated set of paramaters suitable for most cases. This method is for use where releasers or a 'fail' callback are required.

Parameters
whenA callback which will be executed if and when the function passed to this method finishes correctly. The callback is passed that function's return value when it is invoked. If an exception propagates from the 'when' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method.
when_releaserA pointer to a Releaser object for automatic disconnection of the 'when' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
failA callback which will be executed if the 'when' callback does not execute. This would happen if the function passed to this method exits by throwing Thread::Exit or some other exception, if the copy constructor of a non-reference argument of that function throws, if the copy constructor of that function's return value throws or if the 'when' callback does not execute because the internal implementation of this wrapper throws std::bad_alloc (which will not happen if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). If an exception propagates from the function represented by the 'fail' callback, this will be consumed and a g_critical() warning will be issued. The callback will execute in the glib main loop whose GMainContext object is passed to the 'context' argument of this method. An empty std::auto_ptr object indicates no 'fail' callback.
fail_releaserA pointer to a Releaser object for automatic disconnection of the 'fail' callback before it executes in a main loop (mainly relevant if the callback represents a non-static member function of an object which may be destroyed before the callback executes). A value of NULL indicates no releaser.
priorityThe priority to be given in the main loop to the 'when' callback or any 'fail' callback. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
contextThe glib main context of the main loop in which the 'when' callback or any 'fail' callback is to be executed. A value NULL will cause the callback to be executed in the main program loop).
funcThe function to be executed as a task. If an exception propagates from the task, the exception will be consumed and the 'fail' callback will execute.
arg1The first argument to be passed to that function.
arg2The second argument to be passed to that function.
Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion). See also the documentation for the get_max_tasks() method about the possibility of std::length_error being thrown. If std::bad_alloc or std::length_error is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called. It will also be thrown if is_error() would return true because this class's internal thread pool loop implementation has thrown std::bad_alloc, or a thread has failed to start correctly. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, but there may be some specialized cases where the return value of is_error() is useful.) If this exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
Note
1. This method will also throw if the copy constructor of a bound argument throws. If such an exception is thrown, the task will not start (which also means that the 'when' and 'fail' callbacks will not execute).
2. If a 'when_releaser' or a 'fail_releaser' object is provided, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the 'when' or 'fail' callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.

Since 1.2.26

void Cgu::Thread::TaskManager::set_blocking ( bool  blocking)

Sets the current blocking setting, which determines whether calls to stop_all() and the destructor will block waiting for all remaining tasks to complete. This method cannot be called after stop_all() has been called (if that is attempted, Cgu::Thread::TaskError will be thrown). It is thread safe.

Parameters
blockingThe new blocking setting.
Exceptions
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called.

Since 1.2.25

void Cgu::Thread::TaskManager::set_idle_time ( unsigned int  idle)

Sets the length of time in milliseconds that threads greater in number than the minimum and not executing any tasks will remain in existence waiting for new tasks. This will only have effect for threads in the pool which begin waiting for new tasks after this method is called. This method will not throw and is thread safe.

Parameters
idleThe length of the idle time in milliseconds during which threads will remain waiting for new tasks.

Since 1.2.25

void Cgu::Thread::TaskManager::set_max_threads ( unsigned int  max)
Deprecated:

DEPRECATED. Use change_max_threads() instead. This method will interfere with the intended operation of the ThreadManager::IncHandle class if one task constructs a IncHandle object and another calls this method.

Sets the maximum number of threads which the TaskManager object will currently run in the thread pool. If this is less than the current number of running threads, the number of threads actually running will only be reduced as tasks complete, or as idle timeouts expire. This method does nothing if stop_all() has previously been called. This method is thread safe.

Parameters
maxThe maximum number of threads which the TaskManager object will currently run in the thread pool. This method will not set the maximum value of threads to a value less than that returned by get_min_threads(), nor to a value less than 1.
Exceptions
std::bad_allocIf this call is passed a value for 'max' which increases the maximum number of threads from its previous setting and tasks are currently queued for execution, new threads will be started for the queued tasks, so this exception may be thrown on starting the new threads if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion).
Cgu::Thread::TaskErrorIf this call is passed a value for 'max' which increases the maximum number of threads from its previous setting and tasks are currently queued for execution, new threads will be started for the queued tasks, so this exception may be thrown on starting the new threads if a thread fails to start correctly (this would mean that memory is exhausted, the pthread thread limit has been reached or pthread has run out of other resources to start new threads).

Since 1.2.25

void Cgu::Thread::TaskManager::set_stop_mode ( StopMode  mode)

Sets the current StopMode setting (either Cgu::Thread::TaskManager::wait_for_running or Cgu::Thread::TaskManager::wait_for_all) executed when running stop_all() or when the destructor is called. See the documentation on stop_all() for an explanation of the setting. This method will not throw and is thread safe.

Parameters
modeThe new StopMode setting.

Since 1.2.25

void Cgu::Thread::TaskManager::stop_all ( )

This will cause the TaskManager object to stop running tasks. The precise effect depends on the current StopMode and blocking settings. If StopMode is set to Cgu::Thread::TaskManager::wait_for_running, all queued tasks which are not yet running on a thread will be dispensed with, but any already running will be left to complete normally. If StopMode is set to Cgu::Thread::TaskManager::wait_for_all, both already running tasks and all tasks already queued will be permitted to execute and complete normally. If the blocking setting is set to true, this method will wait until all the tasks still to execute have finished before returning, and if false it will return straight away.

The StopMode setting should not be set to Cgu::Thread::TaskManager::wait_for_running if, when this method is called, another thread may be waiting on the Cgu::AsyncResult::get() method of a Cgu::AsyncResult object returned by Cgu::Thread::TaskManager::make_task_result(), as otherwise that wait may never end - choose the Cgu::Thread::TaskManager::wait_for_all setting instead in such cases.

After this method has been called, any attempt to add further tasks with the add_task() method will fail, and add_task() will throw Cgu::Thread::TaskError.

This method is thread safe (any thread may call it) unless the blocking setting is true, in which case no task running on the TaskManager object may call this method.

Exceptions
std::bad_allocThis exception will be thrown if memory is exhausted and the system throws in that case. (On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion).
Cgu::Thread::TaskErrorThis exception will be thrown if stop_all() has previously been called, unless that previous call threw std::bad_alloc: if std::bad_alloc is thrown, this method may be called again to stop all threads, once the memory deficiency is dealt with, but no other methods of the TaskManager object should be called.

Since 1.2.25


The documentation for this class was generated from the following file: