1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Passenger: MessageChannel.h Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="main.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
</ul>
</div>
<h1>MessageChannel.h</h1><div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="comment">/*</span>
<a name="l00002"></a>00002 <span class="comment"> * Phusion Passenger - http://www.modrails.com/</span>
<a name="l00003"></a>00003 <span class="comment"> * Copyright (c) 2010 Phusion</span>
<a name="l00004"></a>00004 <span class="comment"> *</span>
<a name="l00005"></a>00005 <span class="comment"> * "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.</span>
<a name="l00006"></a>00006 <span class="comment"> *</span>
<a name="l00007"></a>00007 <span class="comment"> * Permission is hereby granted, free of charge, to any person obtaining a copy</span>
<a name="l00008"></a>00008 <span class="comment"> * of this software and associated documentation files (the "Software"), to deal</span>
<a name="l00009"></a>00009 <span class="comment"> * in the Software without restriction, including without limitation the rights</span>
<a name="l00010"></a>00010 <span class="comment"> * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell</span>
<a name="l00011"></a>00011 <span class="comment"> * copies of the Software, and to permit persons to whom the Software is</span>
<a name="l00012"></a>00012 <span class="comment"> * furnished to do so, subject to the following conditions:</span>
<a name="l00013"></a>00013 <span class="comment"> *</span>
<a name="l00014"></a>00014 <span class="comment"> * The above copyright notice and this permission notice shall be included in</span>
<a name="l00015"></a>00015 <span class="comment"> * all copies or substantial portions of the Software.</span>
<a name="l00016"></a>00016 <span class="comment"> *</span>
<a name="l00017"></a>00017 <span class="comment"> * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR</span>
<a name="l00018"></a>00018 <span class="comment"> * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,</span>
<a name="l00019"></a>00019 <span class="comment"> * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE</span>
<a name="l00020"></a>00020 <span class="comment"> * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER</span>
<a name="l00021"></a>00021 <span class="comment"> * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,</span>
<a name="l00022"></a>00022 <span class="comment"> * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN</span>
<a name="l00023"></a>00023 <span class="comment"> * THE SOFTWARE.</span>
<a name="l00024"></a>00024 <span class="comment"> */</span>
<a name="l00025"></a>00025 <span class="preprocessor">#ifndef _PASSENGER_MESSAGE_CHANNEL_H_</span>
<a name="l00026"></a>00026 <span class="preprocessor"></span><span class="preprocessor">#define _PASSENGER_MESSAGE_CHANNEL_H_</span>
<a name="l00027"></a>00027 <span class="preprocessor"></span>
<a name="l00028"></a>00028 <span class="preprocessor">#include <oxt/system_calls.hpp></span>
<a name="l00029"></a>00029 <span class="preprocessor">#include <oxt/macros.hpp></span>
<a name="l00030"></a>00030
<a name="l00031"></a>00031 <span class="preprocessor">#include <algorithm></span>
<a name="l00032"></a>00032 <span class="preprocessor">#include <string></span>
<a name="l00033"></a>00033 <span class="preprocessor">#include <list></span>
<a name="l00034"></a>00034 <span class="preprocessor">#include <vector></span>
<a name="l00035"></a>00035
<a name="l00036"></a>00036 <span class="preprocessor">#include <sys/types.h></span>
<a name="l00037"></a>00037 <span class="preprocessor">#include <sys/socket.h></span>
<a name="l00038"></a>00038 <span class="preprocessor">#include <arpa/inet.h></span>
<a name="l00039"></a>00039 <span class="preprocessor">#include <errno.h></span>
<a name="l00040"></a>00040 <span class="preprocessor">#include <unistd.h></span>
<a name="l00041"></a>00041 <span class="preprocessor">#include <cstdarg></span>
<a name="l00042"></a>00042 <span class="preprocessor">#ifdef __OpenBSD__</span>
<a name="l00043"></a>00043 <span class="preprocessor"></span> <span class="comment">// OpenBSD needs this for 'struct iovec'. Apparently it isn't</span>
<a name="l00044"></a>00044 <span class="comment">// always included by unistd.h and sys/types.h.</span>
<a name="l00045"></a>00045 <span class="preprocessor"> #include <sys/uio.h></span>
<a name="l00046"></a>00046 <span class="preprocessor">#endif</span>
<a name="l00047"></a>00047 <span class="preprocessor"></span><span class="preprocessor">#if !APR_HAVE_IOVEC</span>
<a name="l00048"></a>00048 <span class="preprocessor"></span> <span class="comment">// We don't want apr_want.h to redefine 'struct iovec'.</span>
<a name="l00049"></a>00049 <span class="comment">// http://groups.google.com/group/phusion-passenger/browse_thread/thread/7e162f60df212e9c</span>
<a name="l00050"></a>00050 <span class="preprocessor"> #undef APR_HAVE_IOVEC</span>
<a name="l00051"></a>00051 <span class="preprocessor"></span><span class="preprocessor"> #define APR_HAVE_IOVEC 1</span>
<a name="l00052"></a>00052 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
<a name="l00053"></a>00053 <span class="preprocessor"></span>
<a name="l00054"></a>00054 <span class="preprocessor">#include "Exceptions.h"</span>
<a name="l00055"></a>00055 <span class="preprocessor">#include "Utils.h"</span>
<a name="l00056"></a>00056 <span class="preprocessor">#include "Utils/Timer.h"</span>
<a name="l00057"></a>00057
<a name="l00058"></a>00058 <span class="keyword">namespace </span>Passenger {
<a name="l00059"></a>00059
<a name="l00060"></a>00060 <span class="keyword">using namespace </span>std;
<a name="l00061"></a>00061 <span class="keyword">using namespace </span>oxt;
<a name="l00062"></a>00062 <span class="comment"></span>
<a name="l00063"></a>00063 <span class="comment">/**</span>
<a name="l00064"></a>00064 <span class="comment"> * Convenience class for I/O operations on file descriptors.</span>
<a name="l00065"></a>00065 <span class="comment"> *</span>
<a name="l00066"></a>00066 <span class="comment"> * This class provides convenience methods for:</span>
<a name="l00067"></a>00067 <span class="comment"> * - sending and receiving raw data over a file descriptor.</span>
<a name="l00068"></a>00068 <span class="comment"> * - sending and receiving messages over a file descriptor.</span>
<a name="l00069"></a>00069 <span class="comment"> * - file descriptor passing over a Unix socket.</span>
<a name="l00070"></a>00070 <span class="comment"> * - data size limit enforcement and time constraint enforcement.</span>
<a name="l00071"></a>00071 <span class="comment"> * All of these methods use exceptions for error reporting.</span>
<a name="l00072"></a>00072 <span class="comment"> *</span>
<a name="l00073"></a>00073 <span class="comment"> * There are two kinds of messages:</span>
<a name="l00074"></a>00074 <span class="comment"> * - Array messages. These are just a list of strings, and the message</span>
<a name="l00075"></a>00075 <span class="comment"> * itself has a specific length. The contained strings may not</span>
<a name="l00076"></a>00076 <span class="comment"> * contain NUL characters (<tt>'\\0'</tt>). Note that an array message</span>
<a name="l00077"></a>00077 <span class="comment"> * must have at least one element.</span>
<a name="l00078"></a>00078 <span class="comment"> * - Scalar messages. These are byte strings which may contain arbitrary</span>
<a name="l00079"></a>00079 <span class="comment"> * binary data. Scalar messages also have a specific length.</span>
<a name="l00080"></a>00080 <span class="comment"> * The protocol is designed to be low overhead, easy to implement and</span>
<a name="l00081"></a>00081 <span class="comment"> * easy to parse.</span>
<a name="l00082"></a>00082 <span class="comment"> *</span>
<a name="l00083"></a>00083 <span class="comment"> * MessageChannel is to be wrapped around a file descriptor. For example:</span>
<a name="l00084"></a>00084 <span class="comment"> * @code</span>
<a name="l00085"></a>00085 <span class="comment"> * int p[2];</span>
<a name="l00086"></a>00086 <span class="comment"> * pipe(p);</span>
<a name="l00087"></a>00087 <span class="comment"> * MessageChannel channel1(p[0]);</span>
<a name="l00088"></a>00088 <span class="comment"> * MessageChannel channel2(p[1]);</span>
<a name="l00089"></a>00089 <span class="comment"> * </span>
<a name="l00090"></a>00090 <span class="comment"> * // Send an array message.</span>
<a name="l00091"></a>00091 <span class="comment"> * channel2.write("hello", "world !!", NULL);</span>
<a name="l00092"></a>00092 <span class="comment"> * list<string> args;</span>
<a name="l00093"></a>00093 <span class="comment"> * channel1.read(args); // args now contains { "hello", "world !!" }</span>
<a name="l00094"></a>00094 <span class="comment"> *</span>
<a name="l00095"></a>00095 <span class="comment"> * // Send a scalar message.</span>
<a name="l00096"></a>00096 <span class="comment"> * channel2.writeScalar("some long string which can contain arbitrary binary data");</span>
<a name="l00097"></a>00097 <span class="comment"> * string str;</span>
<a name="l00098"></a>00098 <span class="comment"> * channel1.readScalar(str);</span>
<a name="l00099"></a>00099 <span class="comment"> * @endcode</span>
<a name="l00100"></a>00100 <span class="comment"> *</span>
<a name="l00101"></a>00101 <span class="comment"> * The life time of a MessageChannel is independent from that of the</span>
<a name="l00102"></a>00102 <span class="comment"> * wrapped file descriptor. If a MessageChannel object is destroyed,</span>
<a name="l00103"></a>00103 <span class="comment"> * the file descriptor is not automatically closed. Call close()</span>
<a name="l00104"></a>00104 <span class="comment"> * if you want to close the file descriptor.</span>
<a name="l00105"></a>00105 <span class="comment"> *</span>
<a name="l00106"></a>00106 <span class="comment"> * @note I/O operations are not buffered.</span>
<a name="l00107"></a>00107 <span class="comment"> * @note Be careful with mixing the sending/receiving of array messages,</span>
<a name="l00108"></a>00108 <span class="comment"> * scalar messages and file descriptors. If you send a collection of any</span>
<a name="l00109"></a>00109 <span class="comment"> * of these in a specific order, then the receiving side must receive them</span>
<a name="l00110"></a>00110 <span class="comment"> * in the exact some order. So suppose you first send a message, then a</span>
<a name="l00111"></a>00111 <span class="comment"> * file descriptor, then a scalar, then the receiving side must first</span>
<a name="l00112"></a>00112 <span class="comment"> * receive a message, then a file descriptor, then a scalar. If the</span>
<a name="l00113"></a>00113 <span class="comment"> * receiving side does things in the wrong order then bad things will</span>
<a name="l00114"></a>00114 <span class="comment"> * happen.</span>
<a name="l00115"></a>00115 <span class="comment"> * @note MessageChannel is not thread-safe, but is reentrant.</span>
<a name="l00116"></a>00116 <span class="comment"> * @note Some methods throw SecurityException and TimeoutException. When these</span>
<a name="l00117"></a>00117 <span class="comment"> * exceptions are thrown, the channel will be left in an inconsistent state</span>
<a name="l00118"></a>00118 <span class="comment"> * because only parts of the data have been read. You should close the channel</span>
<a name="l00119"></a>00119 <span class="comment"> * after having caught these exceptions.</span>
<a name="l00120"></a>00120 <span class="comment"> *</span>
<a name="l00121"></a>00121 <span class="comment"> * @ingroup Support</span>
<a name="l00122"></a>00122 <span class="comment"> */</span>
<a name="l00123"></a><a class="code" href="classPassenger_1_1MessageChannel.html">00123</a> <span class="keyword">class </span><a class="code" href="classPassenger_1_1MessageChannel.html" title="Convenience class for I/O operations on file descriptors.">MessageChannel</a> {
<a name="l00124"></a>00124 <span class="keyword">private</span>:
<a name="l00125"></a>00125 <span class="keyword">const</span> <span class="keyword">static</span> <span class="keywordtype">char</span> DELIMITER = <span class="charliteral">'\0'</span>;
<a name="l00126"></a>00126 <span class="keywordtype">int</span> fd;
<a name="l00127"></a>00127
<a name="l00128"></a>00128 <span class="preprocessor"> #ifdef __OpenBSD__</span>
<a name="l00129"></a>00129 <span class="preprocessor"></span> <span class="keyword">typedef</span> u_int32_t uint32_t;
<a name="l00130"></a>00130 <span class="keyword">typedef</span> u_int16_t uint16_t;
<a name="l00131"></a>00131 <span class="preprocessor"> #endif</span>
<a name="l00132"></a>00132 <span class="preprocessor"></span>
<a name="l00133"></a>00133 <span class="keyword">public</span>:<span class="comment"></span>
<a name="l00134"></a>00134 <span class="comment"> /**</span>
<a name="l00135"></a>00135 <span class="comment"> * Construct a new MessageChannel with no underlying file descriptor.</span>
<a name="l00136"></a>00136 <span class="comment"> * Thus the resulting MessageChannel object will not be usable.</span>
<a name="l00137"></a>00137 <span class="comment"> * This constructor exists to allow one to declare an "empty"</span>
<a name="l00138"></a>00138 <span class="comment"> * MessageChannel variable which is to be initialized later.</span>
<a name="l00139"></a>00139 <span class="comment"> */</span>
<a name="l00140"></a><a class="code" href="classPassenger_1_1MessageChannel.html#73e7c9a8e421d29558838176aff02ca4">00140</a> <a class="code" href="classPassenger_1_1MessageChannel.html#73e7c9a8e421d29558838176aff02ca4" title="Construct a new MessageChannel with no underlying file descriptor.">MessageChannel</a>() {
<a name="l00141"></a>00141 this->fd = -1;
<a name="l00142"></a>00142 }
<a name="l00143"></a>00143 <span class="comment"></span>
<a name="l00144"></a>00144 <span class="comment"> /**</span>
<a name="l00145"></a>00145 <span class="comment"> * Construct a new MessageChannel with the given file descriptor.</span>
<a name="l00146"></a>00146 <span class="comment"> */</span>
<a name="l00147"></a><a class="code" href="classPassenger_1_1MessageChannel.html#486b6e74c4d0973eefbcfde65f898ca7">00147</a> <a class="code" href="classPassenger_1_1MessageChannel.html#486b6e74c4d0973eefbcfde65f898ca7" title="Construct a new MessageChannel with the given file descriptor.">MessageChannel</a>(<span class="keywordtype">int</span> fd) {
<a name="l00148"></a>00148 this->fd = fd;
<a name="l00149"></a>00149 }
<a name="l00150"></a>00150 <span class="comment"></span>
<a name="l00151"></a>00151 <span class="comment"> /**</span>
<a name="l00152"></a>00152 <span class="comment"> * Returns the underlying file descriptor. -1 if it has already been closed.</span>
<a name="l00153"></a>00153 <span class="comment"> */</span>
<a name="l00154"></a><a class="code" href="classPassenger_1_1MessageChannel.html#0b1e25dd75783d9753f8a0d1dd42606a">00154</a> <span class="keywordtype">int</span> <a class="code" href="classPassenger_1_1MessageChannel.html#0b1e25dd75783d9753f8a0d1dd42606a" title="Returns the underlying file descriptor.">filenum</a>()<span class="keyword"> const </span>{
<a name="l00155"></a>00155 <span class="keywordflow">return</span> fd;
<a name="l00156"></a>00156 }
<a name="l00157"></a>00157 <span class="comment"></span>
<a name="l00158"></a>00158 <span class="comment"> /**</span>
<a name="l00159"></a>00159 <span class="comment"> * Returns whether close() has been called.</span>
<a name="l00160"></a>00160 <span class="comment"> */</span>
<a name="l00161"></a><a class="code" href="classPassenger_1_1MessageChannel.html#a5ee9617bb17bdeaba30b757ecffa1b5">00161</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#a5ee9617bb17bdeaba30b757ecffa1b5" title="Returns whether close() has been called.">connected</a>()<span class="keyword"> const </span>{
<a name="l00162"></a>00162 <span class="keywordflow">return</span> fd != -1;
<a name="l00163"></a>00163 }
<a name="l00164"></a>00164 <span class="comment"></span>
<a name="l00165"></a>00165 <span class="comment"> /**</span>
<a name="l00166"></a>00166 <span class="comment"> * Close the underlying file descriptor. If this method is called multiple</span>
<a name="l00167"></a>00167 <span class="comment"> * times, the file descriptor will only be closed the first time.</span>
<a name="l00168"></a>00168 <span class="comment"> *</span>
<a name="l00169"></a>00169 <span class="comment"> * @throw SystemException</span>
<a name="l00170"></a>00170 <span class="comment"> * @throw boost::thread_interrupted</span>
<a name="l00171"></a>00171 <span class="comment"> * @post filenum() == -1</span>
<a name="l00172"></a>00172 <span class="comment"> * @post !connected()</span>
<a name="l00173"></a>00173 <span class="comment"> */</span>
<a name="l00174"></a><a class="code" href="classPassenger_1_1MessageChannel.html#06309e208fc5e10642a2e9bbe0f351eb">00174</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#06309e208fc5e10642a2e9bbe0f351eb" title="Close the underlying file descriptor.">close</a>() {
<a name="l00175"></a>00175 <span class="keywordflow">if</span> (fd != -1) {
<a name="l00176"></a>00176 <span class="keywordtype">int</span> ret = <a class="code" href="classPassenger_1_1MessageChannel.html#06309e208fc5e10642a2e9bbe0f351eb" title="Close the underlying file descriptor.">syscalls::close</a>(fd);
<a name="l00177"></a>00177 fd = -1;
<a name="l00178"></a>00178 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00179"></a>00179 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"Cannot close file descriptor"</span>, errno);
<a name="l00180"></a>00180 }
<a name="l00181"></a>00181 }
<a name="l00182"></a>00182 }
<a name="l00183"></a>00183 <span class="comment"></span>
<a name="l00184"></a>00184 <span class="comment"> /**</span>
<a name="l00185"></a>00185 <span class="comment"> * Send an array message, which consists of the given elements, over the underlying</span>
<a name="l00186"></a>00186 <span class="comment"> * file descriptor.</span>
<a name="l00187"></a>00187 <span class="comment"> *</span>
<a name="l00188"></a>00188 <span class="comment"> * @param args An object which contains the message elements. This object must</span>
<a name="l00189"></a>00189 <span class="comment"> * support STL-style iteration, and each iterator must have an</span>
<a name="l00190"></a>00190 <span class="comment"> * std::string as value. Use the StringArrayType and</span>
<a name="l00191"></a>00191 <span class="comment"> * StringArrayConstIteratorType template parameters to specify the exact type names.</span>
<a name="l00192"></a>00192 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00193"></a>00193 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00194"></a>00194 <span class="comment"> * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).</span>
<a name="l00195"></a>00195 <span class="comment"> * @see read(), write(const char *, ...)</span>
<a name="l00196"></a>00196 <span class="comment"> */</span>
<a name="l00197"></a>00197 <span class="keyword">template</span><<span class="keyword">typename</span> StringArrayType, <span class="keyword">typename</span> StringArrayConstIteratorType>
<a name="l00198"></a><a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d">00198</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(<span class="keyword">const</span> StringArrayType &args) {
<a name="l00199"></a>00199 StringArrayConstIteratorType it;
<a name="l00200"></a>00200 <span class="keywordtype">string</span> data;
<a name="l00201"></a>00201 uint16_t dataSize = 0;
<a name="l00202"></a>00202
<a name="l00203"></a>00203 <span class="keywordflow">for</span> (it = args.begin(); it != args.end(); it++) {
<a name="l00204"></a>00204 dataSize += it->size() + 1;
<a name="l00205"></a>00205 }
<a name="l00206"></a>00206 data.reserve(dataSize + <span class="keyword">sizeof</span>(dataSize));
<a name="l00207"></a>00207 dataSize = htons(dataSize);
<a name="l00208"></a>00208 data.append((<span class="keyword">const</span> <span class="keywordtype">char</span> *) &dataSize, <span class="keyword">sizeof</span>(dataSize));
<a name="l00209"></a>00209 <span class="keywordflow">for</span> (it = args.begin(); it != args.end(); it++) {
<a name="l00210"></a>00210 data.append(*it);
<a name="l00211"></a>00211 data.append(1, DELIMITER);
<a name="l00212"></a>00212 }
<a name="l00213"></a>00213
<a name="l00214"></a>00214 <a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef" title="Send a block of data over the underlying file descriptor.">writeRaw</a>(data);
<a name="l00215"></a>00215 }
<a name="l00216"></a>00216 <span class="comment"></span>
<a name="l00217"></a>00217 <span class="comment"> /**</span>
<a name="l00218"></a>00218 <span class="comment"> * Send an array message, which consists of the given elements, over the underlying</span>
<a name="l00219"></a>00219 <span class="comment"> * file descriptor.</span>
<a name="l00220"></a>00220 <span class="comment"> *</span>
<a name="l00221"></a>00221 <span class="comment"> * @param args The message elements.</span>
<a name="l00222"></a>00222 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00223"></a>00223 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00224"></a>00224 <span class="comment"> * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).</span>
<a name="l00225"></a>00225 <span class="comment"> * @see read(), write(const char *, ...)</span>
<a name="l00226"></a>00226 <span class="comment"> */</span>
<a name="l00227"></a><a class="code" href="classPassenger_1_1MessageChannel.html#9ad7a978cf8409e01ab2f0a2b6be5a0a">00227</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#9ad7a978cf8409e01ab2f0a2b6be5a0a" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(<span class="keyword">const</span> list<string> &args) {
<a name="l00228"></a>00228 write<list<string>, list<string>::const_iterator>(args);
<a name="l00229"></a>00229 }
<a name="l00230"></a>00230 <span class="comment"></span>
<a name="l00231"></a>00231 <span class="comment"> /**</span>
<a name="l00232"></a>00232 <span class="comment"> * Send an array message, which consists of the given elements, over the underlying</span>
<a name="l00233"></a>00233 <span class="comment"> * file descriptor.</span>
<a name="l00234"></a>00234 <span class="comment"> *</span>
<a name="l00235"></a>00235 <span class="comment"> * @param args The message elements.</span>
<a name="l00236"></a>00236 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00237"></a>00237 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00238"></a>00238 <span class="comment"> * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).</span>
<a name="l00239"></a>00239 <span class="comment"> * @see read(), write(const char *, ...)</span>
<a name="l00240"></a>00240 <span class="comment"> */</span>
<a name="l00241"></a><a class="code" href="classPassenger_1_1MessageChannel.html#6a9bc5d72715cb7ba0e437c8851ef487">00241</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#6a9bc5d72715cb7ba0e437c8851ef487" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(<span class="keyword">const</span> vector<string> &args) {
<a name="l00242"></a>00242 write<vector<string>, vector<string>::const_iterator>(args);
<a name="l00243"></a>00243 }
<a name="l00244"></a>00244 <span class="comment"></span>
<a name="l00245"></a>00245 <span class="comment"> /**</span>
<a name="l00246"></a>00246 <span class="comment"> * Send an array message, which consists of the given strings, over the underlying</span>
<a name="l00247"></a>00247 <span class="comment"> * file descriptor. Like <tt>write(const char *name, ...)</tt> but takes a va_list</span>
<a name="l00248"></a>00248 <span class="comment"> * instead.</span>
<a name="l00249"></a>00249 <span class="comment"> *</span>
<a name="l00250"></a>00250 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00251"></a>00251 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00252"></a>00252 <span class="comment"> * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).</span>
<a name="l00253"></a>00253 <span class="comment"> */</span>
<a name="l00254"></a><a class="code" href="classPassenger_1_1MessageChannel.html#70cc924c1ce7e2cedcbab61155d3aec9">00254</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#70cc924c1ce7e2cedcbab61155d3aec9" title="Send an array message, which consists of the given strings, over the underlying file...">write</a>(<span class="keyword">const</span> <span class="keywordtype">char</span> *name, va_list &ap) {
<a name="l00255"></a>00255 list<string> args;
<a name="l00256"></a>00256 args.push_back(name);
<a name="l00257"></a>00257
<a name="l00258"></a>00258 <span class="keywordflow">while</span> (<span class="keyword">true</span>) {
<a name="l00259"></a>00259 <span class="keyword">const</span> <span class="keywordtype">char</span> *arg = va_arg(ap, <span class="keyword">const</span> <span class="keywordtype">char</span> *);
<a name="l00260"></a>00260 <span class="keywordflow">if</span> (arg == NULL) {
<a name="l00261"></a>00261 <span class="keywordflow">break</span>;
<a name="l00262"></a>00262 } <span class="keywordflow">else</span> {
<a name="l00263"></a>00263 args.push_back(arg);
<a name="l00264"></a>00264 }
<a name="l00265"></a>00265 }
<a name="l00266"></a>00266 <a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(args);
<a name="l00267"></a>00267 }
<a name="l00268"></a>00268 <span class="comment"></span>
<a name="l00269"></a>00269 <span class="comment"> /**</span>
<a name="l00270"></a>00270 <span class="comment"> * Send an array message, which consists of the given strings, over the underlying</span>
<a name="l00271"></a>00271 <span class="comment"> * file descriptor.</span>
<a name="l00272"></a>00272 <span class="comment"> *</span>
<a name="l00273"></a>00273 <span class="comment"> * @param name The first element of the message to send.</span>
<a name="l00274"></a>00274 <span class="comment"> * @param ... Other elements of the message. These *must* be strings, i.e. of type char*.</span>
<a name="l00275"></a>00275 <span class="comment"> * It is also required to terminate this list with a NULL.</span>
<a name="l00276"></a>00276 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00277"></a>00277 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00278"></a>00278 <span class="comment"> * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).</span>
<a name="l00279"></a>00279 <span class="comment"> * @see read(), write(const list<string> &)</span>
<a name="l00280"></a>00280 <span class="comment"> */</span>
<a name="l00281"></a><a class="code" href="classPassenger_1_1MessageChannel.html#12cce3364023eacbe4fe09006cf3d38d">00281</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#12cce3364023eacbe4fe09006cf3d38d" title="Send an array message, which consists of the given strings, over the underlying file...">write</a>(<span class="keyword">const</span> <span class="keywordtype">char</span> *name, ...) {
<a name="l00282"></a>00282 va_list ap;
<a name="l00283"></a>00283 va_start(ap, name);
<a name="l00284"></a>00284 <span class="keywordflow">try</span> {
<a name="l00285"></a>00285 <a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(name, ap);
<a name="l00286"></a>00286 va_end(ap);
<a name="l00287"></a>00287 } <span class="keywordflow">catch</span> (...) {
<a name="l00288"></a>00288 va_end(ap);
<a name="l00289"></a>00289 <span class="keywordflow">throw</span>;
<a name="l00290"></a>00290 }
<a name="l00291"></a>00291 }
<a name="l00292"></a>00292 <span class="comment"></span>
<a name="l00293"></a>00293 <span class="comment"> /**</span>
<a name="l00294"></a>00294 <span class="comment"> * Write a 32-bit big-endian unsigned integer to the underlying file descriptor.</span>
<a name="l00295"></a>00295 <span class="comment"> *</span>
<a name="l00296"></a>00296 <span class="comment"> * @throws SystemException An error occurred while writing the data to the file descriptor.</span>
<a name="l00297"></a>00297 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00298"></a>00298 <span class="comment"> */</span>
<a name="l00299"></a><a class="code" href="classPassenger_1_1MessageChannel.html#bf02c51a74477650de8d5d5db661063b">00299</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#bf02c51a74477650de8d5d5db661063b" title="Write a 32-bit big-endian unsigned integer to the underlying file descriptor.">writeUint32</a>(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> value) {
<a name="l00300"></a>00300 uint32_t l = htonl(value);
<a name="l00301"></a>00301 <a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef" title="Send a block of data over the underlying file descriptor.">writeRaw</a>((<span class="keyword">const</span> <span class="keywordtype">char</span> *) &l, <span class="keyword">sizeof</span>(uint32_t));
<a name="l00302"></a>00302 }
<a name="l00303"></a>00303 <span class="comment"></span>
<a name="l00304"></a>00304 <span class="comment"> /**</span>
<a name="l00305"></a>00305 <span class="comment"> * Write a scalar message to the underlying file descriptor.</span>
<a name="l00306"></a>00306 <span class="comment"> *</span>
<a name="l00307"></a>00307 <span class="comment"> * @note Security guarantee: this method will not copy the data in memory,</span>
<a name="l00308"></a>00308 <span class="comment"> * so it's safe to use this method to write passwords to the underlying</span>
<a name="l00309"></a>00309 <span class="comment"> * file descriptor.</span>
<a name="l00310"></a>00310 <span class="comment"> *</span>
<a name="l00311"></a>00311 <span class="comment"> * @param str The scalar message's content.</span>
<a name="l00312"></a>00312 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00313"></a>00313 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00314"></a>00314 <span class="comment"> * @see readScalar(), writeScalar(const char *, unsigned int)</span>
<a name="l00315"></a>00315 <span class="comment"> */</span>
<a name="l00316"></a><a class="code" href="classPassenger_1_1MessageChannel.html#44e01a783c48abadeea0d915b9893bfb">00316</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#44e01a783c48abadeea0d915b9893bfb" title="Write a scalar message to the underlying file descriptor.">writeScalar</a>(<span class="keyword">const</span> <span class="keywordtype">string</span> &str) {
<a name="l00317"></a>00317 <a class="code" href="classPassenger_1_1MessageChannel.html#44e01a783c48abadeea0d915b9893bfb" title="Write a scalar message to the underlying file descriptor.">writeScalar</a>(str.c_str(), str.size());
<a name="l00318"></a>00318 }
<a name="l00319"></a>00319 <span class="comment"></span>
<a name="l00320"></a>00320 <span class="comment"> /**</span>
<a name="l00321"></a>00321 <span class="comment"> * Write a scalar message to the underlying file descriptor.</span>
<a name="l00322"></a>00322 <span class="comment"> *</span>
<a name="l00323"></a>00323 <span class="comment"> * @note Security guarantee: this method will not copy the data in memory,</span>
<a name="l00324"></a>00324 <span class="comment"> * so it's safe to use this method to write passwords to the underlying</span>
<a name="l00325"></a>00325 <span class="comment"> * file descriptor.</span>
<a name="l00326"></a>00326 <span class="comment"> *</span>
<a name="l00327"></a>00327 <span class="comment"> * @param data The scalar message's content.</span>
<a name="l00328"></a>00328 <span class="comment"> * @param size The number of bytes in <tt>data</tt>.</span>
<a name="l00329"></a>00329 <span class="comment"> * @pre <tt>data != NULL</tt></span>
<a name="l00330"></a>00330 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00331"></a>00331 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00332"></a>00332 <span class="comment"> * @see readScalar(), writeScalar(const string &)</span>
<a name="l00333"></a>00333 <span class="comment"> */</span>
<a name="l00334"></a><a class="code" href="classPassenger_1_1MessageChannel.html#80977020ef895f3ea790c5d28a333dda">00334</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#80977020ef895f3ea790c5d28a333dda" title="Write a scalar message to the underlying file descriptor.">writeScalar</a>(<span class="keyword">const</span> <span class="keywordtype">char</span> *data, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> size) {
<a name="l00335"></a>00335 <a class="code" href="classPassenger_1_1MessageChannel.html#bf02c51a74477650de8d5d5db661063b" title="Write a 32-bit big-endian unsigned integer to the underlying file descriptor.">writeUint32</a>(size);
<a name="l00336"></a>00336 <a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef" title="Send a block of data over the underlying file descriptor.">writeRaw</a>(data, size);
<a name="l00337"></a>00337 }
<a name="l00338"></a>00338 <span class="comment"></span>
<a name="l00339"></a>00339 <span class="comment"> /**</span>
<a name="l00340"></a>00340 <span class="comment"> * Send a block of data over the underlying file descriptor.</span>
<a name="l00341"></a>00341 <span class="comment"> * This method blocks until everything is sent.</span>
<a name="l00342"></a>00342 <span class="comment"> *</span>
<a name="l00343"></a>00343 <span class="comment"> * @note Security guarantee: this method will not copy the data in memory,</span>
<a name="l00344"></a>00344 <span class="comment"> * so it's safe to use this method to write passwords to the underlying</span>
<a name="l00345"></a>00345 <span class="comment"> * file descriptor.</span>
<a name="l00346"></a>00346 <span class="comment"> *</span>
<a name="l00347"></a>00347 <span class="comment"> * @param data The data to send.</span>
<a name="l00348"></a>00348 <span class="comment"> * @param size The number of bytes in <tt>data</tt>.</span>
<a name="l00349"></a>00349 <span class="comment"> * @pre <tt>data != NULL</tt></span>
<a name="l00350"></a>00350 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00351"></a>00351 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00352"></a>00352 <span class="comment"> * @see readRaw()</span>
<a name="l00353"></a>00353 <span class="comment"> */</span>
<a name="l00354"></a><a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef">00354</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef" title="Send a block of data over the underlying file descriptor.">writeRaw</a>(<span class="keyword">const</span> <span class="keywordtype">char</span> *data, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> size) {
<a name="l00355"></a>00355 ssize_t ret;
<a name="l00356"></a>00356 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> written = 0;
<a name="l00357"></a>00357 <span class="keywordflow">do</span> {
<a name="l00358"></a>00358 ret = <a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d" title="Send an array message, which consists of the given elements, over the underlying...">syscalls::write</a>(fd, data + written, size - written);
<a name="l00359"></a>00359 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00360"></a>00360 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"write() failed"</span>, errno);
<a name="l00361"></a>00361 } <span class="keywordflow">else</span> {
<a name="l00362"></a>00362 written += ret;
<a name="l00363"></a>00363 }
<a name="l00364"></a>00364 } <span class="keywordflow">while</span> (written < size);
<a name="l00365"></a>00365 }
<a name="l00366"></a>00366 <span class="comment"></span>
<a name="l00367"></a>00367 <span class="comment"> /**</span>
<a name="l00368"></a>00368 <span class="comment"> * Send a block of data over the underlying file descriptor.</span>
<a name="l00369"></a>00369 <span class="comment"> * This method blocks until everything is sent.</span>
<a name="l00370"></a>00370 <span class="comment"> *</span>
<a name="l00371"></a>00371 <span class="comment"> * @note Security guarantee: this method will not copy the data in memory,</span>
<a name="l00372"></a>00372 <span class="comment"> * so it's safe to use this method to write passwords to the underlying</span>
<a name="l00373"></a>00373 <span class="comment"> * file descriptor.</span>
<a name="l00374"></a>00374 <span class="comment"> *</span>
<a name="l00375"></a>00375 <span class="comment"> * @param data The data to send.</span>
<a name="l00376"></a>00376 <span class="comment"> * @pre <tt>data != NULL</tt></span>
<a name="l00377"></a>00377 <span class="comment"> * @throws SystemException An error occured while writing the data to the file descriptor.</span>
<a name="l00378"></a>00378 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00379"></a>00379 <span class="comment"> */</span>
<a name="l00380"></a><a class="code" href="classPassenger_1_1MessageChannel.html#cfa38f4f0e22ec16350b8cc159e8e364">00380</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#cfa38f4f0e22ec16350b8cc159e8e364" title="Send a block of data over the underlying file descriptor.">writeRaw</a>(<span class="keyword">const</span> <span class="keywordtype">string</span> &data) {
<a name="l00381"></a>00381 <a class="code" href="classPassenger_1_1MessageChannel.html#069314e4c7e1fe8c8ab36e16d2cc5fef" title="Send a block of data over the underlying file descriptor.">writeRaw</a>(data.c_str(), data.size());
<a name="l00382"></a>00382 }
<a name="l00383"></a>00383 <span class="comment"></span>
<a name="l00384"></a>00384 <span class="comment"> /**</span>
<a name="l00385"></a>00385 <span class="comment"> * Pass a file descriptor. This only works if the underlying file</span>
<a name="l00386"></a>00386 <span class="comment"> * descriptor is a Unix socket.</span>
<a name="l00387"></a>00387 <span class="comment"> *</span>
<a name="l00388"></a>00388 <span class="comment"> * @param fileDescriptor The file descriptor to pass.</span>
<a name="l00389"></a>00389 <span class="comment"> * @param negotiate See Ruby's MessageChannel#send_io method's comments.</span>
<a name="l00390"></a>00390 <span class="comment"> * @throws SystemException Something went wrong during file descriptor passing.</span>
<a name="l00391"></a>00391 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00392"></a>00392 <span class="comment"> * @pre <tt>fileDescriptor >= 0</tt></span>
<a name="l00393"></a>00393 <span class="comment"> * @see readFileDescriptor()</span>
<a name="l00394"></a>00394 <span class="comment"> */</span>
<a name="l00395"></a><a class="code" href="classPassenger_1_1MessageChannel.html#e0c558e07dcc91900016773b2bec38d8">00395</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#e0c558e07dcc91900016773b2bec38d8" title="Pass a file descriptor.">writeFileDescriptor</a>(<span class="keywordtype">int</span> fileDescriptor, <span class="keywordtype">bool</span> negotiate = <span class="keyword">true</span>) {
<a name="l00396"></a>00396 <span class="keywordflow">if</span> (negotiate) {
<a name="l00397"></a>00397 vector<string> args;
<a name="l00398"></a>00398
<a name="l00399"></a>00399 <span class="keywordflow">if</span> (!<a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e" title="Read an array message from the underlying file descriptor.">read</a>(args)) {
<a name="l00400"></a>00400 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1IOException.html" title="Represents an error that occured during an I/O operation.">IOException</a>(<span class="stringliteral">"Unexpected end of stream encountered"</span>);
<a name="l00401"></a>00401 } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (args.size() != 1 || args[0] != <span class="stringliteral">"pass IO"</span>) {
<a name="l00402"></a>00402 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1IOException.html" title="Represents an error that occured during an I/O operation.">IOException</a>(<span class="stringliteral">"FD passing negotiation message expected."</span>);
<a name="l00403"></a>00403 }
<a name="l00404"></a>00404 }
<a name="l00405"></a>00405
<a name="l00406"></a>00406 <span class="keyword">struct </span>msghdr msg;
<a name="l00407"></a>00407 <span class="keyword">struct </span>iovec vec;
<a name="l00408"></a>00408 <span class="keywordtype">char</span> dummy[1];
<a name="l00409"></a>00409 <span class="preprocessor"> #if defined(__APPLE__) || defined(__SOLARIS__) || defined(__arm__)</span>
<a name="l00410"></a>00410 <span class="preprocessor"></span> <span class="keyword">struct </span>{
<a name="l00411"></a>00411 <span class="keyword">struct </span>cmsghdr header;
<a name="l00412"></a>00412 <span class="keywordtype">int</span> fd;
<a name="l00413"></a>00413 } control_data;
<a name="l00414"></a>00414 <span class="preprocessor"> #else</span>
<a name="l00415"></a>00415 <span class="preprocessor"></span> <span class="keywordtype">char</span> control_data[CMSG_SPACE(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>))];
<a name="l00416"></a>00416 <span class="preprocessor"> #endif</span>
<a name="l00417"></a>00417 <span class="preprocessor"></span> <span class="keyword">struct </span>cmsghdr *control_header;
<a name="l00418"></a>00418 <span class="keywordtype">int</span> ret;
<a name="l00419"></a>00419
<a name="l00420"></a>00420 msg.msg_name = NULL;
<a name="l00421"></a>00421 msg.msg_namelen = 0;
<a name="l00422"></a>00422
<a name="l00423"></a>00423 <span class="comment">/* Linux and Solaris require msg_iov to be non-NULL. */</span>
<a name="l00424"></a>00424 dummy[0] = <span class="charliteral">'\0'</span>;
<a name="l00425"></a>00425 vec.iov_base = dummy;
<a name="l00426"></a>00426 vec.iov_len = <span class="keyword">sizeof</span>(dummy);
<a name="l00427"></a>00427 msg.msg_iov = &vec;
<a name="l00428"></a>00428 msg.msg_iovlen = 1;
<a name="l00429"></a>00429
<a name="l00430"></a>00430 msg.msg_control = (caddr_t) &control_data;
<a name="l00431"></a>00431 msg.msg_controllen = <span class="keyword">sizeof</span>(control_data);
<a name="l00432"></a>00432 msg.msg_flags = 0;
<a name="l00433"></a>00433
<a name="l00434"></a>00434 control_header = CMSG_FIRSTHDR(&msg);
<a name="l00435"></a>00435 control_header->cmsg_level = SOL_SOCKET;
<a name="l00436"></a>00436 control_header->cmsg_type = SCM_RIGHTS;
<a name="l00437"></a>00437 <span class="preprocessor"> #if defined(__APPLE__) || defined(__SOLARIS__) || defined(__arm__)</span>
<a name="l00438"></a>00438 <span class="preprocessor"></span> control_header->cmsg_len = <span class="keyword">sizeof</span>(control_data);
<a name="l00439"></a>00439 control_data.fd = fileDescriptor;
<a name="l00440"></a>00440 <span class="preprocessor"> #else</span>
<a name="l00441"></a>00441 <span class="preprocessor"></span> control_header->cmsg_len = CMSG_LEN(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>));
<a name="l00442"></a>00442 memcpy(CMSG_DATA(control_header), &fileDescriptor, <span class="keyword">sizeof</span>(<span class="keywordtype">int</span>));
<a name="l00443"></a>00443 <span class="preprocessor"> #endif</span>
<a name="l00444"></a>00444 <span class="preprocessor"></span>
<a name="l00445"></a>00445 ret = syscalls::sendmsg(fd, &msg, 0);
<a name="l00446"></a>00446 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00447"></a>00447 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"Cannot send file descriptor with sendmsg()"</span>, errno);
<a name="l00448"></a>00448 }
<a name="l00449"></a>00449 }
<a name="l00450"></a>00450 <span class="comment"></span>
<a name="l00451"></a>00451 <span class="comment"> /**</span>
<a name="l00452"></a>00452 <span class="comment"> * Read an array message from the underlying file descriptor.</span>
<a name="l00453"></a>00453 <span class="comment"> *</span>
<a name="l00454"></a>00454 <span class="comment"> * @param args The message will be put in this variable.</span>
<a name="l00455"></a>00455 <span class="comment"> * @return Whether end-of-file has been reached. If so, then the contents</span>
<a name="l00456"></a>00456 <span class="comment"> * of <tt>args</tt> will be undefined.</span>
<a name="l00457"></a>00457 <span class="comment"> * @throws SystemException If an error occured while receiving the message.</span>
<a name="l00458"></a>00458 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00459"></a>00459 <span class="comment"> * @see write()</span>
<a name="l00460"></a>00460 <span class="comment"> */</span>
<a name="l00461"></a><a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e">00461</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e" title="Read an array message from the underlying file descriptor.">read</a>(vector<string> &args) {
<a name="l00462"></a>00462 uint16_t size;
<a name="l00463"></a>00463 <span class="keywordtype">int</span> ret;
<a name="l00464"></a>00464 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> alreadyRead = 0;
<a name="l00465"></a>00465
<a name="l00466"></a>00466 <span class="keywordflow">do</span> {
<a name="l00467"></a>00467 ret = <a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e" title="Read an array message from the underlying file descriptor.">syscalls::read</a>(fd, (<span class="keywordtype">char</span> *) &size + alreadyRead, <span class="keyword">sizeof</span>(size) - alreadyRead);
<a name="l00468"></a>00468 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00469"></a>00469 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"read() failed"</span>, errno);
<a name="l00470"></a>00470 } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (ret == 0) {
<a name="l00471"></a>00471 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00472"></a>00472 }
<a name="l00473"></a>00473 alreadyRead += ret;
<a name="l00474"></a>00474 } <span class="keywordflow">while</span> (alreadyRead < <span class="keyword">sizeof</span>(size));
<a name="l00475"></a>00475 size = ntohs(size);
<a name="l00476"></a>00476
<a name="l00477"></a>00477 <span class="keywordtype">string</span> buffer;
<a name="l00478"></a>00478 args.clear();
<a name="l00479"></a>00479 buffer.reserve(size);
<a name="l00480"></a>00480 <span class="keywordflow">while</span> (buffer.size() < size) {
<a name="l00481"></a>00481 <span class="keywordtype">char</span> tmp[1024 * 8];
<a name="l00482"></a>00482 ret = <a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e" title="Read an array message from the underlying file descriptor.">syscalls::read</a>(fd, tmp, min(size - buffer.size(), <span class="keyword">sizeof</span>(tmp)));
<a name="l00483"></a>00483 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00484"></a>00484 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"read() failed"</span>, errno);
<a name="l00485"></a>00485 } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (ret == 0) {
<a name="l00486"></a>00486 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00487"></a>00487 }
<a name="l00488"></a>00488 buffer.append(tmp, ret);
<a name="l00489"></a>00489 }
<a name="l00490"></a>00490
<a name="l00491"></a>00491 <span class="keywordflow">if</span> (!buffer.empty()) {
<a name="l00492"></a>00492 string::size_type start = 0, pos;
<a name="l00493"></a>00493 <span class="keyword">const</span> <span class="keywordtype">string</span> &const_buffer(buffer);
<a name="l00494"></a>00494 <span class="keywordflow">while</span> ((pos = const_buffer.find(<span class="charliteral">'\0'</span>, start)) != string::npos) {
<a name="l00495"></a>00495 args.push_back(const_buffer.substr(start, pos - start));
<a name="l00496"></a>00496 start = pos + 1;
<a name="l00497"></a>00497 }
<a name="l00498"></a>00498 }
<a name="l00499"></a>00499 <span class="keywordflow">return</span> <span class="keyword">true</span>;
<a name="l00500"></a>00500 }
<a name="l00501"></a>00501 <span class="comment"></span>
<a name="l00502"></a>00502 <span class="comment"> /**</span>
<a name="l00503"></a>00503 <span class="comment"> * Read a 32-bit big-endian unsigned integer from the underlying file descriptor.</span>
<a name="l00504"></a>00504 <span class="comment"> *</span>
<a name="l00505"></a>00505 <span class="comment"> * @param value Upon success, the read value will be stored in here.</span>
<a name="l00506"></a>00506 <span class="comment"> * @param timeout A pointer to an integer, representing the maximum number of</span>
<a name="l00507"></a>00507 <span class="comment"> * milliseconds to spend on reading the entire integer.</span>
<a name="l00508"></a>00508 <span class="comment"> * A TimeoutException will be thrown if the timeout expires.</span>
<a name="l00509"></a>00509 <span class="comment"> * If no exception is thrown, the the amount of time spent on waiting</span>
<a name="l00510"></a>00510 <span class="comment"> * will be deducted from <tt>*timeout</tt>.</span>
<a name="l00511"></a>00511 <span class="comment"> * Pass NULL if you do not want to enforce any time limits.</span>
<a name="l00512"></a>00512 <span class="comment"> * @return True if a value was read, false if EOF was reached before all data can be</span>
<a name="l00513"></a>00513 <span class="comment"> * read.</span>
<a name="l00514"></a>00514 <span class="comment"> * @throws SystemException An error occurred while reading data from the file descriptor.</span>
<a name="l00515"></a>00515 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00516"></a>00516 <span class="comment"> */</span>
<a name="l00517"></a><a class="code" href="classPassenger_1_1MessageChannel.html#7b0c67852ea8ab455af75b1037c7f8b6">00517</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#7b0c67852ea8ab455af75b1037c7f8b6" title="Read a 32-bit big-endian unsigned integer from the underlying file descriptor.">readUint32</a>(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> &value, <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> *timeout = NULL) {
<a name="l00518"></a>00518 uint32_t temp;
<a name="l00519"></a>00519
<a name="l00520"></a>00520 <span class="keywordflow">if</span> (!<a class="code" href="classPassenger_1_1MessageChannel.html#b471dc1888f030e20ed23068a160ec2a" title="Read exactly size bytes of data from the underlying file descriptor, and put the...">readRaw</a>(&temp, <span class="keyword">sizeof</span>(uint32_t), timeout)) {
<a name="l00521"></a>00521 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00522"></a>00522 } <span class="keywordflow">else</span> {
<a name="l00523"></a>00523 value = ntohl(temp);
<a name="l00524"></a>00524 <span class="keywordflow">return</span> <span class="keyword">true</span>;
<a name="l00525"></a>00525 }
<a name="l00526"></a>00526 }
<a name="l00527"></a>00527 <span class="comment"></span>
<a name="l00528"></a>00528 <span class="comment"> /**</span>
<a name="l00529"></a>00529 <span class="comment"> * Read a scalar message from the underlying file descriptor.</span>
<a name="l00530"></a>00530 <span class="comment"> *</span>
<a name="l00531"></a>00531 <span class="comment"> * @param output The message will be put in here.</span>
<a name="l00532"></a>00532 <span class="comment"> * @param maxSize The maximum number of bytes that may be read. If the</span>
<a name="l00533"></a>00533 <span class="comment"> * scalar to read is larger than this, then a SecurityException</span>
<a name="l00534"></a>00534 <span class="comment"> * will be thrown. Set to 0 for no size limit.</span>
<a name="l00535"></a>00535 <span class="comment"> * @param timeout A pointer to an integer, representing the maximum number of</span>
<a name="l00536"></a>00536 <span class="comment"> * milliseconds to spend on reading the entire scalar.</span>
<a name="l00537"></a>00537 <span class="comment"> * A TimeoutException will be thrown if unable to read the entire</span>
<a name="l00538"></a>00538 <span class="comment"> * scalar within this time period.</span>
<a name="l00539"></a>00539 <span class="comment"> * If no exception is thrown, the the amount of time spent on waiting</span>
<a name="l00540"></a>00540 <span class="comment"> * will be deducted from <tt>*timeout</tt>.</span>
<a name="l00541"></a>00541 <span class="comment"> * Pass NULL if you do not want to enforce any time limits.</span>
<a name="l00542"></a>00542 <span class="comment"> * @returns Whether end-of-file was reached during reading.</span>
<a name="l00543"></a>00543 <span class="comment"> * @throws SystemException An error occured while reading data from the file descriptor.</span>
<a name="l00544"></a>00544 <span class="comment"> * @throws SecurityException There is more data to read than allowed by maxSize.</span>
<a name="l00545"></a>00545 <span class="comment"> * @throws TimeoutException Unable to read the entire scalar within <tt>timeout</tt></span>
<a name="l00546"></a>00546 <span class="comment"> * milliseconds.</span>
<a name="l00547"></a>00547 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00548"></a>00548 <span class="comment"> * @see writeScalar()</span>
<a name="l00549"></a>00549 <span class="comment"> */</span>
<a name="l00550"></a><a class="code" href="classPassenger_1_1MessageChannel.html#1f3cf672b566166ed920c2bba4d19604">00550</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#1f3cf672b566166ed920c2bba4d19604" title="Read a scalar message from the underlying file descriptor.">readScalar</a>(<span class="keywordtype">string</span> &output, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> maxSize = 0, <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> *timeout = NULL) {
<a name="l00551"></a>00551 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> size;
<a name="l00552"></a>00552 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> remaining;
<a name="l00553"></a>00553
<a name="l00554"></a>00554 <span class="keywordflow">if</span> (!<a class="code" href="classPassenger_1_1MessageChannel.html#7b0c67852ea8ab455af75b1037c7f8b6" title="Read a 32-bit big-endian unsigned integer from the underlying file descriptor.">readUint32</a>(size, timeout)) {
<a name="l00555"></a>00555 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00556"></a>00556 }
<a name="l00557"></a>00557
<a name="l00558"></a>00558 <span class="keywordflow">if</span> (maxSize != 0 && size > maxSize) {
<a name="l00559"></a>00559 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SecurityException.html" title="Represents some kind of security error.">SecurityException</a>(<span class="stringliteral">"There is more data available than is allowed by the size limit."</span>);
<a name="l00560"></a>00560 }
<a name="l00561"></a>00561
<a name="l00562"></a>00562 output.clear();
<a name="l00563"></a>00563 output.reserve(size);
<a name="l00564"></a>00564 remaining = size;
<a name="l00565"></a>00565 <span class="keywordflow">if</span> (OXT_LIKELY(remaining > 0)) {
<a name="l00566"></a>00566 <span class="keywordtype">char</span> buf[1024 * 32];
<a name="l00567"></a>00567 <span class="comment">// Wipe the buffer when we're done; it might contain sensitive data.</span>
<a name="l00568"></a>00568 <a class="code" href="classPassenger_1_1MemZeroGuard.html" title="Fills the given memory space or string with zeroes when a MemoryZeroGuard object...">MemZeroGuard</a> g(buf, <span class="keyword">sizeof</span>(buf));
<a name="l00569"></a>00569
<a name="l00570"></a>00570 <span class="keywordflow">while</span> (remaining > 0) {
<a name="l00571"></a>00571 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> blockSize = min((<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span>) <span class="keyword">sizeof</span>(buf), remaining);
<a name="l00572"></a>00572
<a name="l00573"></a>00573 <span class="keywordflow">if</span> (!<a class="code" href="classPassenger_1_1MessageChannel.html#b471dc1888f030e20ed23068a160ec2a" title="Read exactly size bytes of data from the underlying file descriptor, and put the...">readRaw</a>(buf, blockSize, timeout)) {
<a name="l00574"></a>00574 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00575"></a>00575 }
<a name="l00576"></a>00576 output.append(buf, blockSize);
<a name="l00577"></a>00577 remaining -= blockSize;
<a name="l00578"></a>00578 }
<a name="l00579"></a>00579 }
<a name="l00580"></a>00580 <span class="keywordflow">return</span> <span class="keyword">true</span>;
<a name="l00581"></a>00581 }
<a name="l00582"></a>00582 <span class="comment"></span>
<a name="l00583"></a>00583 <span class="comment"> /**</span>
<a name="l00584"></a>00584 <span class="comment"> * Read exactly <tt>size</tt> bytes of data from the underlying file descriptor,</span>
<a name="l00585"></a>00585 <span class="comment"> * and put the result in <tt>buf</tt>. If end-of-file has been reached, or if</span>
<a name="l00586"></a>00586 <span class="comment"> * end-of-file was encountered before <tt>size</tt> bytes have been read, then</span>
<a name="l00587"></a>00587 <span class="comment"> * <tt>false</tt> will be returned. Otherwise (i.e. if the read was successful),</span>
<a name="l00588"></a>00588 <span class="comment"> * <tt>true</tt> will be returned.</span>
<a name="l00589"></a>00589 <span class="comment"> *</span>
<a name="l00590"></a>00590 <span class="comment"> * @param buf The buffer to place the read data in. This buffer must be at least</span>
<a name="l00591"></a>00591 <span class="comment"> * <tt>size</tt> bytes long.</span>
<a name="l00592"></a>00592 <span class="comment"> * @param size The number of bytes to read.</span>
<a name="l00593"></a>00593 <span class="comment"> * @param timeout A pointer to an integer, which specifies the maximum number of</span>
<a name="l00594"></a>00594 <span class="comment"> * milliseconds that may be spent on reading the <tt>size</tt> bytes</span>
<a name="l00595"></a>00595 <span class="comment"> * of data. If the timeout expired then TimeoutException will be</span>
<a name="l00596"></a>00596 <span class="comment"> * thrown.</span>
<a name="l00597"></a>00597 <span class="comment"> * If this function returns without throwing an exception, then the</span>
<a name="l00598"></a>00598 <span class="comment"> * total number of milliseconds spent on reading will be deducted</span>
<a name="l00599"></a>00599 <span class="comment"> * from <tt>timeout</tt>.</span>
<a name="l00600"></a>00600 <span class="comment"> * Pass NULL if you do not want to enforce a timeout.</span>
<a name="l00601"></a>00601 <span class="comment"> * @return Whether reading was successful or whether EOF was reached.</span>
<a name="l00602"></a>00602 <span class="comment"> * @pre buf != NULL</span>
<a name="l00603"></a>00603 <span class="comment"> * @throws SystemException Something went wrong during reading.</span>
<a name="l00604"></a>00604 <span class="comment"> * @throws TimeoutException Unable to read <tt>size</tt> bytes of data within</span>
<a name="l00605"></a>00605 <span class="comment"> * <tt>timeout</tt> milliseconds.</span>
<a name="l00606"></a>00606 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00607"></a>00607 <span class="comment"> * @see writeRaw()</span>
<a name="l00608"></a>00608 <span class="comment"> */</span>
<a name="l00609"></a><a class="code" href="classPassenger_1_1MessageChannel.html#b471dc1888f030e20ed23068a160ec2a">00609</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#b471dc1888f030e20ed23068a160ec2a" title="Read exactly size bytes of data from the underlying file descriptor, and put the...">readRaw</a>(<span class="keywordtype">void</span> *buf, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> size, <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> *timeout = NULL) {
<a name="l00610"></a>00610 ssize_t ret;
<a name="l00611"></a>00611 <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> alreadyRead = 0;
<a name="l00612"></a>00612
<a name="l00613"></a>00613 <span class="keywordflow">while</span> (alreadyRead < size) {
<a name="l00614"></a>00614 <span class="keywordflow">if</span> (timeout != NULL && !<a class="code" href="classPassenger_1_1MessageChannel.html#c2407ed109785b49794989507c570149" title="Waits at most *timeout milliseconds for the file descriptor to become readable.">waitUntilReadable</a>(timeout)) {
<a name="l00615"></a>00615 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1TimeoutException.html" title="An exception indicating that some timeout expired.">TimeoutException</a>(<span class="stringliteral">"Cannot read enough data within the specified timeout."</span>);
<a name="l00616"></a>00616 }
<a name="l00617"></a>00617 ret = <a class="code" href="classPassenger_1_1MessageChannel.html#129659b60d1a663337873d2af944431e" title="Read an array message from the underlying file descriptor.">syscalls::read</a>(fd, (<span class="keywordtype">char</span> *) buf + alreadyRead, size - alreadyRead);
<a name="l00618"></a>00618 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00619"></a>00619 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"read() failed"</span>, errno);
<a name="l00620"></a>00620 } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (ret == 0) {
<a name="l00621"></a>00621 <span class="keywordflow">return</span> <span class="keyword">false</span>;
<a name="l00622"></a>00622 } <span class="keywordflow">else</span> {
<a name="l00623"></a>00623 alreadyRead += ret;
<a name="l00624"></a>00624 }
<a name="l00625"></a>00625 }
<a name="l00626"></a>00626 <span class="keywordflow">return</span> <span class="keyword">true</span>;
<a name="l00627"></a>00627 }
<a name="l00628"></a>00628 <span class="comment"></span>
<a name="l00629"></a>00629 <span class="comment"> /**</span>
<a name="l00630"></a>00630 <span class="comment"> * Waits at most <tt>*timeout</tt> milliseconds for the file descriptor to become readable.</span>
<a name="l00631"></a>00631 <span class="comment"> * Returns true if it become readable within the timeout, false if the timeout expired.</span>
<a name="l00632"></a>00632 <span class="comment"> *</span>
<a name="l00633"></a>00633 <span class="comment"> * <tt>*timeout</tt> may be 0, in which case this method will check whether the file</span>
<a name="l00634"></a>00634 <span class="comment"> * descriptor is readable, and immediately returns without waiting.</span>
<a name="l00635"></a>00635 <span class="comment"> *</span>
<a name="l00636"></a>00636 <span class="comment"> * If no exception is thrown, this method deducts the number of milliseconds that has</span>
<a name="l00637"></a>00637 <span class="comment"> * passed from <tt>*timeout</tt>.</span>
<a name="l00638"></a>00638 <span class="comment"> *</span>
<a name="l00639"></a>00639 <span class="comment"> * @throws SystemException</span>
<a name="l00640"></a>00640 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00641"></a>00641 <span class="comment"> */</span>
<a name="l00642"></a><a class="code" href="classPassenger_1_1MessageChannel.html#c2407ed109785b49794989507c570149">00642</a> <span class="keywordtype">bool</span> <a class="code" href="classPassenger_1_1MessageChannel.html#c2407ed109785b49794989507c570149" title="Waits at most *timeout milliseconds for the file descriptor to become readable.">waitUntilReadable</a>(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> *timeout) {
<a name="l00643"></a>00643 fd_set fds;
<a name="l00644"></a>00644 <span class="keyword">struct </span>timeval tv;
<a name="l00645"></a>00645 <span class="keywordtype">int</span> ret;
<a name="l00646"></a>00646
<a name="l00647"></a>00647 FD_ZERO(&fds);
<a name="l00648"></a>00648 FD_SET(fd, &fds);
<a name="l00649"></a>00649 tv.tv_sec = *timeout / 1000;
<a name="l00650"></a>00650 tv.tv_usec = *timeout % 1000 * 1000;
<a name="l00651"></a>00651
<a name="l00652"></a>00652 Timer timer;
<a name="l00653"></a>00653 ret = syscalls::select(fd + 1, &fds, NULL, NULL, &tv);
<a name="l00654"></a>00654 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00655"></a>00655 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"select() failed"</span>, errno);
<a name="l00656"></a>00656 } <span class="keywordflow">else</span> {
<a name="l00657"></a>00657 <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> elapsed = timer.elapsed();
<a name="l00658"></a>00658 <span class="keywordflow">if</span> (elapsed > *timeout) {
<a name="l00659"></a>00659 *timeout = 0;
<a name="l00660"></a>00660 } <span class="keywordflow">else</span> {
<a name="l00661"></a>00661 *timeout -= elapsed;
<a name="l00662"></a>00662 }
<a name="l00663"></a>00663 <span class="keywordflow">return</span> ret != 0;
<a name="l00664"></a>00664 }
<a name="l00665"></a>00665 }
<a name="l00666"></a>00666 <span class="comment"></span>
<a name="l00667"></a>00667 <span class="comment"> /**</span>
<a name="l00668"></a>00668 <span class="comment"> * Receive a file descriptor, which had been passed over the underlying</span>
<a name="l00669"></a>00669 <span class="comment"> * file descriptor.</span>
<a name="l00670"></a>00670 <span class="comment"> *</span>
<a name="l00671"></a>00671 <span class="comment"> * @param negotiate See Ruby's MessageChannel#send_io method's comments.</span>
<a name="l00672"></a>00672 <span class="comment"> * @return The passed file descriptor.</span>
<a name="l00673"></a>00673 <span class="comment"> * @throws SystemException If something went wrong during the</span>
<a name="l00674"></a>00674 <span class="comment"> * receiving of a file descriptor. Perhaps the underlying</span>
<a name="l00675"></a>00675 <span class="comment"> * file descriptor isn't a Unix socket.</span>
<a name="l00676"></a>00676 <span class="comment"> * @throws IOException Whatever was received doesn't seem to be a</span>
<a name="l00677"></a>00677 <span class="comment"> * file descriptor.</span>
<a name="l00678"></a>00678 <span class="comment"> * @throws boost::thread_interrupted</span>
<a name="l00679"></a>00679 <span class="comment"> */</span>
<a name="l00680"></a><a class="code" href="classPassenger_1_1MessageChannel.html#1a28ba9d078f38f2831673092ac9dcbc">00680</a> <span class="keywordtype">int</span> <a class="code" href="classPassenger_1_1MessageChannel.html#1a28ba9d078f38f2831673092ac9dcbc" title="Receive a file descriptor, which had been passed over the underlying file descriptor...">readFileDescriptor</a>(<span class="keywordtype">bool</span> negotiate = <span class="keyword">true</span>) {
<a name="l00681"></a>00681 <span class="keywordflow">if</span> (negotiate) {
<a name="l00682"></a>00682 <a class="code" href="classPassenger_1_1MessageChannel.html#150f68bc47e060dcc6ca35bee047914d" title="Send an array message, which consists of the given elements, over the underlying...">write</a>(<span class="stringliteral">"pass IO"</span>, NULL);
<a name="l00683"></a>00683 }
<a name="l00684"></a>00684
<a name="l00685"></a>00685 <span class="keyword">struct </span>msghdr msg;
<a name="l00686"></a>00686 <span class="keyword">struct </span>iovec vec;
<a name="l00687"></a>00687 <span class="keywordtype">char</span> dummy[1];
<a name="l00688"></a>00688 <span class="preprocessor"> #if defined(__APPLE__) || defined(__SOLARIS__) || defined(__arm__)</span>
<a name="l00689"></a>00689 <span class="preprocessor"></span> <span class="comment">// File descriptor passing macros (CMSG_*) seem to be broken</span>
<a name="l00690"></a>00690 <span class="comment">// on 64-bit MacOS X. This structure works around the problem.</span>
<a name="l00691"></a>00691 <span class="keyword">struct </span>{
<a name="l00692"></a>00692 <span class="keyword">struct </span>cmsghdr header;
<a name="l00693"></a>00693 <span class="keywordtype">int</span> fd;
<a name="l00694"></a>00694 } control_data;
<a name="l00695"></a>00695 <span class="preprocessor"> #define EXPECTED_CMSG_LEN sizeof(control_data)</span>
<a name="l00696"></a>00696 <span class="preprocessor"></span><span class="preprocessor"> #else</span>
<a name="l00697"></a>00697 <span class="preprocessor"></span> <span class="keywordtype">char</span> control_data[CMSG_SPACE(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>))];
<a name="l00698"></a>00698 <span class="preprocessor"> #define EXPECTED_CMSG_LEN CMSG_LEN(sizeof(int))</span>
<a name="l00699"></a>00699 <span class="preprocessor"></span><span class="preprocessor"> #endif</span>
<a name="l00700"></a>00700 <span class="preprocessor"></span> <span class="keyword">struct </span>cmsghdr *control_header;
<a name="l00701"></a>00701 <span class="keywordtype">int</span> ret;
<a name="l00702"></a>00702
<a name="l00703"></a>00703 msg.msg_name = NULL;
<a name="l00704"></a>00704 msg.msg_namelen = 0;
<a name="l00705"></a>00705
<a name="l00706"></a>00706 dummy[0] = <span class="charliteral">'\0'</span>;
<a name="l00707"></a>00707 vec.iov_base = dummy;
<a name="l00708"></a>00708 vec.iov_len = <span class="keyword">sizeof</span>(dummy);
<a name="l00709"></a>00709 msg.msg_iov = &vec;
<a name="l00710"></a>00710 msg.msg_iovlen = 1;
<a name="l00711"></a>00711
<a name="l00712"></a>00712 msg.msg_control = (caddr_t) &control_data;
<a name="l00713"></a>00713 msg.msg_controllen = <span class="keyword">sizeof</span>(control_data);
<a name="l00714"></a>00714 msg.msg_flags = 0;
<a name="l00715"></a>00715
<a name="l00716"></a>00716 ret = syscalls::recvmsg(fd, &msg, 0);
<a name="l00717"></a>00717 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00718"></a>00718 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"Cannot read file descriptor with recvmsg()"</span>, errno);
<a name="l00719"></a>00719 }
<a name="l00720"></a>00720
<a name="l00721"></a>00721 control_header = CMSG_FIRSTHDR(&msg);
<a name="l00722"></a>00722 <span class="keywordflow">if</span> (control_header == NULL) {
<a name="l00723"></a>00723 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1IOException.html" title="Represents an error that occured during an I/O operation.">IOException</a>(<span class="stringliteral">"No valid file descriptor received."</span>);
<a name="l00724"></a>00724 }
<a name="l00725"></a>00725 <span class="keywordflow">if</span> (control_header->cmsg_len != EXPECTED_CMSG_LEN
<a name="l00726"></a>00726 || control_header->cmsg_level != SOL_SOCKET
<a name="l00727"></a>00727 || control_header->cmsg_type != SCM_RIGHTS) {
<a name="l00728"></a>00728 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1IOException.html" title="Represents an error that occured during an I/O operation.">IOException</a>(<span class="stringliteral">"No valid file descriptor received."</span>);
<a name="l00729"></a>00729 }
<a name="l00730"></a>00730 <span class="preprocessor"> #if defined(__APPLE__) || defined(__SOLARIS__) || defined(__arm__)</span>
<a name="l00731"></a>00731 <span class="preprocessor"></span> <span class="keywordflow">return</span> control_data.fd;
<a name="l00732"></a>00732 <span class="preprocessor"> #else</span>
<a name="l00733"></a>00733 <span class="preprocessor"></span> <span class="keywordflow">return</span> *((<span class="keywordtype">int</span> *) CMSG_DATA(control_header));
<a name="l00734"></a>00734 <span class="preprocessor"> #endif</span>
<a name="l00735"></a>00735 <span class="preprocessor"></span> }
<a name="l00736"></a>00736 <span class="comment"></span>
<a name="l00737"></a>00737 <span class="comment"> /**</span>
<a name="l00738"></a>00738 <span class="comment"> * Set the timeout value for reading data from this channel.</span>
<a name="l00739"></a>00739 <span class="comment"> * If no data can be read within the timeout period, then a</span>
<a name="l00740"></a>00740 <span class="comment"> * SystemException will be thrown by one of the read methods,</span>
<a name="l00741"></a>00741 <span class="comment"> * with error code EAGAIN or EWOULDBLOCK.</span>
<a name="l00742"></a>00742 <span class="comment"> *</span>
<a name="l00743"></a>00743 <span class="comment"> * @param msec The timeout, in milliseconds. If 0 is given,</span>
<a name="l00744"></a>00744 <span class="comment"> * there will be no timeout.</span>
<a name="l00745"></a>00745 <span class="comment"> * @throws SystemException Cannot set the timeout.</span>
<a name="l00746"></a>00746 <span class="comment"> */</span>
<a name="l00747"></a><a class="code" href="classPassenger_1_1MessageChannel.html#eb69bffbbb148c9bc8662e20b416c4e2">00747</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#eb69bffbbb148c9bc8662e20b416c4e2" title="Set the timeout value for reading data from this channel.">setReadTimeout</a>(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> msec) {
<a name="l00748"></a>00748 <span class="comment">// See the comment for setWriteTimeout().</span>
<a name="l00749"></a>00749 <span class="keyword">struct </span>timeval tv;
<a name="l00750"></a>00750 <span class="keywordtype">int</span> ret;
<a name="l00751"></a>00751
<a name="l00752"></a>00752 tv.tv_sec = msec / 1000;
<a name="l00753"></a>00753 tv.tv_usec = msec % 1000 * 1000;
<a name="l00754"></a>00754 ret = syscalls::setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO,
<a name="l00755"></a>00755 &tv, <span class="keyword">sizeof</span>(tv));
<a name="l00756"></a>00756 <span class="preprocessor"> #ifndef __SOLARIS__</span>
<a name="l00757"></a>00757 <span class="preprocessor"></span> <span class="comment">// SO_RCVTIMEO is unimplemented and returns an error on Solaris</span>
<a name="l00758"></a>00758 <span class="comment">// 9 and 10 SPARC. Seems to work okay without it.</span>
<a name="l00759"></a>00759 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00760"></a>00760 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"Cannot set read timeout for socket"</span>, errno);
<a name="l00761"></a>00761 }
<a name="l00762"></a>00762 <span class="preprocessor"> #endif</span>
<a name="l00763"></a>00763 <span class="preprocessor"></span> }
<a name="l00764"></a>00764 <span class="comment"></span>
<a name="l00765"></a>00765 <span class="comment"> /**</span>
<a name="l00766"></a>00766 <span class="comment"> * Set the timeout value for writing data to this channel.</span>
<a name="l00767"></a>00767 <span class="comment"> * If no data can be written within the timeout period, then a</span>
<a name="l00768"></a>00768 <span class="comment"> * SystemException will be thrown, with error code EAGAIN or</span>
<a name="l00769"></a>00769 <span class="comment"> * EWOULDBLOCK.</span>
<a name="l00770"></a>00770 <span class="comment"> *</span>
<a name="l00771"></a>00771 <span class="comment"> * @param msec The timeout, in milliseconds. If 0 is given,</span>
<a name="l00772"></a>00772 <span class="comment"> * there will be no timeout.</span>
<a name="l00773"></a>00773 <span class="comment"> * @throws SystemException Cannot set the timeout.</span>
<a name="l00774"></a>00774 <span class="comment"> */</span>
<a name="l00775"></a><a class="code" href="classPassenger_1_1MessageChannel.html#77c5d7c47f387cf43992ebeb14e3c6c7">00775</a> <span class="keywordtype">void</span> <a class="code" href="classPassenger_1_1MessageChannel.html#77c5d7c47f387cf43992ebeb14e3c6c7" title="Set the timeout value for writing data to this channel.">setWriteTimeout</a>(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> msec) {
<a name="l00776"></a>00776 <span class="comment">// People say that SO_RCVTIMEO/SO_SNDTIMEO are unreliable and</span>
<a name="l00777"></a>00777 <span class="comment">// not well-implemented on all platforms.</span>
<a name="l00778"></a>00778 <span class="comment">// http://www.developerweb.net/forum/archive/index.php/t-3439.html</span>
<a name="l00779"></a>00779 <span class="comment">// That's why we use APR's timeout facilities as well (see Hooks.cpp).</span>
<a name="l00780"></a>00780 <span class="keyword">struct </span>timeval tv;
<a name="l00781"></a>00781 <span class="keywordtype">int</span> ret;
<a name="l00782"></a>00782
<a name="l00783"></a>00783 tv.tv_sec = msec / 1000;
<a name="l00784"></a>00784 tv.tv_usec = msec % 1000 * 1000;
<a name="l00785"></a>00785 ret = syscalls::setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO,
<a name="l00786"></a>00786 &tv, <span class="keyword">sizeof</span>(tv));
<a name="l00787"></a>00787 <span class="preprocessor"> #ifndef __SOLARIS__</span>
<a name="l00788"></a>00788 <span class="preprocessor"></span> <span class="comment">// SO_SNDTIMEO is unimplemented and returns an error on Solaris</span>
<a name="l00789"></a>00789 <span class="comment">// 9 and 10 SPARC. Seems to work okay without it.</span>
<a name="l00790"></a>00790 <span class="keywordflow">if</span> (ret == -1) {
<a name="l00791"></a>00791 <span class="keywordflow">throw</span> <a class="code" href="classPassenger_1_1SystemException.html" title="Represents an error returned by a system call or a standard library call.">SystemException</a>(<span class="stringliteral">"Cannot set read timeout for socket"</span>, errno);
<a name="l00792"></a>00792 }
<a name="l00793"></a>00793 <span class="preprocessor"> #endif</span>
<a name="l00794"></a>00794 <span class="preprocessor"></span> }
<a name="l00795"></a>00795 };
<a name="l00796"></a>00796
<a name="l00797"></a>00797 } <span class="comment">// namespace Passenger</span>
<a name="l00798"></a>00798
<a name="l00799"></a>00799 <span class="preprocessor">#endif </span><span class="comment">/* _PASSENGER_MESSAGE_CHANNEL_H_ */</span>
</pre></div></div>
<hr size="1"><address style="text-align: right;"><small>Generated on Sun Feb 21 12:22:45 2010 for Passenger by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
|
