I/O drivers

The mmjobs module provides a modified version of the mem IO driver designed to be used in a multithreaded environment: memory blocks allocated by the shmem IO driver are persistent (i.e. they are not released after the model terminates) and can be used by several models. Thanks to this facility, models running concurrently may exchange data through memory by means of initialization blocks for instance.

The driver mempipe offers another communication mechanism between models: a memory pipe may be open by two models simultaneously. One of them for writing and the other one for reading. This driver also supports initialization blocks through which data is transfered in binary form.

The drivers rcmd, xsrv and xssh allow to start additional Mosel instances: they have to be used to build host specifications as expected by the connect function. Finally, thanks to the rmt driver a Mosel instance can access files available from the environment of another instance.

Driver shmem

shmem:label[/minsize[/incstep]]

The file name for this driver is a label: this is the identifier (the first character must be a letter) of the memory block. A label is not local to a particular model and remains valid after the end of the execution of the model having created it. All memory blocks are released when the module mmjobs is unloaded but a given memory block may also be deleted explicitly by calling the fdelete procedure of module mmsystem or by using the fremove C-function of the Native Interface. Note also that deleting the special file "shmem:*" has the effect of releasing all memory blocks handled by the driver.

Several models may open a given label at the same time and several read operations may be performed concurrently. However, writing to a memory block can be done by only one model at a time: if several models try to read and write from/to the same label, only one (it becomes the owner of the memory block) performs its IO operations for writing and the others are suspended until the owner closes its file descriptor to the specified label. Then, one of the waiting models is restarted and becomes the new owner: this process continues until all file descriptors to the label are closed.

The memory block is allocated dynamically and resized as necessary. By default the size of the memory block is increased by pages of 4 kilobytes: the optional parameter incstep may be used to change this page size (i.e. the default setting is "label/0/4k"). The special value 0 modifies the allocation policy: instead of being increased of a fixed amount, the block size is doubled. In all cases unused memory is released when the file is closed.

Driver mempipe

mempipe:name

A memory pipe is characterized by its name. Only one model may open a pipe for reading but several models may open the same pipe for writing. However, if several models try to write to the same pipe, only one (it becomes the owner of the memory pipe) performs its IO operations and the others are suspended until the owner closes its file descriptor to the specified pipe. Then, one of the waiting models is restarted and becomes the new owner: this process continues until all file descriptors to the pipe are closed.

Pipe operations are possible only if the two ends of the pipe are open: one model for reading and at least one model for writing. There is no notion of 'end of file' in a pipe: if a model tries to read from an empty pipe (i.e. no model is writing to the other end) no error is raised and the model is suspended until something is available. Similarly trying to write to a pipe for which no model is reading from the other end is a blocking operation. In order to avoid lock ups, it is usually good practice to synchronize the models using events. For instance a model waits for a specific event before trying to read from a pipe; before starting to write to the same pipe, the other model sends the expected event.

Memory pipes may be used with initialization blocks. This driver does not use labels for each record of the initialization block: it is assumed (but not checked) that both ends of the pipe are using the same sequence of records. For instance, if the writer sends an integer, a string and then an array of reals, the reader must expect an integer, a string and an array of reals: it is not allowed to skip records or change order as it is usually possible with these blocks.

Driver rcmd

rcmd:[command]

This driver starts the specified command in a new process and connects its standard input and output streams to the calling Mosel instance. The created process is executed in the same current working directory as the controlling model and inherits the environment variables defined using setenv. The default command is "mosel -r". A typical use for this driver is to start an instance on the current machine or on a remote computer through an external program. For instance:

rcmd:rsh sunbox mosel -r

When Mosel is running in restricted mode (see Section mosel command: restricted mode), the restriction NoExec disables this driver.

Driver xsrv

xsrv:hostname[(port)][/ctx[/pass]][|var=val...]

This driver connects to the host hostname running the Mosel Remote Launcher (see Section The Mosel Remote Launcher xprmsrv) through a TCP socket on port port (default value: 2513) asking for the context ctx (default: xpress) using the password pass (default: no password). Additional environment variables can be specified: assignments of the form var=val must be separated by the symbol | and variable values may include variable references noted ${varname} (expansion is performed on the remote host in the context of its environment). The special environment variable MOSEL_CWD defines the current working directory for the newly created instance.

xsrv:winbox(3211)/xpr64|MOSEL_CWD=C:\workdir|MYDATA=${MOSEL_CWD}\data

Driver xssh

xssh:hostname[(port,kwf)][/ctx[/pass]][|var=val...]

This driver is the secure version of the xsrv driver decribed above: it establishes the connection to the xprmsrv server through an encrypted SSH tunnel (using 2515 as the default TCP port number). In addition to the port number, the driver can also take a file name (kwf) used as the known host file for server authentication: this file contains the list of known hosts with their corresponding public keys. When the connection is established to the remote host, the public key stored in this file is compared with the key provided by the server. The connection is canceled if keys do not match. Generating this known hosts file requires running the command xprmsrv -key public on the remote server in order to retrieve its public key (see Section Running the xprmsrv command).

For instance, the following command will include the server mysun in the knownhosts.txt file (the command must be run on the server):

xprmsrv -key public -hn mysun >>knownhosts.txt

Then after having moved the file to the machine(s) from where connections are initiated, the following connection string may be used to open secure connections with server authentication:

xssh:mysun(knownhosts.txt)

The remote connection is handled by a separate process. By default the program xprmsrv is used as the helper program but it can be replaced by another SSH client by changing the control parameter sshcmd.

Driver rmt

rmt:[node,bs]filename

This driver can be used with any routine expecting a physical file for accessing files on remote instances. By default, the file is located on the instance running on the node identified by the parameter defaultnode but a particular instance may be specified by prefixing the file name by its node number enclosed in square brackets. The special node number -1 designates the parent node of the current instance.

load(mi,mo,"rmt:[-1]model.bim")

By default the driver creates a buffer of 8k for its communication operations. The size of this buffer might be changed by specifying the desired buffer size after the node number (for instance "rmt:[0,4]filename" to use a 4k buffer). If only the buffer size has to stated the node number can be omitted (e.g. "rmt:[,4]filename"). Note that a buffer size must be between 2k and 64k.

In addition to physical files, this driver also emulates the behaviour of drivers cb, sysfd, tmp, shmem and java such that it can transfer streams from one instance to another. For instance, "rmt:sysfd:2" is the standard error stream of the process running the default node.