1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>Events</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">Events: Overview <IMG src="../../image/NTR.gif" align=middle><IMG src="../../image/TWL.gif" align=middle></H1> 12<P>The first method for synchronizing threads is to control them using events.</P> 13<P>Events consist of information provided to an event structure. By calling functions available in the SDK, an event can be generated to signal moribund threads that are waiting for an event. If a waiting thread fulfills the specified conditions, its state can be changed from <I>waiting</I> to <I>runnable</I>.</P> 14<BLOCKQUOTE><IMG src="event_image1.gif" width="501" height="466" border="0"></BLOCKQUOTE> 15<H2>Event Structure</H2> 16<P>The event structure's data is of type <CODE>OSEvent</CODE>, and has the following members:<BR> 17</P> 18<TABLE border="1"> 19 <TBODY> 20 <TR> 21 <TH>Member Name</TH> 22 <TH>Type</TH> 23 <TH>Usage</TH> 24 </TR> 25 <TR> 26 <TD><CODE>flag</CODE></TD> 27 <TD><CODE>u32</CODE></TD> 28 <TD>Event flag. Stores the flag of the given event.</TD> 29 </TR> 30 <TR> 31 <TD><CODE>queue</CODE></TD> 32 <TD><CODE>OSThreadQueue</CODE></TD> 33 <TD>Thread queue. Used to pause (put in the <EM>waiting</EM> state) or start threads.</TD> 34 </TR> 35 </TBODY> 36</TABLE> 37<H2>Initializing the Event Structure</H2> 38<P>Before making a thread wait for an event, the structure must be initialized.<BR>The initialization function is <A href="OS_InitEvent.html"><CODE>OS_InitEvent</CODE></A>.<BR> 39</P> 40<BLOCKQUOTE> 41<table style="width:80%"> 42<tr> 43<td style="background-color:lightyellow"><CODE>OS_InitEvent( &event );</CODE> 44</td> 45</tr> 46</table> 47</BLOCKQUOTE> 48<H2>Waiting for Events</H2> 49<P>To wait for an event, you must take an event structure that has been initialized with the <A href="OS_InitEvent.html"><CODE>OS_InitEvent</CODE></A> function and pass it to the <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent</CODE></A> function.</P> 50<P>To specify the completion conditions when waiting for an event, use the arguments of the <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent</CODE></A> function. These are specified as a bit pattern (<CODE>pattern</CODE>) and a mode (<CODE>mode</CODE>). Depending on the mode, waiting will complete when either (1) all bits in the event flag's bit pattern become 1, or (2) any of the bits in the event flag's bit pattern become 1.<BR> 51</P> 52<TABLE border="1"> 53 <TBODY> 54 <TR> 55 <TH>Value of mode</TH> 56 <TH>Completion Conditions</TH> 57 </TR> 58 <TR> 59 <TD><CODE>OS_EVENT_MODE_AND</CODE></TD> 60 <TD>Stop waiting when all bits become 1</TD> 61 </TR> 62 <TR> 63 <TD><CODE>OS_EVENT_MODE_OR</CODE></TD> 64 <TD>Stop waiting when any bits become 1</TD> 65 </TR> 66 </TBODY> 67</TABLE> 68<P><BR> Until the specified condition is fulfilled, threads for which this function has been called will be in the <EM>waiting</EM> state. Strictly speaking, there will be a short time required to find out whether the condition has been fulfilled, but the thread will enter the waiting state immediately if the condition has not been fulfilled. In other words, <FONT color="#ff0000">calling this function may cause execution to switch to a separate thread.</FONT></P> 69<P>Use the <A href="OS_WaitEvent.html"><CODE>OS_WaitEventEx</CODE></A> function if you want to clear the event flag once the condition is fulfilled.</P> 70<P>The return value will be the value of the event flag when the condition is fulfilled. If you have specified that the event flag should be cleared with the <A href="OS_WaitEvent.html"><CODE>OS_WaitEventEx</CODE></A> function, the flag value before the clear operation will be returned.<BR> 71</P> 72<BLOCKQUOTE> 73<table style="width:80%"> 74 75 <tr> 76<td style="background-color:lightyellow"><CODE>OS_WaitEvent( &event, pattern, mode );</CODE><BR> <CODE>OS_WaitEventEx( &event, pattern, mode, clearBit );<BR></CODE></td> 77 </tr> 78 79</table> 80</BLOCKQUOTE> 81<P><BR> If the completion conditions have already been fulfilled, control will return immediately without a thread function being called.<BR> 82</P> 83<H2>Setting Event Flags</H2> 84<P>Call the <A href="OS_SignalEvent.html"><CODE>OS_SignalEvent</CODE></A> function to set an event flag and signal a <I>waiting</I> thread.<BR> 85</P> 86<BLOCKQUOTE> 87<table style="width:80%"> 88 89 90 <tr> 91<td style="background-color:lightyellow"><CODE>OS_SignalEvent( &event, setBit );</CODE></td> 92 </tr> 93 94 95</table> 96</BLOCKQUOTE> 97<P><BR> Internally, after setting the event, this function will use the thread queue within the event structure to reschedule.<FONT color="#ff0000">Calling this function may cause execution to switch to a separate thread.</FONT></P> 98<H2>Clearing Event Flags</H2> 99<P>Call the <A href="OS_ClearEvent.html"><CODE>OS_ClearEvent</CODE></A> function to clear a particular bit in the event structure's event flag. To clear all bits, call the <A href="OS_ClearEvent.html"><CODE>OS_ClearAllEvent</CODE></A> function.<BR> 100</P> 101<BLOCKQUOTE> 102<table style="width:80%"> 103 104 105 106 <tr> 107<td style="background-color:lightyellow"><CODE>OS_ClearEvent( &event, clearBit );</CODE><BR> <CODE>OS_ClearAllEvent( &event )</CODE></td> 108 </tr> 109 110 111 112</table> 113</BLOCKQUOTE> 114<P><BR> Control will not switch to another thread as a result of this function.</P> 115<H2>Polling Event Flags</H2> 116<P>The standard procedure for waiting for events is to use the <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent</CODE></A> thread function, but it is also possible to poll the <A href="OS_PollEvent.html"><CODE>OS_PollEvent</CODE></A> function to determine whether the conditions are fulfilled on your own.<BR> 117</P> 118<BLOCKQUOTE> 119<table style="width:80%"> 120 121 122 123 124 <tr> 125<td style="background-color:lightyellow"><CODE>OS_PollEvent( &event, pattern, mode );</CODE><BR> <CODE>OS_PollEventEx( &event, pattern, mode, clearBit );</CODE></td> 126 </tr> 127 128 129 130 131</table> 132</BLOCKQUOTE> 133<P><BR> Here, the completion conditions for waiting are the same as those for the <CODE><A href="OS_WaitEvent.html">OS_WaitEvent*</A></CODE> functions.</P> 134<P>If the return value is nonzero, the conditions will be deemed to have been fulfilled, and that return value will be the value of the event flag. If the return value is 0, the conditions are not fulfilled.</P> 135<P>Like the <A href="OS_WaitEvent.html">OS_WaitEventEx</A> function, the <A href="OS_PollEvent.html"><CODE>OS_PollEventEx</CODE></A> function allows you to clear specified bits using a clear flag when the conditions have been fulfilled.</P> 136<H2>Example 1</H2> 137<P>Here, let's consider the case where we have three threads: a thread waiting for events, thread 1, and thread 2. In this example, the thread waiting for events is waiting for <CODE>MY_EVENT1</CODE> (thread 1) and <CODE>MY_EVENT2</CODE> (thread 2) to be signaled. It will continue waiting until both are signaled.<BR> 138</P> 139<BLOCKQUOTE > 140<table style="width:80%"><tr><td style="background-color:lightyellow"><CODE>OSEvent event;<BR> <BR> #define MY_EVENT1 0x00000001<BR> #define MY_EVENT2 0x00000002<BR> #define MY_EVENT (MY_EVENT1 | MY_EVENT2)<BR> <BR> //-------- thread waiting on events<BR> func()<BR> {<BR> OS_InitEvent( &event );<BR> :<BR>(void)OS_WaitEvent( &event, MY_EVENT, <FONT color="#ff0000">OS_EVENT_MODE_AND</FONT> );<BR> OS_Printf( "signaled EVENT1 and EVENT2\n" );<BR> :<BR>}<BR> <BR> //-------- thread 1<BR> thread1()<BR> {<BR> :<BR>OS_SignalEvent( &event, MY_EVENT1 );<BR> :<BR>}<BR> <BR> //-------- thread 2<BR> thread2()<BR> {<BR> :<BR>OS_SignalEvent( &event, MY_EVENT2 );<BR> :<BR> }</CODE></td></tr></table> 141</BLOCKQUOTE> 142<P><BR> 143</P> 144<P>In the example above, the waiting thread waited until both <CODE>MY_EVENT1</CODE> and <CODE>MY_EVENT2</CODE> were signaled. Only one change, shown below, is necessary to change this so that it will wait only until either one is signaled.<BR> 145</P> 146<BLOCKQUOTE > 147<table style="width:80%"><tr><td style="background-color:lightyellow"><CODE>// </CODE>Part of <CODE>func()</CODE> in the example above has been changed.<BR> <BR> <CODE> (void)OS_WaitEvent( &event, MY_EVENT, <FONT color="#ff0000">OS_EVENT_MODE_OR</FONT> );<BR> OS_Printf( "signaled EVENT1 or EVENT2\n" );<BR> <BR></CODE></td></tr></table> 148</BLOCKQUOTE> 149<H2>Example 2</H2> 150<P>In this example we have two threads: a thread waiting for events, and thread 1, which signals <CODE>MY_EVENT1</CODE> periodically. The thread waiting for events will start up each time <CODE>MY_EVENT1</CODE> is signaled. Once its processing completes, it will go back to waiting for events and enter the <EM>moribund</EM> state.<BR> <BR> 151<BLOCKQUOTE> 152<table style="width:80%"><tr><td style="background-color:lightyellow"><CODE>OSEvent event;<BR> <BR> #define MY_EVENT1 0x00000001<BR> <BR> //-------- this thread waits for an event<BR> func()<BR> {<BR> OS_InitEvent( &event );<BR> :<BR>while(1)<BR> {<BR> <FONT color="#ff0000">(void)OS_WaitEventEx( &event, MY_EVENT1,<BR> OS_EVENT_MODE_AND,<BR> MY_EVENT1);</FONT><BR> OS_Printf( "signaled EVENT1\n" );<BR> }<BR> :<BR>}<BR> <BR> //-------- Thread 1<BR> thread1()<BR> {<BR> :<BR>OS_SignalEvent( &event, MY_EVENT1 );<BR> :<BR>OS_SignalEvent( &event, MY_EVENT1 );<BR> :<BR> }<BR></CODE></td></tr></table> 153</BLOCKQUOTE> 154<BR> 155<P>In this example, we use the <A href="OS_WaitEvent.html"><CODE>OS_WaitEventEx</CODE></A> function to clear <CODE>MY_EVENT1</CODE> when the event completes. This is done in order to accept events again.</P> 156<P>If this code is changed so that the waiting thread waits for events with the <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent</CODE></A> function and clears <CODE>flag</CODE> by itself after completion, and an interrupt occurs after the <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent</CODE></A> function completes but before <CODE>flag</CODE> is cleared, it will not be possible to catch the next single time <CODE>MY_EVENT1</CODE> is signaled. (This is not a problem if interrupts are prohibited for the duration of this sequence, but that would be no different from using the <A href="OS_WaitEvent.html"><CODE>OS_WaitEventEx</CODE></A> function.)<BR> 157</P> 158<BLOCKQUOTE> 159<table style="width:80%"><tr><td style="background-color:lightyellow"><CODE>// By changing func() as shown below, some events may be dropped.</CODE><BR><BR> <CODE>func()<BR> {<BR> OS_InitEvent( &event );<BR> :<BR>while(1)<BR> {<BR> <FONT color="#ff0000">(void)OS_WaitEvent( &event, MY_EVENT1,<BR> OS_EVENT_MODE_AND );</FONT><BR> // When the event occurs here<BR> // Immediately cleared on the line below<BR><FONT color="#ff0000">event->flag = 0;</FONT> <BR> OS_Printf( "signaled EVENT1\n" );<BR> }<BR> :<BR> }<BR></CODE> 160</td></tr></table> 161</BLOCKQUOTE> 162<P><BR> 163</P> 164<H2>See Also</H2> 165<P><A href="OS_InitEvent.html"><CODE>OS_InitEvent</CODE></A><BR> <A href="OS_WaitEvent.html"><CODE>OS_WaitEvent*</CODE></A><BR> <A href="OS_SignalEvent.html"><CODE>OS_SignalEvent</CODE></A><BR> <A href="OS_ClearEvent.html"><CODE>OS_Clear*Event</CODE></A><BR> <A href="OS_PollEvent.html"><CODE>OS_PollEvent*</CODE></A></P> 166<H2>Revision History</H2> 167<P>2007/12/04 Initial version.</P> 168<hr><p>CONFIDENTIAL</p></body> 169</HTML>
