-
Notifications
You must be signed in to change notification settings - Fork 20
Creating Threads (C)
C++ Guides: GAMS Primer | Simulation Primer | Creating Algorithms | Creating Platforms | Creating Threads | Creating Transports | Debugging
Threading in GAMS can be done in a variety of ways including boost threads, stl threads, and various other libraries. However, we recommend and support the usage of the portable, knowledge-centered MADARA Threader class and extensions of the BaseThread class. For anyone who has worked with threads, the MADARA threads should feel familiar with its run method implementation. However, MADARA also provides access to a data plane (the knowledge base of which GAMS uses) and a controllable hertz rate.
To simplify the thread creation process, we have written a script called gpc.pl that allows quick creation and configuration of not only new user threads but also custom controllers that utilize your threads. In this wiki, we'll walk through the process of creating and maintaining new threads.
Creating a new algorithm can be greatly simplified by using the gpc.pl tool. To use the tool, decide where you want a custom project to be located. We'll refer to this as a PROGRAM_LOCATION environment variable. A good place for this might be in a folder in your home directory, say HOME/gams_examples. The following examples assume perl is installed on your computer and available in the PATH variable. If perl is installed but not in PATH, you will want to call perl on the gpc.pl script to run it.
If you have any questions about usage of gpc.pl, pass the script a -h or --help option for guidance and information.
Generating new algorithm in Windows command shell (cmd in Start->Run)
%GAMS_ROOT%\scripts\projects\gpc.pl --new-thread my_thread --path %PROGRAM_LOCATION%Generating new algorithm in Linux terminal
$GAMS_ROOT/scripts/projects/gpc.pl --new-thread my_thread --path $PROGRAM_LOCATIONRunning these commands will generate a new directory at PROGRAM_LOCATION. Do not create the directory beforehand. Let the tool do that to ensure it doesn't assume the appropriate infrastructure has already been generated. The tool tries to do no harm to your projects when possible, so you can add new algorithms, platforms, simulations, etc. later.
The tool will generate a number of files and a build infrastructure using the MakefileProjectCreator for portability to Windows, Linux, Mac, Android, etc. As far as editing goes, there are only three files that most users may want to edit:
PROGRAM_LOCATION/src/threads/my_thread.h
PROGRAM_LOCATION/src/threads/my_thread.cpp
PROGRAM_LOCATION/src/controller.cppThe my_thread class is found in the my_thread.h|cpp files. By default this class is a null implementation of the MADARA BaseThread class with stubs for the run method and initialization method. This is going to be where your thread execution logic will be implemented
The controller.cpp file contains a custom GAMS controller that initializes your thread along with any other threads you want to add (you can chain together new thread creations in one command line via chaining together -new-thread or -nt with the names of the threads). However, the controller.cpp will probably need to be edited to include the correct hertz rates for each thread. To find this hertz rate, open src/controller.cpp with your favorite editor and look for the text "begin thread creation". You should see text like the following (which is creating and running your thread at 1hz).
// begin thread creation
threader.run (1, "my_thread", new threads::my_thread ());
// end thread creationIf this is too slow, and you would like to run your thread at 5hz or 100hz, simply change the first parameter of threader.run to be the hertz rate you need. The MADARA threader can be instructed to run a thread at an infinite hertz by providing it a zero hertz rate (0.0). A negative hertz rate indicates that the thread should only be run once. See documentation for Threader for more information.
Generating/compiling project in Windows command shell (cmd in Start->Run)
cd %PROGRAM_LOCATION%
mwc.pl -type vc12 workspace.mwc
workspace.slnAfter opening the Visual Studio project, compile the project with the settings used during compilation of MADARA and GAMS (e.g. 64 bit, Release mode).
Generating/compiling project in Linux terminal
cd %PROGRAM_LOCATION%
mwc.pl -type gnuace workspace.mwc
makeYou can speed up compilation by call make with -j , where NUMCORES is the number of cores on your build machine. This essentially will parallelize the build process, but with a project this small, the build process is very quick (should take a few seconds).
Believe it or not, you have already just generated and compiled a custom thread with a custom controller!
C++ Guides: GAMS Primer | Simulation Primer | Creating Algorithms | Creating Platforms | Creating Threads | Creating Transports | Debugging