SYNOPSIS:

Starting neo with the option -server serverid makes its named units remote accessible from other Neo/NST circuits through use_remote units. This is achieved with the shared library nstserver.so which allows an application (such as Neo) to make named NST units remotely accessible by other NST or Neo processes. The protocol is very simple and permits an external client to obtain a proxy to any named NST unit in the application (analogous to the functionality offered by the use_method unit within a Neo or NST process). Any pins not of the basic NST data types (float,int,byte,string,scalar) will be missing on the proxy. Their values simply do not participate in the data exchange protocol. When the client executes (adapts,controls) its proxy, the following steps happen: 1.the input values of all pins of the proxy are temporarily copied into the corresponding pins of the remote unit 2.the remote unit is executed (adapted,controlled) 3.the new values in the output pins of the remote unit are transferred back into the corresponding pins of the proxy. 4.the original inputs of the remote unit are restored. (but the changed output values are kept). The idea is to minimally disrupt the operation of the remote unit in its circuit. When the server's main thread is already executing NST units while a client request arrives, execution of the server main thread will become suspended in the next 'gap' between exec operations. Then steps 1-4 from the client will be inserted and the operation of the main thread resumed thereafter (note that any operations in additional threads, e.g., within thread_box'es, remain unaffected. Here it is in the responsibility of the programmer to consider and handle potential interference problems). Multiple clients may attach to the same server: each client will get its own service thread, but the services themselves will share a mutex so that each client request is for its entire duration protected from interference through competing clients. HOW TO ACCESS REMOTE UNITS FROM OTHER NEO/NST PROCESSES: Access of remote units is through the use_remote() unit in folder remote (folder library remote.so). This unit works entirely analogous to the use_method unit, only that it works across the network and requires to additionally specify a server name. For details, see the man page use_remote

IMPLEMENTATION NOTES:

Turning the NST-application (e.g. Neo) into a server with nstserver requires only a handful additional code lines:

   #include "nstserver.h"
   ...
   struct NstServerStuff; // hides some defs
   ...
   int main(...) {
      ...
      char *pcErr, *pcServerName = ...;
      ...
      if ((pcErr = NST_START_SERVER(pcServerName,&uSearchRoot))) {
        // error: description is in pcErr
      } // else success
      ...

Here, the macro NST_START_SERVER returns NULL on success (a pointer to an error string in case of an error) and starts a server thread opening a socket that can be reached under name pcServerName by external processes. The second argument must be the address (!) of the unitptr of a unit *uSearchRoot that 'anchors' the identification of the to-be-called units by means of path names: any colon-free single token name refers to a unit in the container uSearchRoot, name1:name2 would refer to the (leftmost) named subunit name2 in named container name1 within uSearchRoot, and so on (entirely analogous to the naming scheme for the use_method() unit). For Neo, the root container is always the top-level circuit window. Note that this means that only the circuit that is displayed on the screen is reachable from a client (this might become changed in future releases so that it is always circuit 0 that is the reachable one).

IMPORTANT TECHNICAL NOTE:

Activating and deactivating the server is built into the _init and _fini functions of the shared library. Therefore, a mere dlopen() of nstserver.so is all that is needed. To avoid identifier clashes, the library is compiled such that the _init and _fini functions carry the names _init_nstserver and _fini_nstserver. This requires the linker options

    -Wl,--init -Wl,_init_nstserver -Wl,--fini -Wl,_fini_nstserver

(otherwise the server will not become activated!!)

SEE ALSO:

use_remote, appserver.so, remote_var

FILE

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../remotesrc/nstserver.c