obj.CreateEvent( [Name ] [, Flag ] [, StartFlag ] [, Timeout ] )

Part	Description
obj	An FUNCky object created from a previous call to CreateObject.
Name	The public name of the event. Optional, the default is "".
Flag	The initial state of the event object. Optional. The default is FALSE (calls to Wait will block).
StartFlag	A flag designating if the application wants OnEvent notifications immediately. Optional. The default is FALSE (no).
Timeout	The value in milliseconds that must elapse before an OnTimeout event is generated. Optional, the default value is -1.

An event object that can be used to synchronize multiple processes.

CreateEvent creates and initializes a new Event object using the supplied parameters. Events provide a mechanism whereby multiple threads or processes can be granted access to a global resource or section of code at the same time.

Events are useful to control access to global resources such as directories, files and FUNCkyView objects. Events differ from Semaphores and Mutexes in that any number of threads and processes can be granted access to the global resource at the same time. Semaphores and Mutexes limit the number of users while Events do not.

An Event has two states, signaled, and non-signaled.

When the event is in the signaled state, a call to Wait will return immediately with a result code of 0 which grants permission to that process to proceed.

When the event is in the non-signaled state, a call to Wait will block until the event becomes signaled or the timeout period elapses.

An Event can be named, or unnamed. A named Event can be shared by multiple processes while an unnamed Event can only be shared within a single process, making it useful only to multiple threads within the same process..

The name of the Event is specified via the parameter Name. Name is any text string up to 255 characters in length. Normally, this name cannot contain the backslash character but FUNCky will translate them into an underscore. This allows the direct use of filenames and directory names as Event names.

Event names are case sensitive.

An Event Name is global to the system. Any name already in use by Semaphores, Views or Mutexes will fail since they all share the same global namespace.

To specify a named Event, pass a unique name via the parameter Name. To create an unnamed Event, pass "" via the parameter Name.

The initial state of the Event can be specified via the parameter Flag.

If the calling thread wants to allow other threads waiting for this event to have immediate access to the resource this event is protecting, True should specified to initialize this event in the signaled state.

If the calling thread wants all other other threads to have to wait for this event, False should be specified to initialize this event in the non-signaled state.

When Flag is True, the next Wait method call on this event by any process will return immediately with a value of 0 - this grants permission to the other thread or process to proceed.

When Flag is False, the next Wait method call on this event by any other process will block until another thread or process uses Signal or Pulse to change the signaled status of the event.

If an Event by the same name has already been created, Flag is ignored.

If omitted, the default value for the initial state is False (non-signaled).

The event can also generate OnEvent and OnTimeout notifications in VB if the Event object is created using the WithEvents keyword in a VB Class or Form.

To generate the OnEvent and OnTimeout notifications, a background monitoring thread is started and it automatically executes the Wait method call on this event using the timeout value specified in Timeout.

To designate that OnEvent events are desired, specify StartFlag as True. If OnEvent notifications are not desired, specify StartFlag as False.

When OnEvent notifications are desired, the monitoring thread can be instructed to timeout after a period of time. This value is expressed in milliseconds via the parameter Timeout.

If Timeout is specified as -1 (the default), the monitoring thread waits indefinately on the event and no OnTimeout events will ever occur.

The format of the OnEvent and OnTimeout event handlers are as follows:

    Private Sub MyEvent_OnEvent()      

        // Your code here      

    End Sub      

and

    Private Sub MyEvent_OnTimeout()      

        // Your code here      

    End Sub      

When the OnEvent handler is being used, calls to Wait are not necessary since execution will jump to the OnEvent handler when the designated event becomes signaled by another process or the current process.

If the event is successfully initialized with the supplied values, True is returned, otherwise False is returned and the Error and ErrorMessage properties can be queried for information regarding why the call failed.

Events are useful to signal other processes that something is available. For example, multiple processes can be waiting for a file to appear in a certain directory, or, they can be waiting for data in a FUNCkyView object to be updated. Once the signal is generated that the resource is available, all waiting processes will begin accessing the resource to do something.

The FUNCkyView object is an object that makes it's data visible to other processes and threads on the system using shared memory. The shared data also retains it's datatype across the processes so a date value will be visible as a date value to all other processes accessing the same View.

A problem exists if multiple Views are being used to share multiple pieces of information. Read/Write access to a single View is automatically synchronized by FUNCky. Multiple read/write access to multiple Views are not, which can cause a process to receive incorrect values from the different Views.

Lets say we have three Views. One for Name, one for Birthday and one for Age. Since there are three values that need to be read and written, it is entirely possible that one process can be in the middle of updating the Views while another process is reading from three Views. If process A writes to the Name View, the three values are not matched since Birthday and Age now contain values that are not related to the value in Name.

So, if process B comes in right at this point and reads all three values before process A has a chance to update the Age and Birthday Views, Process B is going to get incorrect data since Age and Birthday are from the old data while Name is from the new data.

Multiple processes can use an Event to signal each other when they are done reading or writing the data. In addition, the OnEvent handler can be used to automatically wait for changes like this to be completed before the data is accessed.

Finally, multiple events can be used to coordinate multiple processes by using the WaitFor method of the Event object. This is very useful when an application has to wait for two or three situations to be completed before continuing. See the documentation on the WaitFor method for more information.

Tip	For better coordination, use an Ack/Nak system of events. One process updates some resource and then signals that is has done so on the Ack event. It then immediately waits on the Nak event. The second process wakes up to the Ack event, does its thing and then signals back to the original process that it is going to be waiting again on the Ack event by signaling the Nak event. The first process then can safely wake up and go back to updating the resource again.

 Example

// This example waits on a single event to be signaled. // Please review the documentation on WaitFor for an example of // waiting for Multiple Events (or Mutexes) and also for the // OnEvent handler for using a background monitoring thread. // First, get inital objects we need Set FUNCky = CreateObject("FUNCky") Set FConst = CreateObject("FUNCkyConst") // Create our "MyEvent" object. Since Param 2 is False // we don't automatically signal the event so our call to // Wait will block unless someone has called Signal() with // TRUE as the parameter. If Param 2 was TRUE, the event would // be signaled and any Waits would immediately return 0. Set oEvent = FUNCky.CreateEvent("MyEvent", False, False, 20000) // If there were no errors we can proceed While (oEvent.Status = 0) // Now wait for a signal or 20 seconds... // ALL threads waiting on this event will // resume execution when the event becomes signaled // or the timeout period elapses Reason = oEvent.Wait(20000) // Check the reason we were allowed to proceed If (Reason = FConst.WAIT_OBJECT_0) Then // We got permission to do our thang... ElseIf (Reason = FConst.WAIT_OBJECT_TIMEOUT) Then // We didn't get permission in the last 20 seconds Else // Dunno, something bad happened - we should quit // or wait some more End If Wend