Here is everything you need for FG version 1.4. We have a tutorial to get you started, and you can follow the instructions below to install FG.
If you download and use FG, we invite you to send email to firstname.lastname@example.org to let us know that you're using it.
You will need the standard pthread interface library and g++ to install and run FG. Download fg1.4.tgz. Then run the following command from your terminal to unzip the tarball:This command will unzip the FG files into a directory called
tar -xvzf fg1.4.tgz
fg1.4. Now you can adjust debugging options and make the FG library. There are three debugging options that you can set:
FGLOGfor the log file,
FGDEBUGfor debugging options, and
FGTIMERfor timing options. If you choose to leave all three options unset, you can make the FG library with the following command:You can set the debugging options explicitly in the Makefile, or you can set them on the command line. The
FGLOGvariable may be set to
-DLOGW, which you would set on the command line with one of the following:If you set either option for
make FGLOG=-DLOGA libfg.a
make FGLOG=-DLOGW libfg.a
FGLOG, FG prints information about your program, including warnings and errors, to a log file. With the first argument, FG appends all the information to the log file, and with the second it overwrites the existing log file.
FGDEBUGvariable may be set to
-DVERBOSE:With this setting, FG continually prints information about the program as it progresses, along with any errors or warnings. It also prints timestamps along with each message. If
make FGDEBUG=-DVERBOSE libfg.a
FGLOGis set, FG prints this information to the log file. Otherwise, it prints to standard output.
Finally, you may set the
-DTIMERALL, which you would set on the command line with one of the following:The first option times the the pipeline when the first stage begins executing until the final stage finishes executing. The second option times the pipeline from the very first call to FG until the pipeline is dismantled. If
make FGTIMER=-DTIMERPIPELINE libfg.a
make FGTIMER=-DTIMERALL libfg.a
FGLOGis set, FG prints the timings to the log file. Otherwise, it prints the timings to standard output.
You may combine any of the three debugging options in any way. If you would rather not use the command line, you can change the settings directly in the Makefile, which is in the
By default, the FG log file is named FG.log, and it is stored in the directory where you run your program. You may change both the name and the directory with environment variables, however. FG uses the environment variable
FGLOGNAMEfor the filename and
FGLOGDIRfor the directory.
Any files you create that need to use FG classes and methods must include the file
fg1.4/FG.h. When compiling a program written with FG, you must link in the FG library file. If your program is called
fgtest.cc, and your
fg1.4directory is located at
/net/grad/laney/fg1.4/, you would build your FG program as follows:Then you can run the executable file
g++ fgtest.cc -o fgtest -L/net/grad/laney/fg1.4 -lfg -lpthread
Because FG creates a multi-threaded program (even if you specify only one thread), you should ensure that all the software you link with FG works in a multi-threaded environment. Be particularly careful if you are using MPI for interprocessor communication, for not all implementations of MPI are thread-safe.
Because they are multi-threaded, FG programs also can create performance problems associated with disk I/O. On many systems, when you run multi-threaded code, C stdio locks a file every time a thread reads or writes it and unlocks the file when the thread finishes reading or writing. The use of locks can slow down performance considerably, especially in a program where disk I/O is a time sink. It can be useful to instead use the unlocked versions of C stdio functions. We have found that using
fread_unlocked()for reading and
fwrite_unlocked()for writing can be significantly faster than using the locked counterparts. Check the man page entry for
unlocked_stdioto determine the support in your system for unlocked I/O.
Any questions or comments, please email email@example.com.
The following are sample FG programs from the FG tutorial. You can download these files and build them with the FG library as described above.
- Example 2.1 Try out FG with a simple example.
- Example 2.2 Implicit threads.
- Example 3.1 Using the caboose.
- Example 3.2 Auxiliary thumbnails and buffers.
- Example 3.3 Thumbnail parameters.
- Example 4.1 Stage parameters.
- Example 4.2 Thread initialization and cleanup functions.
- Example 4.3 Multistage threads.
- Example 5.1 Soft barriers.
- Example 5.2 Macros.
- Input files for some examples:
- read_file.dat For Examples 4.2 and 4.3.