Debian Codegraph @

cextern/xpa/man/man3/xparace.3

raw
1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "xparace 3"
127 .TH xparace 3 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 \&\fB\s-1XPA\s0 Race Conditions\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 Potential \s-1XPA\s0 race conditions and how to avoid them.
137 .SH "DESCRIPTION"
138 .IX Header "DESCRIPTION"
139 Currently, there is only one known circumstance in which \s-1XPA\s0 can get
140 (temporarily) deadlocked in a race condition: if two or more \s-1XPA\s0
141 servers send messages to one another using an \s-1XPA\s0 client routine such
142 as \fIXPASet()\fR, they can deadlock while each waits for the other server
143 to respond. (This can happen if the servers call \fIXPAPoll()\fR with a
144 time limit, and send messages in between the polling call.) The
145 reason this happens is that both client routines send a string to the
146 other server to establish the handshake and then wait for the server
147 response. Since each client is waiting for a response, neither is able
148 to enter its event-handling loop and respond to the other's
149 request. This deadlock will continue until one of the timeout periods
150 expire, at which point an error condition will be triggered and the
151 timed-out server will return to its event loop.
152 .PP
153 Starting with version 2.1.6, this rare race condition can be
154 avoided by setting the \s-1XPA_IOCALLSXPA\s0 environment variable for servers
155 that will make client calls. Setting this variable causes all \s-1XPA\s0
156 socket \s-1IO\s0 calls to process outstanding \s-1XPA\s0 requests whenever the
157 primary socket is not ready for \s-1IO\s0. This means that a server making a
158 client call will (recursively) process incoming server requests while
159 waiting for client completion. It also means that a server callback
160 routine can handle incoming \s-1XPA\s0 messages if it makes its own \s-1XPA\s0 call.
161 The semi-public routine oldvalue=XPAIOCallsXPA(newvalue) can be used
162 to turn this behavior off and on temporarily. Passing a 0 will turn
163 off \s-1IO\s0 processing, 1 will turn it back on. The old value is returned
164 by the call.
165 .PP
166 By default, the \s-1XPA_IOCALLSXPA\s0 option is turned off, because we judge
167 that the added code complication and overhead involved will not be
168 justified by the amount of its use. Moreover, processing \s-1XPA\s0 requests
169 within socket \s-1IO\s0 can lead to non-intuitive results, since incoming
170 server requests will not necessarily be processed to completion in the
171 order in which they are received.
172 .PP
173 Aside from setting \s-1XPA_IOCALLSXPA\s0, the simplest way to avoid this race
174 condition is to multi-process: when you want to send a client message,
175 simply start a separate process to call the client routine, so that
176 the server is not stopped. It probably is fastest and easiest to use
177 \&\fIfork()\fR and then have the child call the client routine and exit. But
178 you also can use either the \fIsystem()\fR or \fIpopen()\fR routine to start one
179 of the command line programs and do the same thing. Alternatively, you
180 can use \s-1XPA\s0's internal \fIlaunch()\fR routine instead of \fIsystem()\fR. Based on
181 \&\fIfork()\fR and \fIexec()\fR, this routine is more secure than \fIsystem()\fR because
182 it does not call /bin/sh.
183 .PP
184 Starting with version 2.1.5, you also can send an \fIXPAInfo()\fR message with
185 the mode string \*(L"ack=false\*(R". This will cause the client to send a message
186 to the server and then exit without waiting for any return message from
187 the server. This UDP-like behavior will avoid the server deadlock when
188 sending short XPAInfo messages.
189 .SH "SEE ALSO"
190 .IX Header "SEE ALSO"
191 See xpa(n) for a list of \s-1XPA\s0 help pages