Annotation of libwww/Library/src/HTNet.html, revision 2.26

2.1       frystyk     1: <HTML>
                      2: <HEAD>
2.17      frystyk     3: <TITLE>Asyncronous Socket Management</TITLE>
2.26    ! frystyk     4: <!-- Changed by: Henrik Frystyk Nielsen, 22-Nov-1995 -->
2.1       frystyk     5: </HEAD>
                      6: <BODY>
2.2       frystyk     7: 
2.17      frystyk     8: <H1>Asyncronous Socket Management</H1>
2.1       frystyk     9: 
2.5       frystyk    10: <PRE>
                     11: /*
2.8       frystyk    12: **     (c) COPYRIGHT MIT 1995.
2.5       frystyk    13: **     Please first read the full copyright statement in the file COPYRIGH.
                     14: */
                     15: </PRE>
                     16: 
2.1       frystyk    17: This module contains the routines for handling the set of active
2.2       frystyk    18: sockets currently in use by the multithreaded clients. It is an
                     19: internal module to the Library, the application interface is
2.15      frystyk    20: implemented in the <A HREF="HTEvntrg.html">Event Module</A>. Look for
2.2       frystyk    21: more information in the <A
2.17      frystyk    22: HREF="http://www.w3.org/pub/WWW/Library/User/Architecture/">
2.2       frystyk    23: Multithread Specifications</A>. <P>
2.1       frystyk    24: 
2.17      frystyk    25: This module is implemented by <A HREF="HTNet.c">HTNet.c</A>, and it is
                     26: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C
                     27: Reference Library</A>.
2.1       frystyk    28: 
                     29: <PRE>
2.17      frystyk    30: #ifndef HTNET_H
                     31: #define HTNET_H
2.21      frystyk    32: #include "HTEvntrg.h"
2.17      frystyk    33: #include "HTReq.h"
2.1       frystyk    34: </PRE>
                     35: 
2.17      frystyk    36: <H2>The HTNet Object</H2>
2.1       frystyk    37: 
2.17      frystyk    38: The <CODE>HTNet</CODE> object is the core of the request queue
                     39: management. This object contains information about the socket
                     40: descriptor, the input read buffer etc. required to identify and
                     41: service a request. <P>
2.1       frystyk    42: 
                     43: <PRE>
2.18      frystyk    44: typedef struct _HTNet HTNet;
2.1       frystyk    45: </PRE>
                     46: 
2.24      frystyk    47: <H2>Request Call Back Functions</H2>
2.17      frystyk    48: 
2.24      frystyk    49: Callback functions can be registered to be called <EM>before</EM> and
                     50: <EM>after</EM> a request has either been started or has
                     51: terminated. The following functions are the generic registration
                     52: mechanisms where we use lists as the basic data container. Then there
                     53: is two methods for binding a list of callback functions to the set
                     54: which is called <EM>before</EM> and to the set set which is called
                     55: <EM>after</EM> <P>
                     56: 
                     57: In both cases there can be more than one callback function which are
2.17      frystyk    58: called on turn and each callback function can be associated with a
                     59: status code of the request. For example one callback function can be
                     60: registered for HT_LOADED, another for HT_ERROR etc.
                     61: 
                     62: <H3>Register a Request Callback</H3>
2.2       frystyk    63: 
2.17      frystyk    64: Register a call back function that is to be called on every
                     65: termination of a request. Several call back functions can be
                     66: registered in which case all of them are called in the reverse order
2.24      frystyk    67: of which they were registered (last one first). We name the calling
                     68: mechansm of calling the functions for the <EM>before</EM> loop and the
                     69: <EM>after</EM> loop.<P>
                     70: 
                     71: In case the callback function is registered as being called
                     72: <EM>after</EM> the request has terminated the result of the request is
                     73: passed to the fucntion. The status signifies which call back function
                     74: to call depending of the result of the request. This can be
2.1       frystyk    75: 
2.17      frystyk    76: <DL>
                     77: <DT>HT_ERROR
                     78: <DD>An error occured
                     79: <DT>HT_LOADED
                     80: <DD>The document was loaded
                     81: <DT>HT_NO_DATA
                     82: <DD>OK, but no data
                     83: <DT>HT_RETRY
                     84: <DD>Retry request after at a later time
2.24      frystyk    85: <DT>HT_REDIRECT
                     86: <DD>The request has been redirected and we send back the new URL
2.17      frystyk    87: <DT>HT_ALL
                     88: <DD>All of above
                     89: </DL>
2.1       frystyk    90: 
2.24      frystyk    91: Any callback function any code it likes, but <B>IF NOT</B> the code is
                     92: <EM>HT_OK</EM>, then the callback loop is stopped. If we are in the
                     93: <EM>before</EM> loop and a function returns anything else than
                     94: <EM>HT_OK</EM> then we immediately jump to the <EM>after</EM> loop
                     95: <B>passing</B> the last return code from the <EM>before</EM> loop.
                     96: 
