GAP (ZeroMQInterface) - Chapter 3: Using ZeroMQ with the zgap script

Goto Chapter: Top 1 2 3 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

3 Using ZeroMQ with the zgap script
3.1 Running zgap
3.2 Zgap API
3.2-1 ZExec
3.2-2 ZBind
3.2-3 ZUnbind
3.2-4 ZCall
3.2-5 ZQuery
3.2-6 ZResponse
3.2-7 ZTask
3.2-8 ZAsync
3.2-9 ZRead
3.2-10 ZReadGapRoot

### 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

`‣ ZExec`( dest, cmd ) | ( function )

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

`‣ ZBind`( dest, var, expr ) | ( function )

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

`‣ ZUnbind`( dest, var ) | ( function )

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

    gap> ZUnbind(ZAll, "status");

##### 3.2-4 ZCall

`‣ ZCall`( dest, func, args ) | ( function )

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

`‣ ZQuery`( dest, func, args, callback ) | ( function )

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`( ) | ( function )

`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

`‣ ZTask`( dest, func, args, callback ) | ( function )

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

`‣ ZAsync`( dest, func, args ) | ( function )

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

##### 3.2-9 ZRead

`‣ ZRead`( dest, file ) | ( function )

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

##### 3.2-10 ZReadGapRoot

`‣ ZReadGapRoot`( dest, file ) | ( function )

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

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 Ind

generated by GAPDoc2HTML