SYNCHRONIZE_DRAIN (Windows CE 5.0)
When you perform a build on a development workstation that has multiple processors, Build Tool (Build.exe) might create different threads which will build different directories at the same time.
In this case, you must ensure that your build process is ordered so that Build.exe does not attempt to build a directory without first building its dependencies.
If SYNCHRONIZE_DRAIN is set to 1 in a directory's sources file, Build.exe finishes building all preceding directories before starting to build that directory.
This differs from the related SYNCHRONIZE_BLOCK macro in that if SYNCHRONIZE_BLOCK is set, Build.exe finishes building that directory before starting to build any subsequent directories.Be aware that there is a subtle distinction between SYNCHRONIZE_BLOCK and SYNCHRONIZE_DRAIN, which are not mutually exclusive.
In either case, Build.exe still builds in the order specified by the dirs entry in the parent directory's dirs file.
Use this macro, and SYNCHRONIZE_BLOCK, very sparingly. When encountered, these macros completely stall the build process until synchronization is complete.
The following code example shows how to use SYNCHRONIZE_DRAIN.
SYNCHRONIZE_DRAIN=1
Remarks
In a sample scenario, where a single parent directory contains three directories labelled A, B, and C, the dirs file in the parent directory contains the line DIRS=A B C. Build.exe could start a worker process for each of the three directories if 3 or more processors are available in the development workstation and the environment variable BUILD_MULTIPROCESSOR is set to 3. For more information about this environment variable, see Miscellaneous Environment Variables.
In this scenario, directory A and B build static libraries, and that directory C combines the result into a single static library. Synchronization errors occur because, depending on the behavior of the desktop workstation, the compilation and link processes in directory C might run before either or both directories A and B have finished linking. This causes a link error in directory C because the necessary input library created by A and B has not been built yet.
To solve the issue, set SYNCHRONIZE_DRAIN=1 in the sources file of directory C. This allows directories A and B to finish compiling and linking before Build.exe starts the process for directory C. However, once directories A and B are finished, Build.exe might start processing directory C in addition to the next group of directories that are specified in the parent dirs file.
A more subtle error might occur if the user is not performing a clean build. For example, there might be preexisting versions of library A or B that were previously built. So, if directory C is built before directory A or B, C will link to outdated versions of library A or B. The resulting library C will not contain the expected changes from library A or B, but it will appear to have been correctly built. When the user suspects that this type of error might have occurred, performing a clean build will typically explicitly show the link error.
In a variation of this scenario, directory A produces a library which is used by both directories B and C. Synchronization issues occur because, depending on the timing of the desktop workstation, the compilation and link processes in directories A, B and C might run at the same time, which causes a link error in directories B and C. This error occurs because the necessary input library created by A has not been built yet.
To help avoid these issues, the line SYNCHRONIZE_BLOCK=1 is added to the sources file of directory A. This allows directory A to finish building before Build.exe starts processing the next directories as specified in the dirs file, which might even be processed by multiple worker threads.
Due to speed differences between desktop workstations, some workstations might exhibit synchronization issues while others do not. However, when a workstation exhibits a race condition, it is usually reproducible on the same machine. To help avoid these issues, the macros SYNCHRONIZE_BLOCK and SYNCHRONIZE_DRAIN are used.
While uncommon, it is possible for a static library to require a number of preceding libraries, and in turn be used by a number of subsequent directories. In this case, the directory requires SYNCHRONIZE_BLOCK to be set so that the directory can finish building before Build.exe proceeds to the subsequent directories. It also requires SYNCHRONIZE_DRAIN to be set to allow the preceding directories to be built.
See Also
Sources File | Build Tool | Windows CE Build Environment Tool
Last updated on Thursday, February 02, 2006
Send Feedback on this topic to the authors