2.1       frystyk    97: <PRE>
2.23      frystyk    98: typedef int HTNetCallback (HTRequest * request, int status);
2.17      frystyk    99: 
2.24      frystyk   100: extern BOOL HTNetCall_add (HTList * list, HTNetCallback *cbf, int status);
2.9       frystyk   101: </PRE>
                    102: 
2.24      frystyk   103: <H3>Delete a single Callbak</H3>
2.9       frystyk   104: 
2.24      frystyk   105: Removes a callback function from a list
2.9       frystyk   106: 
                    107: <PRE>
2.24      frystyk   108: extern BOOL HTNetCall_delete (HTList * list, HTNetCallback *cbf);
2.1       frystyk   109: </PRE>
                    110: 
2.24      frystyk   111: <H3>Delete a list of Callbacks</H3>
                    112: 
                    113: Unregisters all call back functions in the list
                    114: 
                    115: <PRE>
                    116: extern BOOL HTNetCall_deleteAll (HTList * list);
                    117: </PRE>
                    118: 
                    119: <H3>Call List of Registered Callback Functions</H3>
2.10      frystyk   120: 
2.17      frystyk   121: Call all the call back functions registered in the list IF not the
2.24      frystyk   122: status is HT_IGNORE.  The callback functions are called in the order
                    123: of which they were registered. At the moment an application callback
                    124: function is called, it can free the request object - it is no longer
                    125: used by the Library. Returns what the last callback function returns
                    126: 
                    127: <PRE>
                    128: extern int HTNetCall_execute (HTList * list, HTRequest * request, int status);
                    129: </PRE>
                    130: 
                    131: <H3>BEFORE Callbacks</H3>
                    132: 
                    133: Global set of callback functions BEFORE the request is issued. The
                    134: list can be NULL.
                    135: 
                    136: <PRE>
2.25      frystyk   137: extern BOOL HTNetCall_addBefore        (HTNetCallback *cbf, int status);
2.24      frystyk   138: extern BOOL HTNet_setBefore    (HTList * list);
                    139: extern HTList * HTNet_before   (void);
                    140: extern int HTNet_callBefore    (HTRequest *request, int status);
                    141: </PRE>
                    142: 
                    143: <H3>AFTER Callbacks</H3>
                    144: 
                    145: Global set of callback functions AFTER the request is issued. The list can be NULL
2.10      frystyk   146: 
                    147: <PRE>
2.25      frystyk   148: extern BOOL HTNetCall_addAfter (HTNetCallback *cbf, int status);
2.24      frystyk   149: extern BOOL HTNet_setAfter     (HTList * list);
                    150: extern HTList * HTNet_after    (void);
                    151: extern int HTNet_callAfter     (HTRequest *request, int status);
2.10      frystyk   152: </PRE>
                    153: 
2.17      frystyk   154: <H2>Request Queue</H2>
                    155: 
                    156: The request queue ensures that no more than a fixed number of TCP
                    157: connections are open at the same time. If more requests are handed to
                    158: the Library, they are put into the pending queue and initiated when
                    159: sockets become free.
                    160: 
                    161: <H3>Number of Simultanous open TCP connections</H3>
2.1       frystyk   162: 
2.17      frystyk   163: Set the max number of simultanous sockets. The default value is
2.19      frystyk   164: HT_MAX_SOCKETS which is 6. The number of persistent connections depend
                    165: on this value as a deadlock can occur if all available sockets a
                    166: persistent (see the <A HREF="HTDNS.html">DNS Manager</A> for more
                    167: information on setting the number of persistent connections). The
                    168: number of persistent connections can never be more than the max number
                    169: of sockets-2, so letting newmax=2 prevents persistent sockets.
2.1       frystyk   170: 
                    171: <PRE>
2.17      frystyk   172: extern BOOL HTNet_setMaxSocket (int newmax);
                    173: extern int  HTNet_maxSocket (void);
2.1       frystyk   174: </PRE>
                    175: 
2.23      frystyk   176: <H3>List Active Queue</H3>
2.1       frystyk   177: 
2.17      frystyk   178: Returns the list of active requests that are currently having an open
2.22      frystyk   179: connection. Returns list of HTNet objects or NULL if
                    180: error. <CODE>HTNet_idle()</CODE> returns YES if no active sockets are
                    181: registered.
2.1       frystyk   182: 
                    183: <PRE>
2.17      frystyk   184: extern HTList *HTNet_activeQueue (void);
2.22      frystyk   185: extern BOOL HTNet_idle (void);
2.1       frystyk   186: </PRE>
2.17      frystyk   187: 
2.23      frystyk   188: <H3>List Pending Queue</H3>
2.17      frystyk   189: 
                    190: Returns the list of pending requests that are waiting to become
                    191: active. Returns list of HTNet objects or NULL if error
                    192: 
2.1       frystyk   193: <PRE>
2.17      frystyk   194: extern HTList *HTNet_pendingQueue (void);
2.1       frystyk   195: </PRE>
                    196: 
