FG Version 1.4
(released July 2006)
ABCDEFG (Asynchronous Buffered Computation Design and Engineering Framework Generator), which we shorten to FG and pronounce "effigy," is a programming environment for pipeline-structured programs. Such programs pass buffers among asynchronous stages, so that while one stage accesses high-latency data, other stages can make progress. The FG project is supported by DARPA, IBM, and the National Science Foundation. You can download FG version 1.4 from this page.
About FGFG is a programming environment for asynchronous programs that run on clusters and fit into a pipeline framework. It enables the programmer to write a series of synchronous functions and represents them as stages of an asynchronous pipeline. FG mitigates the high latency inherent in interprocessor communication and accessing the outer levels of the memory hierarchy. It overlaps separate pipeline stages that perform communication, computation, and I/O by running the stages asynchronously. Each stage maps to a thread. Buffers, whose sizes correspond to block sizes in the memory hierarchy, traverse the pipeline. FG makes such programs easier to write, smaller, and faster.People
New features in FG version 1.4 include disjoint and intersecting pipelines. FG allows you to run more than one pipeline concurrently on one processor. This flexibility enables cluster computations in which a given processor may send more or less data than it receives. Please see pages 32–36 in the FG tutorial for details.
May 2011 update: FG version 2 is being developed. The API for FG 2 will be completely different from the FG version 1.X API, and we plan to have a graphical front end.
- Elena Riccio Davidson, Ph.D. 2006
- Geeta Chaudhry Petrovic, Ph.D. 2004
- Elizabeth Hamon (Dartmouth '03)
- Brunn Roysden (Dartmouth '04)
- Cristina Maracine (Dartmouth '04)
- Senate Taka (Dartmouth '08)
- Wei Zhang, M.S. 2007
- Out-of-Core Distribution Sort in the FG Programming Environment. Workshop on Multithreaded Architectures and Applications (MTAAP 2010), April 2010.
- The FG Programming Environment: Good and Good For You. 18th ACM Symposium on Parallel Algorithms and Architectures (SPAA 2006) brief announcement, July 2006.
- Building on a Framework: Using FG for More Flexibility and Improved Performance in Parallel Programs. 19th International Parallel and Distributed Processing Symposium (IPDPS 2005).
- The FG Programming Environment: Reducing Source Code Size for Parallel Programs Running on Clusters. Second Workshop on Productivity and Performance in High-End Computing (P-PHEC 2005), pp. 27--34.
- FG: A Framework Generator for Hiding Latency in Parallel Programs Running on Clusters. 17th International Conference on Parallel and Distributed Computing Systems (PDCS 2004), pp. 137--144.
- Asynchronous Buffered Computation Design and Engineering Framework Generator (ABCDEFG). White paper for HECRTF, June 2003.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.
Sample CodeThe 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.