Annotation of libwww/Library/src/HTNet.html, revision 2.23
2.1 frystyk 1: <HTML>
2: <HEAD>
2.17 frystyk 3: <TITLE>Asyncronous Socket Management</TITLE>
2.23 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 2-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.17 frystyk 47: <H2>Request Termination Call Back Functions</H2>
48:
49: The termination callback functions is a set of functions that can be
50: registered by the application to be called when a request has
51: terminated. There can be more than one callback function which are
52: called on turn and each callback function can be associated with a
53: status code of the request. For example one callback function can be
54: registered for HT_LOADED, another for HT_ERROR etc.
55:
56: <H3>Register a Request Callback</H3>
2.2 frystyk 57:
2.17 frystyk 58: Register a call back function that is to be called on every
59: termination of a request. Several call back functions can be
60: registered in which case all of them are called in the reverse order
61: of which they were registered (last one first). The status signifies
62: which call back function to call depending of the result of the
63: request. This can be
2.1 frystyk 64:
2.17 frystyk 65: <DL>
66: <DT>HT_ERROR
67: <DD>An error occured
68: <DT>HT_LOADED
69: <DD>The document was loaded
70: <DT>HT_NO_DATA
71: <DD>OK, but no data
72: <DT>HT_RETRY
73: <DD>Retry request after at a later time
74: <DT>HT_ALL
75: <DD>All of above
76: </DL>
2.1 frystyk 77:
78: <PRE>
2.23 ! frystyk 79: typedef int HTNetCallback (HTRequest * request, int status);
2.17 frystyk 80:
2.23 ! frystyk 81: extern BOOL HTNet_register (HTNetCallback *cbf, int status);
2.9 frystyk 82: </PRE>
83:
2.17 frystyk 84: <H3>Unregister</H3>
2.9 frystyk 85:
2.17 frystyk 86: Unregister call back functions
2.9 frystyk 87:
88: <PRE>
2.23 ! frystyk 89: extern BOOL HTNet_unregister (HTNetCallback *cbf);
2.17 frystyk 90: extern BOOL HTNet_unregisterAll (void);
2.1 frystyk 91: </PRE>
92:
2.23 ! frystyk 93: <H3>Call the Call Back Functions</H3>
2.10 frystyk 94:
2.17 frystyk 95: Call all the call back functions registered in the list IF not the
96: status is HT_IGNORE. The callback functions are called in the reverse
97: order of which they were registered (last one first). Returns YES if
98: OK, else NO.
2.10 frystyk 99:
100: <PRE>
2.17 frystyk 101: extern BOOL HTNet_callback (HTRequest * me, int status);
2.10 frystyk 102: </PRE>
103:
2.17 frystyk 104: <H2>Request Queue</H2>
105:
106: The request queue ensures that no more than a fixed number of TCP
107: connections are open at the same time. If more requests are handed to
108: the Library, they are put into the pending queue and initiated when
109: sockets become free.
110:
111: <H3>Number of Simultanous open TCP connections</H3>
2.1 frystyk 112:
2.17 frystyk 113: Set the max number of simultanous sockets. The default value is
2.19 frystyk 114: HT_MAX_SOCKETS which is 6. The number of persistent connections depend
115: on this value as a deadlock can occur if all available sockets a
116: persistent (see the <A HREF="HTDNS.html">DNS Manager</A> for more
117: information on setting the number of persistent connections). The
118: number of persistent connections can never be more than the max number
119: of sockets-2, so letting newmax=2 prevents persistent sockets.
2.1 frystyk 120:
121: <PRE>
2.17 frystyk 122: extern BOOL HTNet_setMaxSocket (int newmax);
123: extern int HTNet_maxSocket (void);
2.1 frystyk 124: </PRE>
125:
2.23 ! frystyk 126: <H3>List Active Queue</H3>
2.1 frystyk 127:
2.17 frystyk 128: Returns the list of active requests that are currently having an open
2.22 frystyk 129: connection. Returns list of HTNet objects or NULL if
130: error. <CODE>HTNet_idle()</CODE> returns YES if no active sockets are
131: registered.
2.1 frystyk 132:
133: <PRE>
2.17 frystyk 134: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 135: extern BOOL HTNet_idle (void);
2.1 frystyk 136: </PRE>
2.17 frystyk 137:
2.23 ! frystyk 138: <H3>List Pending Queue</H3>
2.17 frystyk 139:
140: Returns the list of pending requests that are waiting to become
141: active. Returns list of HTNet objects or NULL if error
142:
2.1 frystyk 143: <PRE>
2.17 frystyk 144: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 145: </PRE>
146:
2.23 ! frystyk 147: <H2>HTNet Object Methods</H2>
2.17 frystyk 148:
149: These methods are used from within the Request Manager and are not
150: normally to be used outside the Library kernel.
151:
152: <H3>Create an Object</H3>
153:
154: Create a new HTNet object as a new request to be handled. If we have
155: more than HTMaxActive connections already then put this into the
156: pending queue, else start the request by calling the call back
157: function registered with this access method. Returns YES if OK, else
158: NO
159:
160: <PRE>
2.23 ! frystyk 161: extern BOOL HTNet_new (HTRequest * request);
2.20 frystyk 162: </PRE>
163:
164: <H3>Duplicate an Existing Object</H3>
165:
166: Creates a new HTNet object as a duplicate of the same request.
167: Returns YES if OK, else NO.
168:
169: <PRE>
170: extern BOOL HTNet_dup (HTNet *src, HTNet **dest);
2.17 frystyk 171: </PRE>
172:
2.23 ! frystyk 173: <H3>Make an Object Wait</H3>
2.19 frystyk 174:
175: Let a net object wait for a persistent socket. It will be launched
176: from the HTNet_delete() function when the socket gets free.
177:
178: <PRE>
179: extern BOOL HTNet_wait (HTNet *net);
180: </PRE>
181:
2.23 ! frystyk 182: <H3>Priority Management</H3>
! 183:
! 184: Each HTNet object is created with a priority which it inherits from
! 185: the <A HREF="HTReq.html">Request manager</A>. However, in some
! 186: stuations it is useful to be to change the current priority after the
! 187: request has been started. These two functions allow you to do
! 188: this. The effect will show up the first time (which might be
! 189: imidiately) the socket blocks and control returns to the event loop.
! 190: Also have a look at how you can do this before the request is issued
! 191: in the <A HREF="HTReq.html">request manager</A>.
! 192:
! 193: <PRE>
! 194: extern HTPriority HTNet_priority (HTNet * net);
! 195: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
! 196: </PRE>
! 197:
2.17 frystyk 198: <H3>Delete an Object</H3>
199:
200: Deletes the HTNet object from the list of active requests and calls
201: any registered call back functions IF not the status is HT_IGNORE.
202: This is used if we have internal requests that the app doesn't know
203: about. We also see if we have pending requests that can be started up
204: now when we have a socket free. The callback functions are called in
205: the reverse order of which they were registered (last one first)
2.1 frystyk 206:
207: <PRE>
2.17 frystyk 208: extern BOOL HTNet_delete (HTNet * me, int status);
2.1 frystyk 209: </PRE>
210:
2.17 frystyk 211: <H3>Delete ALL HTNet Objects</H3>
2.1 frystyk 212:
2.17 frystyk 213: Deletes all HTNet object that might either be active or pending We DO
2.19 frystyk 214: NOT call the call back functions - A crude way of saying goodbye!
2.1 frystyk 215:
216: <PRE>
2.17 frystyk 217: extern BOOL HTNet_deleteAll (void);
2.1 frystyk 218: </PRE>
2.17 frystyk 219:
220: <H3>Kill a Request</H3>
2.1 frystyk 221:
2.17 frystyk 222: Kill the request by calling the call back function with a request for
223: closing the connection. Does not remove the object. This is done by
224: HTNet_delete() function which is called by the load routine. Returns
225: OK if success, NO on error
2.1 frystyk 226:
227: <PRE>
2.17 frystyk 228: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 229: </PRE>
230:
2.17 frystyk 231: <H3>Kill ALL requests</H3>
2.1 frystyk 232:
2.17 frystyk 233: Kills all registered (active+pending) requests by calling the call
234: back function with a request for closing the connection. We do not
235: remove the HTNet object as it is done by HTNet_delete(). Returns OK
236: if success, NO on error
2.1 frystyk 237:
238: <PRE>
2.17 frystyk 239: extern BOOL HTNet_killAll (void);
240: </PRE>
2.1 frystyk 241:
2.17 frystyk 242: <PRE>
243: #endif /* HTNET_H */
2.1 frystyk 244: </PRE>
245:
2.17 frystyk 246: End of declaration module
2.1 frystyk 247: </BODY>
248: </HTML>
249:
250:
Webmaster