2.23      frystyk   197: <H2>HTNet Object Methods</H2>
2.17      frystyk   198: 
                    199: These methods are used from within the Request Manager and are not
                    200: normally to be used outside the Library kernel.
                    201: 
                    202: <H3>Create an Object</H3>
                    203: 
                    204: Create a new HTNet object as a new request to be handled. If we have
                    205: more than HTMaxActive connections already then put this into the
                    206: pending queue, else start the request by calling the call back
                    207: function registered with this access method.  Returns YES if OK, else
                    208: NO
                    209: 
                    210: <PRE>
2.23      frystyk   211: extern BOOL HTNet_new (HTRequest * request);
2.26    ! frystyk   212: </PRE>
        !           213: 
        !           214: <H3>Create an Empty Object</H3>
        !           215: 
        !           216: This function creates a new HTNet object and assigns the socket number
        !           217: to it. This is intended to be used when you are going to listen on a
        !           218: socket using the HTDoListen() function in HTTCP.c. The function do NOT
        !           219: call any of the callback functions.  Returns YES if OK, else NO
        !           220: 
        !           221: <PRE>
        !           222: extern BOOL HTNet_create (HTRequest * request, SOCKET sockfd);
2.20      frystyk   223: </PRE>
                    224: 
                    225: <H3>Duplicate an Existing Object</H3>
                    226: 
                    227: Creates a new HTNet object as a duplicate of the same request.
                    228: Returns YES if OK, else NO.
                    229: 
                    230: <PRE>
                    231: extern BOOL HTNet_dup (HTNet *src, HTNet **dest);
2.17      frystyk   232: </PRE>
                    233: 
2.23      frystyk   234: <H3>Make an Object Wait</H3>
2.19      frystyk   235: 
                    236: Let a net object wait for a persistent socket. It will be launched
                    237: from the HTNet_delete() function when the socket gets free.
                    238: 
                    239: <PRE>
                    240: extern BOOL HTNet_wait (HTNet *net);
                    241: </PRE>
                    242: 
2.23      frystyk   243: <H3>Priority Management</H3>
                    244: 
                    245: Each HTNet object is created with a priority which it inherits from
                    246: the <A HREF="HTReq.html">Request manager</A>. However, in some
                    247: stuations it is useful to be to change the current priority after the
                    248: request has been started. These two functions allow you to do
                    249: this. The effect will show up the first time (which might be
                    250: imidiately) the socket blocks and control returns to the event loop.
                    251: Also have a look at how you can do this before the request is issued
                    252: in the <A HREF="HTReq.html">request manager</A>.
                    253: 
                    254: <PRE>
                    255: extern HTPriority HTNet_priority (HTNet * net);
                    256: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
                    257: </PRE>
                    258: 
2.17      frystyk   259: <H3>Delete an Object</H3>
                    260: 
                    261: Deletes the HTNet object from the list of active requests and calls
                    262: any registered call back functions IF not the status is HT_IGNORE.
                    263: This is used if we have internal requests that the app doesn't know
                    264: about. We also see if we have pending requests that can be started up
                    265: now when we have a socket free. The callback functions are called in
2.24      frystyk   266: the reverse order of which they were registered (last one first);
2.1       frystyk   267: 
                    268: <PRE>
2.17      frystyk   269: extern BOOL HTNet_delete (HTNet * me, int status);
2.1       frystyk   270: </PRE>
                    271: 
2.17      frystyk   272: <H3>Delete ALL HTNet Objects</H3>
2.1       frystyk   273: 
2.17      frystyk   274: Deletes all HTNet object that might either be active or pending We DO
2.19      frystyk   275: NOT call the call back functions - A crude way of saying goodbye!
2.1       frystyk   276: 
                    277: <PRE>
2.17      frystyk   278: extern BOOL HTNet_deleteAll (void);
2.1       frystyk   279: </PRE>
2.17      frystyk   280: 
                    281: <H3>Kill a Request</H3>
2.1       frystyk   282: 
2.17      frystyk   283: Kill the request by calling the call back function with a request for
                    284: closing the connection. Does not remove the object. This is done by
                    285: HTNet_delete() function which is called by the load routine.  Returns
                    286: OK if success, NO on error
2.1       frystyk   287: 
                    288: <PRE>
2.17      frystyk   289: extern BOOL HTNet_kill (HTNet * me);
2.1       frystyk   290: </PRE>
                    291: 
2.17      frystyk   292: <H3>Kill ALL requests</H3>
2.1       frystyk   293: 
2.17      frystyk   294: Kills all registered (active+pending) requests by calling the call
                    295: back function with a request for closing the connection. We do not
                    296: remove the HTNet object as it is done by HTNet_delete().  Returns OK
                    297: if success, NO on error
2.1       frystyk   298: 
                    299: <PRE>
2.17      frystyk   300: extern BOOL HTNet_killAll (void);
                    301: </PRE>
2.1       frystyk   302: 
2.17      frystyk   303: <PRE>
                    304: #endif /* HTNET_H */
2.1       frystyk   305: </PRE>
                    306: 
2.17      frystyk   307: End of declaration module
2.1       frystyk   308: </BODY>
                    309: </HTML>
                    310: 
                    311: 

Webmaster