|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-301037F1-1983-565A-88F9-633BBF0EBB91" xml:lang="en"><title>posixsignals: |
|
13 POSIX Signal Example, Using P.I.P.S.</title><shortdesc>This example demonstrates various signal use cases as supported |
|
14 in P.I.P.S. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
15 <section id="GUID-CB373350-FF46-4535-BF8E-69F1CB3BA96E"><title>Purpose</title> <p>The |
|
16 example demonstrates the following use cases: </p> <ol> |
|
17 <li id="GUID-2449E06E-4B58-567F-977E-B949483EB5C2"><p>Sending and handling |
|
18 a signal using the default handler </p> </li> |
|
19 <li id="GUID-7E468336-5849-5900-BE63-5AAE64061463"><p>Sending and handling |
|
20 a signal using a customized signal handler </p> </li> |
|
21 <li id="GUID-0BE58B0C-9D2A-5CAE-BF98-CF5169532B41"><p>Ignoring an incoming |
|
22 signal </p> </li> |
|
23 <li id="GUID-585B9B29-DFA4-5530-8E4F-F2DC865C9D2C"><p>Blocking and releasing |
|
24 a signal </p> </li> |
|
25 <li id="GUID-A486A7E3-31AB-5AAF-B24F-F908CE687121"><p>Waiting for a signal </p> </li> |
|
26 <li id="GUID-E4F52B24-EDA0-57A7-AA1C-7B93EF91F3C1"><p>Generating and handling |
|
27 a <codeph>SIGPIPE</codeph> signal </p> </li> |
|
28 <li id="GUID-3D92B198-4827-5817-B28C-C1AC0B28CD6F"><p>Using a signal to gracefully |
|
29 terminate a process </p> </li> |
|
30 <li id="GUID-D7F62326-7148-528E-9189-D9180123724E"><p>Using a signal to handle |
|
31 an asynchronous event </p> </li> |
|
32 </ol><p> </p><p>The example delivers 3 sub projects: </p> <ul> |
|
33 <li id="GUID-F8B3EA5D-58D5-535D-BF5A-5E4639EE78FB"><p> <b>basicSignals:</b> This |
|
34 project demonstrates basic signal use cases. It shows the first six use cases |
|
35 mentioned in the list above. The use cases are demonstrated through <filepath>basicsignals.exe</filepath>. </p> </li> |
|
36 <li id="GUID-145641DC-753A-53C4-8AFA-4F38D754A293"><p> <b>sigtermSignal:</b> This |
|
37 project demonstrates the graceful termination of a process using the <codeph>SIGTERM</codeph> signal. |
|
38 The use case is demonstrated through <filepath>sigtermsignal.exe</filepath> and <filepath>raisesignal.exe</filepath>. </p> </li> |
|
39 <li id="GUID-899D801E-B669-560F-87AE-3C3AE095FB07"><p> <b>asyncSignal:</b> This |
|
40 project demonstrates asynchronous signal handling using the <codeph>SIGUSR1</codeph> signal |
|
41 and the <codeph>SIGUSR2</codeph> signal. The use case is demonstrated using <filepath>sigusr1.exe</filepath> and <filepath>sigusr2.exe</filepath>. </p> </li> |
|
42 </ul> </section> |
|
43 <section id="GUID-703F9106-A12C-4F0B-872B-F4A06FCEC1FC"><title>Description</title> <p>The |
|
44 use cases demonstrated in this example are described below.</p><p>Note: For |
|
45 clarity in the documentation for this example, signal names have been given |
|
46 in capitals whilst process names have been given in lower case.</p><p><b>1. |
|
47 Sending and handling a signal using the default handler </b> </p> <p>The default |
|
48 implementation of the signals supported in P.I.P.S. will either terminate |
|
49 a process or ignore a process. Signals are generated using the <codeph>Kill()</codeph> method |
|
50 and they are handled as per the implementation in the default handler. </p> <p>To |
|
51 demonstrate this use case we use <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals. <codeph>SIGCHLD</codeph> by |
|
52 default gets ignored whenever it is raised, whereas <codeph>SIGALRM</codeph> causes |
|
53 a process termination when raised. As a result the example terminates whenever <codeph>SIGALRM</codeph> is |
|
54 raised, whereas an info message is printed when <codeph>SIGCHLD</codeph> is |
|
55 raised. </p> <p><b>2. Sending and handling a signal using a customized signal |
|
56 handler </b> </p> <p>To override the default implementation of a signal a |
|
57 customized handler can be defined. This customized handler can be set either |
|
58 by using <codeph>sigaction()</codeph> or <codeph>signal()</codeph>. The <codeph>sigaction()</codeph> method |
|
59 takes <codeph>struct sigaction</codeph> as one of its parameters (the <codeph>sa_handler</codeph> member |
|
60 of this structure is filled with the custom handler). Now whenever a signal |
|
61 is generated the custom handler is executed. </p> <p>For the demonstration |
|
62 of this particular use case, <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals |
|
63 are used. These signals are assigned custom handler functions. The handlers |
|
64 for these signals contains a simple user message. Thus, whenever the signals |
|
65 are raised, the customized signal handlers get invoked instead of the default |
|
66 handlers. </p> <p><b>3. Ignoring an incoming signal </b> </p> <p>A signal |
|
67 can be ignored by setting <codeph>SIG_IGN</codeph> in the <codeph>sa_handler</codeph> member |
|
68 of <codeph>struct sigaction</codeph>. The demonstration of this use case also |
|
69 uses <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals, and as |
|
70 a result of setting <codeph>SIG_IGN</codeph> in <codeph>sa_handler</codeph> the |
|
71 signals are ignored when raised. </p> <p><b>4. Blocking and releasing a signal </b> </p> <p>A |
|
72 signal can be blocked by first adding it to the blocking set (a list of signals |
|
73 we want to block, when a signal is executing) by using the <codeph>sigaddset()</codeph> method |
|
74 and then calling the<codeph> sigprocmask()</codeph> function. Once a signal |
|
75 is blocked it will always be ignored upon generation. The <codeph>sigrelse()</codeph> method |
|
76 is used to unblock a signal. </p> <p>Demonstration of this use case involves |
|
77 the <codeph>SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals. Both <codeph>SIGUSR1 </codeph>and <codeph>SIGUSR2</codeph> are |
|
78 user-defined signals. We first block the <codeph>SIGUSR1</codeph> signal by |
|
79 adding it to the blocking set and making a call to the <codeph>sigprocmask()</codeph> function. |
|
80 Now whenever <codeph>SIGUSR1</codeph> is raised it will get ignored as it |
|
81 is blocked. <codeph>SIGUSR1</codeph> will keep waiting in the pending queue |
|
82 until it is released. The release of <codeph>SIGUSR1</codeph> happens in the <codeph>SIGUSR2</codeph> signal |
|
83 handler. Once <codeph>SIGUSR1</codeph> is released, it is removed from the |
|
84 pending queue and its handler function is called to handle it. </p> <p><b>5. |
|
85 Waiting for a signal </b> </p> <p>Before a process can wait on a particular |
|
86 signal, it has to add the signal to the mask set (which is a list of signals |
|
87 we want to block) and then call the <codeph>sigprocmask()</codeph> method. |
|
88 The process then sets the timeout value using <codeph>struct timespec</codeph>. |
|
89 Once this is done the process waits on a signal for a specified time period |
|
90 using the<codeph>sigtimedwait()</codeph> method. If the signal is not received |
|
91 within the specified time period, an error message is generated. </p> <p>For |
|
92 the demonstration of this use case we are setting a timeout of 5 seconds. |
|
93 The <codeph>SIGALRM</codeph> signal is raised by a call to <codeph>alarm()</codeph> as |
|
94 and when the timer expires. There are two instances in the example where <codeph>SIGALRM</codeph> signal |
|
95 is raised, one after a duration of 4 seconds and one after 6 seconds. When <codeph>SIGALRM</codeph> is |
|
96 raised after 4 seconds, it is well within the timeout limit (of 5 seconds) |
|
97 and hence the signal gets received but not handled. But when the alarm is |
|
98 raised after 6 seconds, timeout happens and an error is generated. Now as |
|
99 the <codeph>SIGALRM</codeph> signal was added to the mask set it never gets |
|
100 handled even though it is received. To handle the signal we need to move it |
|
101 from block state to unblock state, which we do using the <codeph>sigprocmask()</codeph> method. |
|
102 Once the signal gets unblocked its custom handler gets called. </p> <p><b>6. |
|
103 Generating and handling a <codeph>SIGPIPE</codeph> signal </b> </p> <p>The |
|
104 <codeph>SIGPIPE</codeph> signal is generated when writing to a broken pipe. |
|
105 To achieve this broken pipe condition the read end of the pipe (obtained using |
|
106 the <codeph>pipe() </codeph> function call) is closed and then write to the |
|
107 pipe is done. The associated handler function is executed in response to the |
|
108 raised <codeph>SIGPIPE</codeph> signal . </p> <p><b>7. Using a signal to gracefully |
|
109 terminate a process </b> </p> <p>Graceful termination of process can be achieved |
|
110 by using the <codeph>SIGTERM </codeph>signal. In the handler function of the |
|
111 signal all the opened file descriptors need to be closed before exiting. </p> <p>This |
|
112 use case is demonstrated using the <filepath>sigtermSignal</filepath> project. |
|
113 The project consists of two processes: the <filepath>sigtermsignal</filepath> process |
|
114 and the <filepath>raisesignal </filepath> process. </p> <ul> |
|
115 <li id="GUID-A2CC3DF9-0334-5638-A5E7-7828F319F5D0"> <p>The <filepath>sigtermsignal</filepath> process |
|
116 first defines a custom handler for the <codeph>SIGTERM</codeph> signal that |
|
117 carries out the closing of all the open file descriptors when the signal is |
|
118 raised. This is done in order to achieve the graceful termination of the process. |
|
119 The <filepath>sigtermsignal</filepath> process then opens a file and obtains |
|
120 names from user to be written in to it. It then simultaneously spawns a <filepath>raisesignal</filepath> process |
|
121 and starts reading from the file. When the <filepath>raisesignal</filepath> process |
|
122 sends a <codeph>SIGTERM</codeph> signal to the <filepath>sigtermsignal</filepath> process, |
|
123 the <filepath>sigtermsignal</filepath> process closes all the open file descriptors |
|
124 and prepares to exit. </p> </li> |
|
125 <li id="GUID-05715C75-A100-563B-82D5-CAA4EFD44634"> <p>The <filepath>raisesignal</filepath> process |
|
126 sends the <codeph>SIGTERM</codeph> signal to the <filepath>sigtermsignal</filepath> process. |
|
127 The custom handler of the <codeph>SIGTERM</codeph> signal takes care of properly |
|
128 closing all opened file descriptors and then terminating the process. If the |
|
129 custom handler is not implemented, the default handler will get called, which |
|
130 will result in process termination without closing any opened file descriptors. </p> </li> |
|
131 </ul> <p><b>8. Using a signal to handle an asynchronous event </b> </p> <p> <codeph>The |
|
132 SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals are used to demonstrate |
|
133 the handling of an asynchronous event. These signals are sent from one process |
|
134 to another. On reception of these signals, respective custom handlers are |
|
135 called and any necessary action is taken. The action taken is purely implementation |
|
136 dependent . </p> <p>This use case demonstration is performed using the <filepath>asyncSignal</filepath> project. |
|
137 The project consists of two processes: the <filepath>sigusr1</filepath> process |
|
138 and the <filepath>sigusr2</filepath> process, where the <filepath>sigusr1</filepath> process |
|
139 handles the <codeph>SIGUSR1</codeph> signal and sends the <codeph>SIGUSR2</codeph> signal |
|
140 to the <filepath>sigusr2</filepath> process. Whereas the<filepath> sigusr2</filepath> process |
|
141 handles the <codeph>SIGUSR2</codeph> signal and sends the <codeph>SIGUSR1</codeph> signal |
|
142 to the <filepath>sigusr1</filepath> process. </p> <ul> |
|
143 <li id="GUID-57116DD9-EB8E-57F0-9FFD-AA54F984F698"><p>The <filepath>sigusr1 </filepath> process |
|
144 assigns a custom handler for the <codeph>SIGUSR1</codeph> signal. It then |
|
145 opens a file in read and write mode and write some content into the open file. |
|
146 Once write operation is done the <filepath>sigusr1</filepath> process spawns <filepath>sigusr2</filepath> process |
|
147 and waits for <codeph>SIGUSR1 </codeph> signal from <filepath>sigusr2</filepath> process. |
|
148 On receiving <codeph>SIGUSR1</codeph> signal <filepath>sigusr1 </filepath> process |
|
149 starts reading from the file. Once reading from the file is done and its contents |
|
150 are displayed on the console, <filepath>sigusr1</filepath> process sends <codeph>SIGUSR2</codeph> signal |
|
151 to <filepath>sigusr2</filepath> process. It then closes all its open file |
|
152 descriptor and prepares to exit. </p> </li> |
|
153 <li id="GUID-9F878182-23B1-570C-986C-3B4E7B26F444"> <p>The<filepath> sigusr2</filepath> process |
|
154 is spawned from <filepath>sigusr1</filepath> process and it assigns a custom |
|
155 handler for <codeph>SIGUSR2</codeph> signal. It sends <codeph>SIGUSR1</codeph> signal |
|
156 to <filepath>sigusr1</filepath> process in order to start file read and then |
|
157 waits for <codeph>SIGUSR2 </codeph> signal from <filepath>sigusr1</filepath> process. |
|
158 When <filepath>sigusr2</filepath> process receives <codeph>SIGUSR2</codeph> signal |
|
159 it prepares to exit. </p> </li> |
|
160 </ul> <p>Hence, the communication between the two processes happens through |
|
161 the <codeph>SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals and asynchronous |
|
162 signal handling happens. </p> </section> |
|
163 <section id="GUID-E1661179-0268-4E49-A574-C7CC41D7A56B"><title>Download</title> <p>Click |
|
164 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-5a633d12-547a-4439-9eca-104a655109ab.zip" scope="external">BasicSignals.zip</xref></p><p>Click on the following link |
|
165 to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-54523fba-51b5-436a-9403-99874fdc94c7 .zip" scope="external">SigtermSignal.zip</xref></p><p>Click on the following link |
|
166 to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-7714a392-161f-4dc7-b8e6-311e42e1deb8 .zip" scope="external">AsyncSignal.zip</xref></p><p/><p>To view the BasicSignal |
|
167 example source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-5a633d12-547a-4439-9eca-104a655109ab.html" scope="peer">browseBasicSignals</xref></p><p>To view the SigtermSignal example |
|
168 source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-54523fba-51b5-436a-9403-99874fdc94c7.html" scope="peer">browseSigtermSignal</xref></p><p>To view the AsyncSignal example |
|
169 source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-7714a392-161f-4dc7-b8e6-311e42e1deb8.html" scope="peer">browseAsyncSignal</xref></p> </section> |
|
170 <section id="GUID-38492A50-BF1B-4A33-8125-397D646ED8A7"><title>Building and |
|
171 configuring</title> <p>You can build the example from your IDE or the command |
|
172 line: </p> <ul> |
|
173 <li id="GUID-0D86ECCB-1501-52D9-A52E-A016AB6710A2"><p> </p><p>If you use an |
|
174 IDE, import the <filepath>bld.inf</filepath> file of the example into your |
|
175 IDE, and use the build command of the IDE. </p></li> |
|
176 <li> <p>If you use the command line, open a command prompt, and set the current |
|
177 directory to the source code directory of the example. You can then build |
|
178 the example with the SBSv1 build tools using the following commands: </p><ul> |
|
179 <li><p><cmdname>bldmake bldfiles</cmdname></p></li> |
|
180 <li><p><cmdname>abld build</cmdname></p></li> |
|
181 </ul> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use |
|
182 bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How |
|
183 to use abld</xref> describe how to use the SBSv1 build tools. </p> </li> |
|
184 </ul> <p> </p><p>The example builds the following executables :<ul> |
|
185 <li><p><filepath>basicsignals.exe</filepath> : for basic signal use cases |
|
186 demonstration. </p></li> |
|
187 <li><p><filepath>sigtermsignal.exe</filepath> : for demonstrating graceful |
|
188 termination of process .</p></li> |
|
189 <li><p><filepath>raisesignal.exe</filepath> : for sending <codeph>SIGTERM</codeph> signal.</p></li> |
|
190 <li><p><filepath>sigusr1.exe</filepath> : for demonstrating asynchronous event |
|
191 handling , sending <codeph>SIGUSR2</codeph> signal and receiving <codeph>SIGUSR1</codeph> signal. </p></li> |
|
192 <li><p><filepath>sigusr2.exe</filepath> : for sending <codeph><codeph>SIGUSR1</codeph></codeph> signal |
|
193 and receiving <codeph>SIGUSR2</codeph> signal.</p></li> |
|
194 </ul></p><p> in the <filepath>epoc32\release\winscw\<udeb or urel>\</filepath> folder. </p><p> </p></section> |
|
195 <section id="GUID-1CB8164D-030D-41CD-B146-3E4D14CB1A9B"><title>Running the |
|
196 example</title> <p><b>NOTE : </b> </p> <p> <filepath>basicsignals.exe</filepath> should |
|
197 be executed first for running the first six uses cases mentioned above. </p> <p> <filepath>sigtermsignal.exe</filepath> should |
|
198 be executed for running the seventh use case. </p> <p> <filepath>sigusr1.exe</filepath> should |
|
199 be executed for running the last use case. </p> <p>The <filepath>sigtermsignal</filepath> process |
|
200 internally spawns the<filepath> raisesignal</filepath> process for taking |
|
201 an input from the user and sending the <codeph>SIGTERM</codeph> signal. You |
|
202 should not run the <filepath>raisesignal</filepath> process explicitly. You |
|
203 should only run <filepath>sigtermsignal.exe</filepath> as the <filepath>sigtermsignal</filepath> process |
|
204 takes proper care of launching the <filepath>raisesignal</filepath> process. </p> <p>The <filepath>sigusr1</filepath> process |
|
205 also internally spawns the <filepath>sigusr2</filepath> process. </p> <p>The <filepath>sigusr1</filepath> process |
|
206 sends the <codeph>SIGUSR2</codeph> signal to the <filepath>sigusr2</filepath> process |
|
207 and receives the <codeph>SIGUSR1</codeph> signal from it. </p> <p>The <filepath>sigusr2</filepath> process |
|
208 sends the <codeph>SIGUSR1</codeph> signal to the <filepath>sigusr1</filepath> process |
|
209 and receives the <codeph>SIGUSR2</codeph> signal from it. </p> <p>As the <filepath>sigusr1 </filepath>process |
|
210 spawns the <filepath>sigusr2</filepath> process, hence you should run <filepath>sigusr1.exe</filepath> only. </p> <p>In |
|
211 order to toggle between the processes use <cmdname>Alt+ctrl+shift+T</cmdname> and |
|
212 observe the behavior. </p> </section> |
|
213 </refbody></reference> |