Using eclock

2 minute read

eclock is a tool that lets you serialize multiple runnings of a program. For example, it may not be safe to run two copies of a particular application simultaneously on a single computer, even if it is run by different users—an example is vb6. Use eclock (typically in makefiles) to cause various invocations of that program to wait for each other. Eclock is located in the bin directory.

An eclock example:

eclock.exe vb6 arg1 arg2 arg3

Using the previous example, multiple invocations of vb6 are now serialized. Note that direct vb6 invocations are not serialized.

Unless you use the --mutex option, you get a reasonable default for your system. The %1 in that default (or your override) is replaced by the base filename of your program (without the trailing .exe on Windows). (Also, %% is replaced by %.) After such expansion, all runs of eclock that refer to the same mutex take turns, running one at a time (in an unspecified order). If two eclock invocations have different mutexes, after expansion, then the eclock invocations run concurrently, without interfering with each other. Arguments are passed as-is to the target program, and the output and exit code are the same as the target program.

Mutex names are case sensitive.

For Linux only. The lock file (the --mutex option specifies a filename pattern for the lock file) must go on a local disk outside of $EMAKE_ROOT . Otherwise, the result could be concurrency instead of exclusion. The pathname is interpreted as relative to /tmp . Eclock may append a suffix of its own to the filename component to produce the final name of the lock file.

For Windows only. %1 expands to the lowercase equivalent of the base program filename. If you override the default mutex name, do not use any backslashes. The only exceptions are that you may start the mutex name with either Local\ to force the mutex to be session-local (which is not general practice) or Global\ (which makes the default explicit).

The following help text is the eclock Windows help.

eclockUsage:eclock.exe [--mutex <name>] <process> <process args>
-m or --mutex or /mutex - specify mutex name, overrides ECLOCK_MUTEX-h or --help or /help or /? - print this help and exit
Environmental variables:ECLOCK_MUTEX - specify mutex name, default 'eclock_%1'. Use %1 to substitute process nameECLOCK_BUSY_WAIT - CPU used every half minute while waiting (milliseconds, default 100)ECLOCK_DEBUG - turn on debuggingECLOCK_DEBUG_LOG - filename of debug log (stderr if omitted)
In case multiple mutexes are required, this program may append suffixes to the mutex name.  And unless you give a pattern starting with 'Local\', mutexes are global. Case matters in mutex names.