Styx Grid Services Tutorial: Advanced techniques

We have been through the process of setting up an SGS server and running some services using the general-purpose SGSRun client program. This is all that many people will need to know. However, there are some more techniques that you should know in order to get the most out of the system.

Monitoring progress and status

Clients of Styx Grid Services can monitor the changes in the state of the remote service. (This state data is known as service data.) All Styx Grid Services expose at least two pieces of service data: the first piece gives the status of the service:

Status stringMeaning
createdThe service instance has been created but not started.
runningThe service instance has been started.
finishedThe service instance has finished normally.
abortedThe services instance has been forcibly stopped by the client.
errorAn error has occurred.

(See the StatusCode class.) The second piece of service data gives the error code that is returned by the program that underlies the service instance. Service providers can also create custom pieces of service data: see Configuration of Styx Grid Services.

Monitoring of service data is handled in a rudimentary way in the SGSRun program. By default, no service data is monitored, but if you run SGSRun with the switch --sgs-debug, all updates to service data will be printed to the standard output stream. This can be useful when troubleshooting as you can get information about what has happened on the server. For example:

SGSRun localhost 9092 helloworld --sgs-debug

produces the following output (for example):

status = created
Hello world
status = finished: took 0.344 seconds.
exitCode = 0

Understanding the config file

The hardest part of setting up a Styx Grid Services server is creating the configuration file. Although an example config file is provided with the distribution, this cannot cover all possible permutations of configurations. Please read this page for a more complete description of how to write the configuration file.

Setting the lifetime of a Styx Grid Service

Whenever you run a Styx Grid Service, a new instance of that service is created on the server. This instance contains cached copies of all the input and output files that the underlying executable program reads and writes. In most cases, once the SGS has finished running, these cached files are no longer needed.

The --sgs-lifetime command-line option can be used to set the lifetime of a particular SGS instance (run SGSRun with the switch --sgs-verbose-help to see this). By default this is set to 60 minutes; after this time the SGS instance will be automatically garbage-collected on the server. You can set this to a longer or shorter time if you wish: for example, if you know that the SGS that you are running will take several hours to run, you will need to set --sgs-lifetime to a much larger number, or the service will be destroyed before it has finished.

In future releases, service lifetime will be handled better: it will be up to service providers, not clients, to decide on the best default lifetime for each service. Also, it will not be possible for services to be garbage-collected before they have finished running.

Creating custom clients

The SGSRun program is a general-purpose command-line client for any Styx Grid Service. It is possible to create other client programs using the JStyx API. A full discussion of this is beyond the scope of this tutorial, but in the meantime you might be able to figure out what to do by looking at the code for the SGSRun and SGSInstanceClient classes. Basically, the idea is that you create a class that implements the SGSInstanceClientChangeListener.html interface, and register this as a listener with an instance of SGSInstanceClient. You can then use the methods of SGSInstanceClient to start the service and subscribe to changes in service data and download output files, etc.