Annotation of libwww/Library/src/HTEvent.html, revision 2.4
2.1 eric 1: <HTML>
2: <HEAD>
2.4 ! frystyk 3: <TITLE>W3C Reference Library libwww Event Class</TITLE>
2.1 eric 4: </HEAD>
5: <BODY>
2.4 ! frystyk 6: <H1>
! 7: The Event Class
2.3 frystyk 8: </H1>
2.1 eric 9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
2.4 ! frystyk 14: </PRE>
! 15: <P>
! 16: The Event Class defines any event manager to be used by libwww for handling
! 17: events. An <I>event</I> is not strictly defined as it is highly platform
! 18: dependent and hence out of scope for the Library. If you are using the libwww
! 19: pseudo threads on Unix then an event is when the <I>select()</I> system
! 20: call returns a notification on a socket descriptor, but it may as well
! 21: be an asynchronous event from the windows manager etc. If your application
! 22: is not using anything but traditional blocking sockets then you do not need
! 23: an event manager at all. In that case, libwww will block on any socket or
! 24: system call until the process can proceed.
! 25: <P>
! 26: The libwww interface to an event manager is very simple as it consists of
! 27: <B>registering</B> a <I>socket descriptor</I>, the <I>location</I> in the
! 28: program, and the <I>current state</I> when an operation (for example
! 29: <CODE>read</CODE>) would block. When the event manager at a later point in
! 30: time gets a notification that the socket has become ready, it can then call
! 31: libwww with the state saved from the registration and libwww can continue.
! 32: Second, libwww must be able to <B>unregister</B> a socket when it is not
! 33: anymore in a state where it can block. <I>Only</I> in case the application
! 34: wishes to use <I>non-blocking</I> sockets it should register methods for
! 35: handling the <B>registration</B> process as described below.
! 36: <P>
! 37: <B>Note</B>: The library <B>core</B> does <I>not</I> define any event manager
! 38: - it is considered part of the application. The library comes with a
! 39: <A HREF="HTEvntrg.html">default event manager</A> which can be initiated
! 40: using the function <CODE>HTEventInit()</CODE> in <A HREF="HTInit.html">HTInit
! 41: module</A>
! 42: <P>
! 43: This module is implemented by <A HREF="HTEvent.c">HTEvent.c</A>, and it is
! 44: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
! 45: Library</A>.
! 46: <PRE>
2.1 eric 47: #ifndef HTEVENT_H
48: #define HTEVENT_H
2.2 frystyk 49: #include "sysdep.h"
50:
2.4 ! frystyk 51: #define FD_NONE 0
! 52: #define FD_ALL (FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT |FD_CLOSE)
! 53: #define FD_UNREGISTER (((FD_ALL) << 1) & (~(FD_ALL)))
! 54:
2.2 frystyk 55: typedef enum _HTPriority {
56: HT_PRIORITY_INV = -1,
57: HT_PRIORITY_OFF = 0,
58: HT_PRIORITY_MIN = 1,
59: HT_PRIORITY_MAX = 20
60: } HTPriority;
61:
62: typedef u_long SockOps;
2.1 eric 63:
64: #include "HTReq.h"
65: </PRE>
2.3 frystyk 66: <H2>
67: Event Handlers
68: </H2>
69: <P>
2.4 ! frystyk 70: A <I>location</I> is a function that can be registered by the event manager
! 71: and called at a later point in time in order to continue an operation. All
! 72: locations must be of type <CODE>HTEventCallback</CODE> as defined here:
2.2 frystyk 73: <PRE>
74: typedef int HTEventCallback (SOCKET, HTRequest *, SockOps);
75: </PRE>
2.4 ! frystyk 76: <P>
! 77: There are many default event handlers provided with the Library. For example,
! 78: all the protocol modules such as the <A HREF="HTTP.html">HTTP client module</A>
! 79: are implemented as event handlers. In stead of using blocking sockets, this
! 80: allows a protocol module to register itself when performing an operation
! 81: that would block. When the sockets becomes ready the handler is called with
! 82: th socket in question, the request object, and the socket operation
2.3 frystyk 83: <H2>
2.4 ! frystyk 84: Registering and Unregistering Event Handlers
2.3 frystyk 85: </H2>
86: <P>
2.4 ! frystyk 87: As mentioned above, the only interface libwww requires from an event manager
! 88: is a method to <I>register</I> an event handler when an operation would block
! 89: and <I>unregister</I> it when the operation has completed The library registers
! 90: and unregisters event handlers by calling the following two functions:
! 91: <PRE>extern int HTEvent_register (SOCKET, HTRequest *,
! 92: SockOps, HTEventCallback *,
! 93: HTPriority);
! 94: extern int HTEvent_unregister (SOCKET, SockOps);
! 95: </PRE>
! 96: <P>
! 97: The register function contains information about which socket we are waiting
! 98: on to get ready and which operation we are waiting for (read, write, etc.),
! 99: the request object containing the current request, the event handler that
! 100: we want to be called when the socket becomes reasy, and finally the priority
! 101: by which we want the thread to be processed by the event manager. Likewise,
! 102: libwww can unregister a operation on a socket which means that libwww is
! 103: no longer waiting for this actiion to become ready.
! 104: <H2>
! 105: Registering an Event Manager
! 106: </H2>
! 107: <P>
! 108: The Library core does not contain any event manager as it depends on whether
! 109: you want to use pseudo threads no threads, or real threads. Instead, libwww
! 110: comes with a <A HREF="HTEvntrg.html">default implementation</A> that you
! 111: may register, but you may as well implement and register your own. The register
! 112: and unregister functions above actually does nothing than looking for a
! 113: registered event manager and then passes the call on to that. You register
! 114: your own event manager by using the methods below:
2.1 eric 115: <PRE>
116: typedef int HTEvent_registerCallback(SOCKET, HTRequest *,
117: SockOps, HTEventCallback *,
118: HTPriority);
119: typedef int HTEvent_unregisterCallback(SOCKET, SockOps);
120:
121: extern void HTEvent_setRegisterCallback(HTEvent_registerCallback *);
122: extern void HTEvent_setUnregisterCallback(HTEvent_unregisterCallback *);
123: </PRE>
2.3 frystyk 124: <P>
2.4 ! frystyk 125: You can register the event manager provided together with libwww by using
! 126: the <CODE>HTEventInit()</CODE> in the <A HREF="HTInit.html">HTInit module</A>
2.1 eric 127: <PRE>
128: #endif /* HTEVENT_H */
129: </PRE>
2.3 frystyk 130: <P>
131: <HR>
2.1 eric 132: <ADDRESS>
2.4 ! frystyk 133: @(#) $Id: HTEvent.html,v 2.3 1996/05/17 17:47:39 frystyk Exp $
2.1 eric 134: </ADDRESS>
2.3 frystyk 135: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTEvent.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src