srv_callback

Description

Install a state transition handler for a thread.

Syntax

CS_RETCODE srv_callback(spp, callback_type, funcp)

SRV_PROC         *spp;
CS_INT                callback_type;
CS_RETCODE     (*funcp)();

Parameters

spp: A pointer to an internal thread control structure.

callback_type

An integer that indicates the state transition for which the callback is being installed. Table 3-16 summarizes the legal values for callback_type:

**Table 3-16: Values for callback_type (srv_callback)**
Value	Description
SRV_C_EXIT	The thread has returned from the entry point specified in srv_spawn or is associated with a disconnected client. The handler is executed in the context of the exiting thread.
SRV_C_PROCEXEC	A registered procedure has been invoked and is about to execute. The handler executes in the context of the thread that requested the registered procedure.
SRV_C_RESUME	The thread is resuming. The handler executes in the scheduler thread’s context and uses its stack.
SRV_C_SUSPEND	The thread is suspending. The handler executes in the context of the thread that is suspending and uses its stack.
SRV_C_TIMESLICE	The callback routine you install for this state transition is called when a thread has executed for a period of time (time slice) determined by the SRV_S_TIMESLICE, SRV_S_VIRTCLKRATE, and SRV_S_VIRTTIMER server properties. See srv_props and “Properties”.

funcp: A pointer to the function to call when the specified state transition occurs.

A callback function takes a thread pointer argument.

Returns

**Table 3-17: Return values (srv_callback))**
Returns	To indicate
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Examples

Example 1

#include          <stdio.h>

#include          <ospublic.h>

/*

 ** Local Prototype

*/

CS_RETCODE        suspend_handler PROTOTYPE((

SRV_PROC          *srvproc

));

CS_RETCODE ex_srv_callback PROTOTYPE((

SRV_PROC          *srvproc

));

CS_RETCODE     suspend_handler(srvproc)

SRV_PROC       *srvproc;

     printf(“Wake me when it’s over...\n”);

     return(CS_SUCCEED);

/*

** EX_SRV_CALLBACK

**

**     Example routine to install a state transition handler.

**

** Arguments:

**   srvpro  - A pointer to an internal thread control structure.

**

** Returns:

**

**     CS_SUCCEED

**     CS_FAIL

*/

CS_RETCODE          ex_srv_callback(srvproc)

SRV_PROC            *srvproc;

     return(srv_callback(srvproc, SRV_C_SUSPEND,

                 suspend_handler));

Usage

Use srv_callback to specify a routine to execute when a thread passes from one state to another.

An application calls the callback routine with a pointer to the thread that is changing states.

Table 3-18 summarizes the value each type of callback routine should return:

**Table 3-18: Valid returns for callback routines (srv_callback)**
Type of callback routine	Return value	Description of return value
SRV_C_EXIT	Ignored by Open Server, but should be set to SRV_CONTINUE for the sake of future compatibility.
SRV_C_PROCEXEC	SRV_S_INHIBIT	Cancel execution of the registered procedure.
SRV_C_PROCEXEC	SRV_S_CONTINUE	Continue execution of the registered procedure.
SRV_C_RESUME	Ignored by Open Server, but should be set to SRV_CONTINUE for the sake of future compatibility.
SRV_C_SUSPEND	Ignored by Open Server, but should be set to SRV_CONTINUE for the sake of future compatibility.
SRV_C_TIMESLICE	SRV_CONTINUE	Continue execution uninterrupted.
	SRV_TERMINATE	Terminate the thread.
	SRV_DEBUG	Add the thread to the debug queue for subsequent examination with a debugger.

Some callback types are not available on some platforms. You can call srv_capability to find out if a handler can be installed for a callback type on the current platform.

To remove a callback routine installed by a previous call to srv_callback, install a null function in its place. For example, to de-install a previously SRV_C_TIMESLICE handler, issue the following command:

     srv_callback(spp, SRV_C_TIMESLICE, NULL);

Set the funcp argument to NULL if your application will use the callback handler for notifications only. See “Registered procedures” for more details.