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