| iMatix home page
| << | < | > | >> 		SMT Logo SMT
Version 2.81
 

The Socket I/O Agent - SMTSOCK

Handles input and output to TCP and UDP sockets. You should use this agent for all access to TCP or UDP sockets, although you can also access sockets directly using the SFL socket access functions. Socket i/o is both central to most Internet servers, and reasonably delicate, making it a task that is well done by a specific agent.

SMTSOCK has two main functions: it acts as the central 'heartbeat' for an Internet server, and it perform input and output on sockets. The heartbeat function works as follows: SMTSOCK uses the select() function to monitor all open sockets. Each socket is owned by a thread, somewhere. When a socket shows signs of life, SMTSOCK sends an event to the appropriate thread. The thread can then decide to read or write data as required. In a typical Internet application -- such as the XITAMI web server -- the socket agent is the main source of the events that drive the application. By contrast, in non-Internet applications the 'heartbeat' role could be played by the timer agent SMTTIME.

The second task for SMTSOCK is input and output on sockets. For instance, you can ask SMTSOCK to read data from a socket, or to write a block of data to a socket. Both these tasks can require multiple cycles, waiting until the socket is ready, then reading/writing as much data as possible, until all the data has been read/written. SMTSOCK handles this automatically.

To use SMTSOCK, call smtsock init(). This creates a single unnamed thread automatically the first time it is called, and has no effect thereafter. You can then send messages to this thread. SMTSOCK replies to most events. It supports these methods:

Example of initialising SMTSOCK: 

/*  Static data                                                 */
static QID
    sockq;                      /*  Socket agent event queue    */

    /*  In agent initialisation code                            */
    THREAD  *thread;            /*  Handle to various threads   */

    /*  Reply events from socket agent                          */
    method declare (agent, "SOCK_INPUT_OK",  ok_event,       0);
    method declare (agent, "SOCK_OUTPUT_OK", ok_event,       0);
    method declare (agent, "SOCK_READ_OK",   read_ok_event,  0);
    method declare (agent, "SOCK_WRITE_OK",  write_ok_event, 0);
    method declare (agent, "SOCK_CLOSED",    closed_event,   0);
    method declare (agent, "SOCK_ERROR",     error_event,    0);
    method declare (agent, "SOCK_TIMEOUT",   error_event,    0);

    /*  Ensure that socket agent is running, else start it      */
    smtsock init ();
    if ((thread = thread lookup (SMT_SOCKET, "")) != NULL)
        sockq = thread-> queue-> qid;
    else
        return (-1);

The READ Method

Waits for, and reads data from a socket. TCP/IP breaks a stream of data into chunks of arbitrary size, and each low-level read operation will read one such chunk. Thus, to read a specific amount of data, you may need to make several low-level read calls. SMTSOCK packages this so that one READ event can read as much data as required. You can alternatively ask SMTSOCK to read just the next chunk sent by TCP/IP. Build the event body using exdr_write() and the message definition SMT_SOCK_READ. The event body consists of these fields (see exdr_write() for the field types):

SMTSOCK replies to a READ event with one of these events:

The READR Method

Works in the same way as the READ method, but works repeatedly until a FLUSH is sent for the socket. The READR method is useful for servers that have to loop on reading a socket; it saves the need for sending fresh READ events.

The WRITE Method

Writes a block of data to a socket. If you call the low-level TCP/IP write function directly, you must handle various error and retry conditions. It is easier and safer to use SMTSOCK to do this. Build the event body using exdr_write() and the message definition SMT_SOCK_WRITE. The event body consists of these fields:

SMTSOCK replies to a WRITE event with one of these events:

The INPUT Method

Waits for input to arrive on a socket. This can be data, or a connection request. Build the event body using exdr_write() and the message definition SMT_SOCK_INPUT. The event body consists of these fields:

SMTSOCK replies to an INPUT event with one of these events:

The INPUTR Method

Works in the same way as the INPUT method, but works repeatedly until a FLUSH is sent for the socket. The INPUTR method is useful for servers that have to loop on waiting for a socket; it saves the need for sending fresh INPUT events.

The OUTPUT Method

Waits for a socket to be ready for output. If you use the low- level TCP/IP write functions, you must be sure that the socket is ready for output, or your thread will block the entire application if it has to wait. Build the event body using exdr_write() and the message definition SMT_SOCK_OUTPUT. The event body consists of these fields:

SMTSOCK replies to an OUTPUT event with one of these events:

The CONNECT Method

Establishes a TCP or UDP connection to some specified host and service (or port). Build the event body using exdr_write() and the message definition SMT_SOCK_CONNECT. The event body consists of these fields:

SMTSOCK replies to a CONNECT event with one of these events:

The FLUSH Method

Removes any requests for a socket. Since events are delivered in a straight first-in first-out basis (ignoring the high priority SHUTDOWN event) it is safe to send first a FLUSH event, followed by another event, with no intervening wait. Build the event body using exdr_write() and the message definition SMT_SOCK_FLUSH. The event body consists of these fields:

SMTSOCK does not reply to a FLUSH event.

Example Of Use

The SMTECHO agent provides a good basic example of using SMTSOCK. Study this program, and use it as a basis for your own socket-based agents.

Notes and Comments

The SOCK_CLOSED and SOCK_TIMEOUT return events can come from various requests; to make processing of this possible, they are always formatted as SOCK_READ_OK events.

SMTSOCK Implementation

The hypertext view of SMTSOCK's dialog and source code may help to understand how SMTSOCK works.

| << | < | > | >> iMatix Copyright © 1996-99 iMatix Corporation