Ns_SockCallback

Overview

Syntax

    int Ns_SockCallback (
    	SOCKET				sock,
    	Ns_SockProc				*proc,
    	void				*ctx,
    	int				when
    );

Description

The proc is your socket callback function. The ctx argument is your context which will be passed back as the second argument of your callback function.

The when argument is a bitmask with one or more of the following options specified:

NS_SOCK_READ:	the socket is readable
NS_SOCK_WRITE:	the socket is writeable
NS_SOCK_EXCEPTION:	the socket has an exceptional condition
NS_SOCK_EXIT:	the server is shutting down

At startup time, AOLserver creates a single socket service thread dedicated to handling socket callbacks. Since several sockets are needed to listen for connection requests, and because connection requests are handled so quickly, all the socket drivers in all the virtual servers share a single thread for that purpose.

The result of this optimization is that AOLserver requires no per-server threads, which can greatly increase the number of servers per process. This is especially beneficial on the SGI platform, where threads use up system process entries.

Example

1. Create a C callback function to handle a request. The callback function must execute without blocking so that other sockets can get serviced. Typically, the callback function just performs an accept() call and queues the request. The prototype is:

       typedef int (Ns_SockProc) (SOCKET sock, void *context, 
   int why);
   

   The parameters are:

   sock	the registered socket
   context	your context passed to Ns_SockCallback()
   why	the reason the function was called, which is one of the following: NS_SOCK_READ: the socket is readable NS_SOCK_WRITE: the socket is writeable NS_SOCK_EXCEPTION: the socket has an exceptional condition NS_SOCK_EXIT: the server is shutting down

   The callback function must return either NS_TRUE to tell the socket thread to keep watching the socket or NS_FALSE to tell the socket thread to stop watching the socket.

   For example:

       int
       MySock(SOCKET sock, void *context, int why)
       {
       	if (why == NS_SOCK_READ) {
       		.. handle read ..
       		if (error) {	
       			return NS_FALSE;
       		} else {
       			return NS_TRUE;
       		}
       	} else if (why == NS_SOCK_EXIT) {
       		.. free(context) ..
       		return NS_FALSE;
       	}
       }
   

2. At server startup time, your module must register your callback function with the server using the Ns_SockCallback() function.

   This example specifies that MySock will be called when the socket is readable or when the server is shutting down:

       Ns_SockCallback(sock, MySock, myCtx, 
       	NS_SOCK_READ | NS_SOCK_EXIT);
   

   Remember that there is only one socket service thread, so your callback function must return immediately without blocking!