Writing Servers

Basics of pylabrad servers

You can write a server simply by subclassing the LabradServer class and using the @setting decorator

from labrad.server import LabradServer, setting
from twisted.internet.defer import inlineCallbacks, returnValue

class MyServer(LabradServer):
    name = "My Server"    # Will be labrad name of server
    
    @inlineCallbacks
    def initServer(self):  # Do initialization here
        pass

    @setting(10, data='?', returns='b')
    def is_true(self, c, data):
        return bool(data)

__server__ = MyServer()

if __name__ == '__main__':
    from labrad import util
    util.runServer(__server__)

Setting decorator

The @setting decorator takes up to four arguments:

• The first positional argument is the setting ID number. These must be unique across all settings in a single server. The actual numbers don't matter, they're there so that requests coming in can be routed to the right setting.

• An optional second argument which is a string specifying this setting's name. If this argument is omitted then the name of the setting is inferred from the python function name.

• Any number of keyword arguments with default values specifying that argument's type tag. For arguments which must be of a specific single type, the default can be a string, e.g. arg='s', or arg='w', or arg='*v[Hz]', etc. If the argument supports multiple LabRAD types, you can instead give a list of type tags. For example, if we accept either a string or an int we write arg=['s', 'i'].

• A keyword argument returns which specifies the type tag (or list of possible type tags) of the returned data.

Here is an example of a cd (change directory) command for the registry:

    @setting(10, 'cd', path=['s', '*s', 'w'], returns='*s') # 'cd' is optional and redundant
    def chdir(self, c, path=None):  # Path can also be unspecified.
        '''Code goes here'''

This setting will be called cd on the LabRAD system. The path can be given as a string, list of strings, or unsigned integer. The settings returns a list of strings. Note that in the python function the path argument defaults to None. This means that the argument can actually be omitted, in which case it will take the default value None in the python code.

Servers acting as clients

Many servers need to make requests to other servers. Each server has a 'client' object for this purpose:

    @setting(15, key='s', returns='?')
    def get_registry_key(self, c, server_name):
        p = self.client.registry.packet()
        p.get(key)
        result = yield p.send()  # Always wait=False
        returnValue(result['get'])

Notice that servers always make asynchronous requests, so we must use yield to get the value of the Deferred. We then must use returnValue to send the result back, just as if this were an inlineCallbacks method.

Contexts

The second argument to every setting function (after self) is the context, usually called c. This allows the server to store state on a per-client basis. It acts like a dictionary which the server implementation is allowed to store arbitrary keys. It also has the attribute c.ID containing the ID of the client making the request. There are two special methods that a server can override: initContext(self, c) and expireContext(self, c). These are called the first time a client uses a specific context, and when the context expires (usually because the client disconnected from the labrad manager).

Signals

LabRAD support signals. These are messages sent by servers triggered by an external event, rather than as a response to a specific client request. For instance, the data vault sends a signal to every listening client when a new file is created. This allows e.g. the grapher to update its display without polling the server. Signals are declared in pylabrad servers like so:

from labrad.server import LabradServer, Signal, setting

class SignalTestServer(LabradServer):
    onNotification = Signal(1234, 'signal: test', 's')
    @setting(10, message='s')
    def notify_clients(self, c, message):
        self.onNotification(message)  # send the message to all listening clients