Contents

1 A Helios Standalone Server

In a client-server based system such as Helios, it is important to be able to create servers fairly easily. To help the programmer to do this, Helios provides a server library which is described in detail in technical report number 8. This server library is based on the assumption that the associated directory structure will be held in the tranputers’ memory at all times. Whilst this is valid for some servers, like the processor manager, the loader and the RAM disc, it is not valid for others, such as a remote filing system, where the directory structure is held permanently on disc. This technical note describes how to write a server without using the server library. It uses extracts of code from existing stand-alone servers to illustrate many of the points, but the reader should note that the code fragments do not form a complete server.

All Helios servers must install themselves in the name table of the processor on which they are running. Once they are in the name table, Helios can locate the server from anywhere else in the network. To install itself, the server should Locate() the current name table and Create() a new entry in it, the new entry being of Type_Name. The following code may be used to perform this.

The NewName() routine is given a name for the server, ”filesys”, a message port, and a protection matrix The protection matrix is usually either DefDirMatrix or DefFileMatrix, defined in the header protect.h, and may be used to limit access to the entire server if desired. The routine creates the entry and returns it, allowing the server to delete its entry from the name table at some future stage by a call Delete(NTE, Null(char)). This should be done as a tidy-up if the server exits.

Once the server is installed in the name table clients can access it using the system library calls, directly or indirectly. These system calls are converted to messages sent to the message port associated with the name table entry. New message ports can be obtained and freed using the NewPort() and FreePort() calls. The following messages may be generated by the system library: Open, Create, Locate, ObjectInfo, ServerInfo, Delete, Rename, Link, Protect, SetDate, Refine, and CloseObj. The server should provide handler routines for all of these messages, even though some will just return error messages. The work involved is greatly simplified if the handler routines are held in a table.

The name and port for the server must be filled, and the server can then start accepting messages and forking off worker processes to deal with the requests. The routine GSPServer below, is in an infinite loop allocating a message buffer if possible, receiving a request, and forking off a GSPWorker process to deal with that request. The GSP Worker checks that the request is a valid one and calls a handler routine to deal with it. It is up to the handler routine to free the message buffer once it is finished.

To facilitate returning suitable messages there are routines SendError(), InvalidFun, and Return(), which will free the message buffer if there is no more use for it.

All the messages sent directly to a server will include the full name of the object that the client is trying to access, but extracting this from the message is non-trivial. The following routine deals with all the various combinations, allocating a new buffer to hold the complete name. This buffer must be freed by the GSPWorker process.

The code so far has been server-independent. Next we consider code to implement a particular server. Assume that the transputer can access a remote MSDOS filing system using the following routines. The exact means of accessing this filing system is irrelevant.

The remote filing system works using MSDOS file names rather than Helios ones, so it is necessary to provide a name conversion routine to convert between the two, as follows.

We can now consider a typical handler routine for one of the possible requests, Drive_Locate().

Drive_Locate() extracts the local name given the Helios name. For example, if the Hellos name is ”c” then the MSDOS name is ”c:”, and if the Helios name is ”c/helios/bin/ls” then the local name is ”c:\helios\bin\ls”. Given this local name, Drive_Locate() calls one of the routines used to access the actual filing system, to determine whether the object exists and if so what it is. If the object does not exist the handler routine sends back an error message, releasing the memory allocated for the message, freeing the memory used to hold the local name, and returning to GSPWorker() above. GSPWorker() frees the memory used to hold the Helios name and returns, causing the worker process to terminate. Note that all the handler routines are called in separate processes, allowing different clients to access the server at the same time. It may be necessary to perform some locking inside the server using semaphores.

Successful replies to Locate, Create and Open requests must include a special data structure in the reply. This includes such details as a capability for the object and the full pathname for the object, allowing future accesses to the object to be faster. The routine SendOpenReply() constructs such a reply.

Many of the other handler routines are also quite simple. Drive_Create() is used to create a new file or directory, or to truncate an existing file to zero length. It does not open a stream to the object. Drive_Delete() is used to delete a file or an empty subdirectory. The other handler routines tend to be fairly simple as well.

The final point to consider is open streams, illustrated below by code to handle opening, closing, and reading files. Following a successful open, the server should include a new message port in its reply. This message port will be used for stream requests: Read, Write, GetSize, SetSize, Close, Seek, GetInfo, SetInfo, EnableEvents, Acknowledge, and NegAcknowledge. File_Open(), which is running as a separate process, waits for these messages and calls other handler routines to do the reading and writing. The system library will lock the open stream at the client side, so that the stream will only ever be sent one request at a time and there is no need to fork off worker processes. If no message arrives for the stream for 30 minutes it is assumed that the client has died without successfully tidying up, and the stream will go away automatically, closing the file in the process and doing all the tidy-ups.

Close requests may be sent either by the client itself, in which case the client expects a reply, or they may be sent on behalf of the client by the system, for example, when the client is terminated abnormally. In the latter case the system does not expect a reply to the Close request.

To achieve a degree of fault-tolerance, most requests are repeatable. In particular, when reading data from a stream the file position is sent with the request. Hence the request is of the form read 5000 bytes at offset 8000, and even if a reply message is lost the system library can just send exactly the same request again. This may mean that an implicit seek within the open file is required. Once the file is at the right position the server can start reading from it and sending the data back to the client. The amount of data requested may be larger than can fit into a single message, so the server may have to send multiple replies to a single request. The reply code may be ReadRc_EOF if the end of the file is reached before the read is satisfied, ReadRc_EOD if the reply is the last one and all the data requested has been sent, and ReadRc_More if the reply is not the last one. To inform the kernel that more messages are coming, the MsgHdr_Flags_preserve flag must be set on every reply except the last one.