Appendix B Open Server Migration To Jaguar

Modified APIs and new event handlers

This section discusses the modified Open Server APIs and two new event handlers.

Modified APIs

The modified Open Server APIs are:

srv_sleep
srv_props
srv_deletemutex
srv_droppproc

srv_sleep

srv_sleep is used to suspend the currently executing thread. srv_sleep now uses its final two parameters which had been reserved for future use. If you do not want to take advantage of the new functionality of srv_sleep no changes are required and your code will work as before.

The first reserved parameter is now an Open Server mutex, and the second is a time-out in milliseconds. Both of these parameters are optional, and should be set to (CS_VOID*)0 when not being used.

When a mutex is passed to srv_sleep, it is released before the thread suspends, but after it is marked suspended. The mutex is reacquired before srv_sleep returns. The behavior is modeled on condition variables (posix threads).

This pseduo-code fragment demonstrates how a multithreaded application may use the new sleep functionality to prevent race conditions where wakeups may be missed:

Sleep side:srv_lockmutex(mutex_id)
status = NOT_YET_DONE;
while (status != DONE)
{
srv_sleep(..., mutex_id, ...);
}
srv_unlockmutex(mutex_id)

Wakeup side:srv_lockmutex(mutex_id)
status = DONE;
srv_wakeup(...)
srv_unlockmutex(mutex_id)

If a srv_sleep call returns because of a time-out, the location pointed to by the infop parameter will be set to SRV_I_TIMEOUT. In this case, as in all others, the mutex is reacquired before the srv_sleep call returns. The normal usage of srv_sleep in the native threads version should be within a loop checking the predicate. For example:

mutex_lock()
        while (work != DONE)
        {
                srv_sleep(...);
        }
    mutex_unlock()

In this usage, the time-out is not useful because it is reset each time.

srv_props

The property SRV_S_NATIVEMUTEX has been added to srv_props(). You can set SRV_S_NATIVEMUTEX to CS_TRUE or CS_FALSE. The default is CS_FALSE. If set to CS_TRUE, the srv_createmutex, srv_lockmutex, srv_unlockmutex, and srv_deletemutex APIs use native (operating system) mutexes. If set to CS_FALSE, these APIs use Open Server mutexes.

Mutex operations will be faster if you set the SRV_S_NATIVEMUTEX property to CS_TRUE because mutex operations will map almost directly to operating system mutex operations. Currently, Open Server allows mutexes to be referred to by name. This requires that mutexes and their names be stored in tables. When you set SRV_S_NATIVEMUTEX property to CS_FALSE, mutex operations require table lookups; these table lookups must be synchronized with other threads to ensure that the mutex table does not become corrupt.

Mutexes created when SRV_S_NATIVEMUTEX is set to CS_FALSE support recursive locking.

Mutexes created when SRV_S_NATIVEMUTEX is set to CS_TRUE do not support recursive locking. If a mutex is locked, any attempt to lock it a second time, even by the same thread that originally locked it, will block the thread.

srv_deletemutex

srv_deletemutex() has been modified so that only an unlocked mutex can be deleted.

srv_dropproc

srv_dropproc() has been modified so that asynchronous or involuntary thread terminations are not allowed.

Event handler prototypes

Jaguar supports two additional event handlers, "Initialization" and "Error". The initialization handler (or init handler) is used to perform any customization the application requires. Ideally, all of your main() code goes into the init handler. The prototype for all the existing open server event handler remains the same.

Initialization handler prototype

typedef CS_RETCODE  (CS_PUBLIC * SRV_INITHANDLE_FUNC)
        PROTOTYPE((
            CS_CONTEXT  *context,
            CS_INT      argc,
            CS_CHAR     **argv
            ));

context - is pointer to the CS_CONTEXT structure.

Initialization handlers must return CS_SUCCEED unless an error occurs that prevents the application from running successfully. Returning a value other than CS_SUCCEED aborts the server startup sequence.

You can use the initialization handler or the run handler to initialize your application's global resources, or you can install handlers for both events. The server log file is not open when the initialization handler is called. If you need to write messages to the log (using JagLog), use a start handler rather than the initialization handler.

Error handler prototype

Install error handlers through Jaguar Manager and not srv_props() or srv_errhandle(). Refer to "Installing event handlers" for more information.

typedef CS_RETCODE  (CS_PUBLIC * SRV_ERRORHANDLE_FUNC) 
        PROTOTYPE((
             CS_CONTEXT  *context,
             CS_VOID     *argp,
             CS_INT      where,
             CS_SERVERMSG    *msg
             ));

Refer to "Additional event handler information" for information about all event handlers.