SAMPY undocumented features

[Luigi Paioro]

Dear all,

   you should have received an e-mail where I announced the alpha 
release of SAMPY 1.0, a Python implementation of SAMP (Standard Profile) 
compliant with WD 1.0 (hub and client toolkit).

This implementation cames to life within the context of the OPTICON 
Network 3.2 (http://archive.eso.org/opticon/twiki/bin/view). In 
particular SAMP has been recently selected as the basic messaging system 
for the MIMA FASE prototype 
(http://cosmos.iasf-milano.inaf.it/trac/fase) - so far we used DBus.

Well, actually the candidate MIMA (and more in general FASE) messaging 
system requires more capabilities respect those currently provided by 
SAMP. This is the reason because I implemented SAMP by myself and added 
some new undocumented (advanced) features (I will add even others).

In this mail I will show you these advanced capabilities, so that you 
can try to use them (if you need them) or in case just comment whether 
they are really useful within the context of SAMP or not (I hope the 
former).

To outline better the reasons of these additional capabilities, let me 
show you our practical use case (or scenario). We have a server machine 
which is the sole host that has a set of data reduction programs 
installed. Whoever wants to use this reduction suite must login to this 
host with a specific user (the only provided with the right authorizations).

The different components of this reduction suite should communicate one 
with another using SAMP. The problem is that if more than one user are 
logged in at the same time, they connect with the same Hub sharing all 
the different client instances of the reduction suite... and we don't 
want this.

Then I've introduced a multi-instance starting mode, that is a way to 
allow multiple Hub instances running at the same time. In practice you 
launch SAMPY in multi-instance mode typing:

$ sampy.py --multi


What SAMPY does is to check whether the directory $HOME/.samp-1 exists 
($HOME or %USERPROFILE%) and if it doesn't then SAMPY creates it 
(.samp-1 means SAMP version 1). Then SAMPY starts a new Hub with a

$HOME/.samp-1/samp-hub-<PID>-<ID>

lock-file. <PID> is the process ID of the program that holds this Hub, 
and <ID> is an integer indicating an additional Hub ID for those 
programs which are able to spawn multiple Hubs (in my case it is a 
thread number).

 From the Hub side that's all. The clients, if not specified, try to 
connect with the single instance mode Hub (looking for $HOME/.samp 
lock-file). Otherwise, if specified, clients look for all the available 
Hubs (looking for $HOME/.samp and $HOME/.samp-1/samp-hub-* lock files), 
ask to the user which one s/he wants to connect with, and then they 
perform the connection.

Looking at the SAMPY API doc:

SAMPHubServer is provided with a mode parameter that accepts two values: 
SAMP_HUB_SINGLE_INSTANCE or SAMP_HUB_MULTIPLE_INSTANCE (the meaning is 
obvious).

SAMPHubProxy has an undocumented static method which is getRunningHubs() 
that returns a dictionary containing all the lock-file contents of the 
currently running hubs. SAMPHubProxy connect() method has also an 
additional undocumented parameter (hub_params) which accepts a 
dictionary containing the lock-file content of the hub chosen by the 
user. By the way... if you know the lock-file parameters of a remote 
hub, wherever it is, using this feature you can directly connect the 
client with it, thus remote connections are supported as well.


In order to simplify the selection of a specific Hub instance from the 
user side, I've also introduced the possibility to label each hub at 
startup:

$ sampy.py --multi --label=MyHub

Then this label is saved in the lock-file with the key name 
"samp.hub.label" and it is used by the client toolkit to provide the 
user with a readable Hub name (if "samp.hub.label" is missing then a 
default name is shown).

There are also other two additional keywords: "samp.hub.owner" and 
"samp.hub.owner_group" which are used to identify the user and the 
working group (they cannot be the UNIX user and group since all 
processes are owned by the same user) that owns the Hub.

Owner and group can be set using:

$ sampy.py --multi --label=MyHub --owner=luigi --group=mima

By the way, --label, --owner and --group options can be used also for 
the single instance mode.


Another additional SAMPY undocumented feature is the Hub instance timeout:

$ sampy.py --timeout=3600

This parameter allows to set up a Hub inactivity timeout after which the 
Hub automatically shuts down. This is very useful for those cases where 
the application that started the hub ends in an unexpected way (it 
crashes) or when someone just forgets to shut it down.

The MIMA team aims to introduce at least other two new capabilities, 
that is an authentication system and an activation system, but we are 
still working on this stuff.

If you have any comment, I'll be glad to receive it. Thank you in advance.


Luigi



-- 

Luigi Paioro

INAF - IASF Milano
Via Bassini 15, I-20133 Milano, Italy

Phone  (+39) 02 23 699 470
Fax    (+39) 02 26 660 17
Site   http://www.iasf-milano.inaf.it/