This page will give you a short introduction concerning the concepts enforced throughout XDispatch and also help you getting started by first integrating libxdispatch into your project and writing the first lines of code afterwards. libxdispatch aims to provide an environment within which you can write parallelized code using the concepts of Grand Central Dispatch while keeping cross-platfrom compatibility and thus leaves it up to you, which operating systems you intend to target.
The quickest way for getting started is obtaining a binary suitable for your development environment by going to the download section. There you can find binaries for Linux, Windows and Mac OS X. Download the appropriate archive and install it on your system.
On Mac OS you will only have to execute the provided package installer. It will automatically copy xdispatch.framework and (if selected) QtDispatch.framework to the '/Library' directory. Afterwards you can use the libraries by including one of the headers
#include <dispatch/dispatch.h> #include <xdispatch/dispatch>
As with any other framework you will need to link your executable against the framework, so either pass '-framework xdispatch' when invoking gcc or configure your IDE to link against the xdispatch framework.
Extract the archive and copy it to some place on the disk. The provided archives contain three directories:
To use xdispatch, make sure the three directories listed above are listed in the INCLUDE, LIB and PATH (for the bin directory) environment variables. When using Visual Studio you might also want to change the include and linker directories within your project configuration. Afterwards you can use the libraries by including one of the headers
#include <dispatch/dispatch.h> #include <xdispatch/dispatch>
Configure your project to link against the xdispatch and dispatch libs.
The recommended way on Linux is to use the provided packages by subscribing the PPA on Launchpad:
sudo apt-add-repository ppa:mlba_team/stable sudo apt-get update sudo apt-get install libxdispatch-dev libdispatch-dev
Packages for debian and RPM packages for openSUSE & Co will be released in the future.
In the meantime when not using Ubuntu, download the provided binary tarball according to your architecture and extract the headers and libraries to their corresponding places. Afterwards you can use the libraries by including one of the headers
#include <dispatch/dispatch.h> #include <xdispatch/dispatch>
As with any other shared library you will need to link your executable against them, so either pass '-lxdispatch -ldispatch' when invoking gcc or configure your IDE to link against the xdispatch framework.
Using libXDispatch within your source code is pretty straight forward as all you need to do is to include the headers within your source files - that's it.
#include <xdispatch/dispatch>
All functions are located in the xdispatch namespace. In the following I will demonstrate some use cases occuring when trying to parallelize the code. I will assume that your are either using gcc-4.5+, Visual Studio 2010 or clang as your compiler as enables us to utilize lambdas. For those not being able to use a "modern" compiler, please have a look at Parallel code using xdispatch::operations.
The most obvious use case is that you want to move some heavy calculation work off the main thread and into a background worker. Now without using libXDispatch, you'd probably be writing something similar to this:
#include <pthread.h> #include <iostream> // declared somewhere else class SomeData { bool finished; pthread_mutex_t lock; ... }; /* The worker function doing all the stuff */ void* do_work(void* dt){ SomeData* data = (SomeData*)dt; // execute the heavy code do_calculations(data); // notify the main thread we are finished pthread_mutex_lock(&data->lock); data->finished = true; pthread_mutex_unlock(%data->lock); } /* This function is getting called from your main thread also powering the user interface */ void some_function(){ SomeData* sd = new SomeData(); fill_data(sd); pthread_t worker; if(pthread_create(&worker, NULL, do_work, NULL, (void*)sd)){ std::cerr << "Failed to create worker thread" << std::endl; return; } pthread_mutex_lock(&sd->lock); while(!sd->finished){ pthread_mutex_unlock(&sd->lock); // process all events on the main thread process_events(); pthread_mutex_lock(&sd->lock); } // ok, now the worker has finished, show the results within the gui show_calc_results(sd); delete sd; }
So this is an example using pthreads. When writing for windows as well, we'd probably need to write another version using WindowsThreads or need to use a library such as OpenThreads or boost::threads. When using libXDispatch, we can express this code much more effectively - and still maintain cross platform compatibility:
#include <xdispatch/dispatch> // declared somewhere else class SomeData { ... }; /* This function is getting called from your main thread also powering the user interface */ void some_function(){ SomeData* sd = new SomeData(); fill_data(sd); xdispatch::global_queue().async(${ // execute the heavy code do_calulations(sd); // notify the gui that we are finished xdispatch::main_queue().async(${ show_calc_results(sd); delete sd; }); }); }
There's no need for manual thread creation and so on. Also note, that we can use all variables declared within some_function() within our lambda code ${ .. }. It's just as easy when you want to parallelize a loop. Let's assume the following piece of code (Please note this is still a very simple calculation):
#include <vector> #include <cmath> // declared somewhere else class SomeData { ... std::vector<double> a; std::vector<double> b; std::vector<double> c; std::vector<double> results; }; void do_calculations(SomeData* sd){ // our output will go in here sd->results = std::vector<double>(sd->a.size()); // the calculation - running on one thread only for(unsigned int i = 0; i < a.size(); i++){ sd->results[i] = 0; for(unsigned int j = 0; j < b.size(); j++){ for(unsigned int z = 0; z < c.size(); z++){ sd->results[i] += std::pow(sd->b[j], sd->a[i]) * std::sin(sd->c[z]); } } } }
Now to parallelize this piece of code using libXDispatch you can simply write:
#include <vector> #include <cmath> #include <xdispatch/dispatch> // declared somewhere else class SomeData { ... std::vector<double> a; std::vector<double> b; std::vector<double> c; std::vector<double> results; }; void do_calculations(SomeData* sd){ // our output will go in here sd->results = std::vector<double>(sd->a.size()); // the calculation - running on multiple threads xdispatch::global_queue().apply($(size_t i){ sd->results[i] = 0; for(unsigned int j = 0; j < b.size(); j++){ for(unsigned int z = 0; z < c.size(); z++){ sd->results[i] += std::pow(sd->b[j], sd->a[i]) * std::sin(sd->c[z]); } } }, a.size()); }
libXDispatch is also providing mechanisms for making some piece of code perfectly threadsafe. So again assume the following piece of code:
#include <pthread.h> static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER; /* So this function is called from several threads */ void worker(){ // some work ... pthread_mutex_lock(&lock); // do some critical work if(already_done){ // we might have finished here pthread_mutex_unlock(&lock); return; } // do some other critical work pthread_mutex_lock(&lock); // some other work ... }
We will have to make sure the mutex is cleanly unlocked whenever leaving the critical section. And what happens if an exception is thrown from within that we do not catch? This might result in a deadlock. All this can be easily resolved by using the following expression:
#include <xdispatch/dispatch> /* So this function is called from several threads */ void worker(){ // some work ... synchronized { // do some critical work if(already_done) // we might have finished here return; // do some other critical work } // some other work ... }
No need to handle the locking by yourself, all is done magically - and it is ensured that the lock will be automatically cleared whenever you leave the section marked by the brackets. For further details about this, please see the documentation on the xdispatch::synclock. Please note that his functionality is available on compilers without lambda support as well.
All the examples shown above can also be written without using lambdas. So for example the parallel loop can also be expressed using an xdispatch::iteration_operation:
#include <vector> #include <cmath> #include <xdispatch/dispatch> // declared somewhere else class SomeData { ... std::vector<double> a; std::vector<double> b; std::vector<double> c; std::vector<double> results; }; class InnerCalculation : public xdispatch::iteration_operation { SomeData* sd; public: InnerCalculation(SomeData* d) : sd(d) {} void operator()(size_t i){ sd->results[i] = 0; for(unsigned int j = 0; j < b.size(); j++){ for(unsigned int z = 0; z < c.size(); z++){ sd->results[i] += std::pow(sd->b[j], sd->a[i]) * std::sin(sd->c[z]); } } } } void do_calculations(SomeData* sd){ // our output will go in here sd->results = std::vector<double>(sd->a.size()); // the calculation - running on multiple threads xdispatch::global_queue().apply(new InnerCalculation(sd), a.size()); }
There is no need to worry about memory leaks - xdispatch will automatically delete the iteration_operation once it has finished execution.
The examples above showed only some of the functionality and power of libXDispatch. Of course there also is a plean C interface and Qt integration provided within QtDispatch. For further exploration, we recommend browsing the API documentation and having a look at the various unittests.
There is also a lot more concepts to explore. For example you could create your own queues and not only use the automatically provided global queues. For understanding the idea of serial and concurrent queues and the usage of setting a target for a queue, we recommend to read the document "Apple Technical Brief on Grand Central Dispatch" and have a look at Apple's Concurrency Programming Guide