Change have been suggested, discussed and agreed to for the PLEvent librayr component of NSPR. These changes are described in the following text version of the spec. NSPR Change Specification: Client 5.0 Requirements for PLEvent Introduction Rick Potts, a wizardly engineer in ClientLand, asked for some changes to the PLEvent library in support of the next release (5.0) Netscape Client; specifically, the requirement titled "Multiple Event Queues for Windows". An additional requirement came from the Mozilla.org chanel. Specifically the requirement titled "NGLayout Calls PL_InitializeEventsLib() Multiple Times". This requirement should be viewed as if it came from Netscape since the function requested will be part of the Netscape branded Client as well as the Mozilla client. This paper documents those changes. Requirements NGLayout Calls PL_InitializeEventsLib() Multiple Times This requirement is obsolete following the change to this specification in which the function "PL_InitializeEventsLib()" is obsoleted. The NGLayout engine for Windows is being implemented as an ActiveX control. This causes the engine to call PL_InitializeEventsLib() multiple times. The desired behavior is to have the effect of the call occur only once; subsequent calls are to behave as a No-Operation. Remove function PL_InitializeEventsLib() The function PL_InitializeEventsLib() is implemented for Windows platforms only. This design made things a bit difficult for other platforms; Mac was the least happy. Anyway, after some discussion with the Mac folks, Rick Potts and others, the client folks decided they wanna do away with PL_InitializeEventsLib() altogether rather than make it compliant across all platforms. Note that the client becomes responsible for maintaining state of which PLEventQueue is associated with which thread. Multiple Event Queues The PLEvent library has slightly different API and capabilities between Unix and Windows platforms. In the Unix implementation, the client can create multiple Event Queues by calling PL_CreateEventQueue() multiple times. In the Windows implementation, the API is different: A single event queue is created on the call to PL_InitializeEventsLib(). Here is the rub. Client5 wants multiple events queues for Windows. In addition the already identified API for event queue creation, PLEvent library exposes slightly different API for handling the event queues. Unix provides for a "PL_GetEventQueueSelectFD()". This function retreives an Unix FD that the client uses in a raw select() function call. ... Oh well; so much for NSPR's platform independence. Windows provides for a "PL_GetMainEventQueue()" and a "PR_GetEventReceiverWindow()" (yes, "PR_..."). These functions are used by the Windows applications in processing PLEvent's events in the main Windows message pump. The Client wants 2 different behaviors for a Windows event queue. The first behavior is the same as for extant single event queue. The second behavior is to not have an associated event receiver window created with the event queue. Similarly, for Unix, an event queue is desired that does not have the Unix pipe, and its associated selectable FD. This concept creates a "unified" event queue; that is: a single API that will operate on an event queue in a fully platform independent maner. External Specification NGLayout Calls PL_InitializeEventsLib() Multiple Times No public API changes are required. Remove function PL_InitializeEventsLib() This is a rather straight forward thingie. Rip it out. Other functions go with it, implicitly: PL_GetMainEventQueue(); PL_GetMainEventReceiverWindow(); Multiple Event Queues Changed API Items No existing APIs will be changed in the NSPR 3.5 release. The funciton PL_GetEventQueueSelectFD() will be conditionally compiled for Unix platforms only; it is currently compiled for both Windows and Unix platforms. The function PL_CreateEventQueue() will be obsoleted in some (TBD) future release of NSPR for both Windows and Unix platforms. Users of this function should use PL_CreateNativeEventQueue(); the behavior on Unix will be the same as the extant PL_CreateEventQueue(). On Windows, there are no known callers of PL_CreateEventQueue(); its behavior is undefined for Windows. The function PL_CreateEventQueue() will not be defined for Windows. New API Items PL_CreateNativeEventQueue() /* ----------------------------------------------------------------------- ** FUNCTION: PL_CreateNativeEventQueue() ** ** DESCRIPTION: ** PL_CreateNativeEventQueue() creates an event queue that ** uses platform specific notify mechanisms. ** ** For Unix, the platform specific notify mechanism provides ** an FD that may be extracted using the function ** PL_GetEventQueueSelectFD(). The FD returned may be used in ** a select() function call. ** ** For Windows, the platform specific notify mechanism ** provides an event receiver window that is called by ** Windows to process the event using the windows message ** pump engine. ** ** INPUTS: ** name: A name, as a diagnostic aid. ** ** handlerThread: A pointer to the PRThread structure for ** the thread that will "handle" events posted to this event ** queue. ** ** RETURNS: ** A pointer to a PLEventQueue structure or NULL. ** */ PR_EXTERN(PLEventQueue) PL_CreateNativeEventQueue( char *name, PRThread *handlerThread ); PL_CreateMonitoredEventQueue() /* ----------------------------------------------------------------------- ** FUNCTION: PL_CreateMonitoredEventQueue() ** ** DESCRIPTION: ** PL_CreateMonitoredEventQueue() creates an event queue. No ** platform specific notify mechanism is created with the ** event queue. ** ** Users of this type of event queue must explicitly poll the ** event queue to retreive and process events. ** ** ** INPUTS: ** name: A name, as a diagnostic aid. ** ** handlerThread: A pointer to the PRThread structure for ** the thread that will "handle" events posted to this event ** queue. ** ** RETURNS: ** A pointer to a PLEventQueue structure or NULL. ** */ PR_EXTERN(PLEventQueue) PL_CreateMonitoredEventQueue( char *name, PRThread *handlerThread ); PL_GetNativeEventReceiverWindow() /* ----------------------------------------------------------------------- ** FUNCTION: PL_GetNativeEventReceiverWindow() ** ** DESCRIPTION: ** PL_GetNativeEventReceiverWindow() returns the windows ** handle of the event receiver window associated with the ** referenced PLEventQueue argument. ** ** INPUTS: ** PLEventQueue pointer ** ** RETURNS: ** event receiver window handle. ** ** RESTRICTIONS: ** */ PR_EXTERN(HWND) PL_GetNativeEventReceiverWindow( PLEventQueue *eqp ); The PL_GetNativeEventReceiverWindow() function behaves like the existing PL_GetEventReceiverWindow(). It requires an argument: a pointer to the PLEventQueue structure whose event receiver window handle is desired. Internal Design NGLayout Calls PL_InitializeEventsLib() Multiple Times A test for the first call to PL_CreateEventQueue() will be made using the PR_CallOnce() mechanism. The initializer function in the PR_CallOnce() argument will create a lock that will be used for atomicly ensuring that the function of PL_InitializeEventsLib() is performed exactly once and only once. Remove function PL_InitializeEventsLib() The platform specific content for PL_InitializeEventsLib() become a "Machine Dependent (md)" sort of capability, similar to other NSPR things like this. All the "md" stuff will remain in plevent.c, unlike separate md files for other components in NSPR. The functions declarations will be removed from plevent.h. The function definitions will be removed from plevent.c Multiple Event Queues The conditional compilation of PLEventQueue structure will be extended to provide a Windows section, in addition to the Unix section extant today. The Windows section will contain a HWND pointer; this HWND * will be handle for the event receiver window for this event queue. PL_CreateEventQueue() will be defined only for Unix. PL_CreateNativeEventQueue() will create the PLEventQueue structure only. For Windows it will call a static function that creates the event receiver window. For Unix it will create the pipes. PL_CreateMonitoredEventQueue() will create the PLEventQueue structure only. The statically defined _pr_eventReceiverWindow will be removed. The statically defined _pr_main_event_queue will be removed. A pointer to the first Windows event queue created will be statically anchored. PL_InitiailizeEventsLib() will call PL_CreateNativeEventQueue() to create a Windows native event queue, then will deal with anchoring the PLEventQueue. Unit Test Plan New Function Test A new test case will be developed. The new test, valid for both Unix and Windows platforms will exercise multiple event queues by passing a "token" via the event mechanism around a ring of threads. This test will be developed according the the general style of NSPR test cases. Its purpose is to verify that the function works as specified. This is not a stress test. Regression Test The existing Windows 3.11 test case (ns/nspr20/pr/tests/w16gui/poppad.c) will be ported to Windows 32. The port will be done according to the suggestions found in the MSDN Library (Oct98) for porting Win16 applications to Win32. This test exercizes the PL_InitializeEventsLib() call and the "normal" windows events processing. This test case was used to port the PLEvent to Win16 from its original Win95 base.. The PLEvents lib is believed to run succcessfully on the client today. This test, ported to Win32 should ensure that it still works following these changes. Implementation Plan Yesterday. ... Oh! ... The Multiple Event Queues will be commited 12/17/98. Removal of PL_InitializeEventsLib() will be committed when Rick Potts tells me he's ready to use it. --- 4-Jan-1998. OK, Rick says it's ready.

Check in changes. cvs commit plevent.h plevent.c Checking in plevent.h; /cvsroot/mozilla/nsprpub/lib/ds/plevent.h,v <-- plevent.h new revision: 3.5; previous revision: 3.4 done Checking in plevent.c; /cvsroot/mozilla/nsprpub/lib/ds/plevent.c,v <-- plevent.c new revision: 3.6; previous revision: 3.5 done

Setting all current Open/Normal to M4.

per leger, assigning QA contacts to all open bugs without QA contacts according to list at http://bugzilla.mozilla.org/describecomponents.cgi?product=Browser

I'm closing this as done!

NSPR now has its own Bugzilla product. Moving this bug to the NSPR product.

this fix is not visible to qa. if you think this bug should be reopened, please do so. will mark as verified.