SYNCHRONIZE_BLOCK (Windows Embedded CE 6.0)

1/5/2010

When you perform a build on a development workstation that has multiple processors, this creates the possibility that different Build Tool (Build.exe) threads might be running on different processors.

In this case, you must ensure that your build process is ordered so that Build.exe does not attempt to build a product without first building its dependencies.

If this macro is set to 1 in a directory's sources file, Build.exe finishes building the current directory before starting to build any subsequent directories.

However, Build.exe still builds in the order specified by the dirs entry in the parent directory's dirs file. This means that Build.exe waits for the current directory to finish building before continuing to build any subsequent directories.

Use this macro, and the related SYNCHRONIZE_DRAIN macro, very sparingly. When encountered, these macros completely stall the build process until synchronization is complete.

If a directory uses this macro, list the directory first in its parent dirs file. For more information, see Dirs File.

The following code example shows how to use this macro.

SYNCHRONIZE_BLOCK=1

Remarks

In a sample scenario where a single parent directory contains three directories labelled A, B, and C, if the dirs file in the parent directory contains the line DIRS=A B C, Build.exe starts a concurrent worker process for each of the three directories.

Assuming that directories A and B build static libraries, and that directory C combines the result into a single static library, setting the environment variable BUILD_MULTIPROCESSOR=3 might cause issues such as link and synchronization errors. For more information about this environment variable, see Miscellaneous Environment Variables.

These issues 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, which causes a link error in directory C. This error occurs because the necessary input library has not been built from the results of directories A and B.

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, it 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.

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 SYNCHRONIZE_BLOCK and SYNCHRONIZE_DRAIN macros are used. For more information, see SYNCHRONIZE_DRAIN.

In the above scenario, the line SYNCHRONIZE_DRAIN=1 is added to the sources file in 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. This can cause issues when directory C contains libraries used by other directories, and those directories are built before directory C is finished.

To help avoid these issues, the line SYNCHRONIZE_BLOCK=1 is added to the first library in directory C. This allows the directory to finish building before Build.exe starts processing the next directories in the queue, which might even be processed by multiple worker processes.

Be aware that there is a subtle distinction between the two macros, which are not mutually exclusive.

While uncommon, it is possible for a static library to require a number of preceding libraries, and in turn be used itself by a number of subsequent directories. In this case, the directory requires SYNCHRONIZE_DRAIN to be set to allow the preceding directories to be built. It also requires SYNCHRONIZE_BLOCK to be set so that the directory can finish building before Build.exe proceeds to the subsequent directories.

See Also

Concepts

Sources File
Build Tool
Windows Embedded CE Build Environment Tool