3. API Primer

Before beginning to use the Client C API, it is important to know the prerequisites and scope of the system. The Status Server was designed from the beginning to be a very simple system to meet a specific set of needs. With this in mind, the following list outlines a basic understanding required before the Client C API can be used effectively.

• First and foremost, before using the Status Server API the libsockio, libcli, libss, and libssapi libraries must be installed on the client system.
• The Status Server was designed to hold relatively small pieces of information. There are two inportant constants defined in ss/ss_define.h which outline the maximum length of both the object name (SS_MAX_NAME_SIZE) and value (SS_MAX_VALUE_SIZE). At the time this document was written, these were both set to 255. It is important to understand that the length of the name is based on a relative path name as opposed to the full absolute path for an object.
• The Status Server was designed to hold information which is updated relatively infrequently. Typically, this means information which updates at around a frequency of one hertz (1x per second or less frequent). While initial benchmarks have shown the ability for the Status Server to handle many thousands of transactions per second, this is a system which contains a large amount of data. As such, it is important common sense is used when evaluating the type of information to be stored in the Status Server.
• Data within the Status Server is kept in memory and serialized at a set time interval. The interval itself can be found at ``/proc/serialize/interval'' in the Status Server. Typically, this interval is around 5 minutes or so. As a result, it is important to determine how this would affect the information you are planning on putting in the Status Server. In many cases, the serialization interval is relatively unimportant if the information is constantly provided by a persistent client. An example of this is the CFHT weather tower information. This information is constantly updated every 10 seconds by a dedicated client. If the client supplying weather information should go away, the information will expire within 20 seconds. By keeping data in memory and only serializaing information periodically, the Status Server can be extremely fast.
• The Status Server client connection is handled very much like NFS. Once a client has successfully logged on to the Status Server, if the Status Server itself goes away, or if a periodic loss of network connectivity occurs, an API function call will block until a connection to the Status Server can be re-established.
• For the most part, clients should not need to worry about where the Status Server is running. The CFHT environment will have one and only one Status Server running on a dedicated port (currently 909) in the CFHT network. If it should become necessary to shut down that Status Server (perhaps machine maintenance) and restart a Status Server on another machine, this can be done almost seemlessly. The Client C API is set up to cycle through a list of potential Status Servers. If connectivity is lost to a given Status Server it will block and continue to cycle through the list until a Status Server can be found. The host list is defined in ss_api.c as STATUS_SERVER_HOST_LIST. Rather than changing this definition, it is also possible to override the list by assigning a new host list to the STATSERV environment variable.
• If connectivity is lost and re-established with a Status Server, the Client C API will make sure that its interaction with the Status Server is unaffected. For example, if the Status Server is shut down on a specific host and a new Status Server is started on a different host, all previously initiated ``touches'' and ``monitors'' will be resent and any pending function call will be re-executed.
• Any ``out-of-memory'' situations detected within the Client C API will result in an abort of the client program utilizing the API. This may seem somewhat extreme. However, given that Linux is the platform of choice for most of the clients at CFHT, this is a situation which can never occur. Starting with the 2.4 Linux Kernel, malloc() will never fail. Instead, if the kernel detects that it is out of memory, it will start killing processes based on a predefined algorithm until memory is available. Given the way Linux is designed and the inherent difficulty in successfully recovering from memory allocation failures, this was a conscious design decision which was made.