[MathJax off]

3 Using ZeroMQ with the zgap script

The zgap script provides facilities to start a number of child processes controlled by a single master process and to allow for easy coordination between them.

3.1 Running zgap

From the shell, run zgap via:

bin/zgap -N <nodes> <gap_options> <gap_files>

Here, nodes should be a positive integer that describes the number of workers one wishes to start. The rest of the command line, consisting of gap options and gap files, will be passed to the master and the worker processes verbatim. This allows, for example, the initialization of functions that need to be known by all workers. The first line of output will be prefixed with [zgap] and will list the directory where zgap will store the files and sockets it uses to communicate. In particular, the logXX.txt files within that directory will contain the output generated by the workers; this is useful for debugging, as the workers do not have a working break loop. Example:

bin/zgap -N 4 -P 8 -m 1G common.g

On NUMA architectures that support the numactl command, it is possible to further specify which node each worker should be running on. This can take one of two forms:

bin/zgap -N <count>:<start>-<end>
bin/zgap -N <count>:+<start>-<end>

Each will distribute count worker processes on the physical nodes ranging from start to end in a round-robin fashion, reusing nodes if there are more workers than nodes. The first mode (without a + sign) will use absolute node numbers, the second will be relative to the master process. See the numactl manual page for further details. Example:

bin/zgap -N 4:+0-3 -P 8 -m 1G common.g

Note: Currently, zgap can only be run from the GAP root directory. This is an implementation restriction that is to be removed at a later date.

3.2 Zgap API

Most of the following API functions take a dest argument, which is used to specify the destination of the operation. To specify a worker thread, dest would have to be an integer in the range from 1 to the number of worker processes; 0 specifies the master process. Multiple processes can be specified by a range or list of integers. The variable ZAll contains a range encompassing the worker processes; ZSelf contains the index of the current worker or 0 for the master.

3.2-1 ZExec

This function sends cmd to the given destination and executes it there. The command must be a valid GAP statement ending in a semicolon. If dest specifies multiple processes, the command will be executed on all of them.

3.2-2 ZBind

This function binds the global variable described by the string var to the value expr in all processes listed in dest. Note that expr must evaluate to a serializable value.

gap> ZBind(ZAll, "counter", 0);

3.2-3 ZUnbind

This function is the counterpart to ZBind. It will unbind var in all specified processes.

gap> ZUnbind(ZAll, "status");

3.2-4 ZCall

This function will execute the function specified by the string func in the specified processes. The string func must be the name of a global variable referring to the function to be executed. This function should be created at startup by adding a file to the commandline that defines it in all workers or by ZExec.

gap> ZBind(ZAll, "counter", 0);
gap> ZExec(Zall, "add := function(n) counter := counter + n; end;");
gap> ZCall(1, "add", [1]);

3.2-5 ZQuery

This function works like ZCall, except that any return value will be passed to the callback function.

gap> res := false;
false
gap> ZQuery(1, "ReturnTrue", [], function(x) res := x; end);
gap> res;
true

3.2-6 ZResponse

ZResponse is a convenience function to construct blocking callbacks for ZCall and ZTask. It returns a record containing a put, a get, and a test function. Here, put is passed as the callback; get can be used to read the returned value; and test can be used to test for the presence of a value.

gap> resp := ZResponse();;
gap> ZQuery(1, "Z", [4], resp.put);
gap> resp.get();
Z(2^2)
gap> resp.test();
true

3.2-7 ZTask

This function works like ZQuery, except that the function will be executed via a task and callback will be called after the task finishes and returns a result.

3.2-8 ZAsync

This function works like ZCall, except that the function will be executed via a task.

3.2-9 ZRead

This function does a Read(file) for all specified processes.

3.2-10 ZReadGapRoot

This function does a ReadGapRoot(file) for all specified processes.

generated by GAPDoc2HTML