1 .TH FLUSH 9P
2 .SH NAME
3 flush \- abort a message
4 .SH SYNOPSIS
5 .ta \w'\fLTflush 'u
6 .IR size [4]
7 .B Tflush
8 .IR tag [2]
9 .IR oldtag [2]
10 .br
11 .IR size [4]
12 .B Rflush
13 .IR tag [2]
14 .SH DESCRIPTION
15 When the response to a request is no longer needed, such as when
16 a user interrupts a process doing a
17 .IR read (9p),
18 a
19 .B Tflush
20 request is sent to the server to purge the pending response.
21 The message being flushed is identified by
22 .IR oldtag .
23 The semantics of
24 .B flush
25 depends on messages arriving in order.
26 .PP
27 The server should answer the
28 .B flush
29 message immediately.
30 If it recognizes
31 .I oldtag
32 as the tag of a pending transaction, it should abort any pending response
33 and discard that tag.
34 In either case, it should respond with an
35 .B Rflush
36 echoing the
37 .I tag
38 (not
39 .IR oldtag )
40 of the
41 .B Tflush
42 message.
43 A
44 .B Tflush
45 can never be responded to by an
46 .B Rerror
47 message.
48 .PP
49 The server may respond to the pending request before
50 responding to the
51 .BR Tflush .
52 It is possible for a client to send multiple
53 .B Tflush
54 messages for a particular pending request.  Each
55 subsequent
56 .B Tflush
57 must contain as
58 .I oldtag
59 the tag of the pending request (not a previous
60 .BR Tflush ).
61 Should multiple
62 .BR Tflush es
63 be received for a pending request, they must be answered in
64 order.  A
65 .B Rflush
66 for any of the multiple
67 .BR Tflush es
68 implies an answer for all previous ones.  Therefore, should
69 a server receive a request and then multiple flushes for that
70 request, it need respond only to the last flush.
71 .PP
72 When the client sends a 
73 .BR Tflush ,
74 it must wait to receive the corresponding
75 .B Rflush
76 before reusing
77 .I oldtag
78 for subsequent messages.
79 If a response to the flushed request is received before the
80 .BR Rflush ,
81 the client must honor the response
82 as if it had not been flushed,
83 since the completed request may signify a state change in the server.
84 For instance,
85 .B Tcreate
86 may have created a file and
87 .B Twalk
88 may have allocated a fid.
89 If no response is received before the
90 .BR Rflush ,
91 the flushed transaction is considered to have been canceled,
92 and should be treated as though it had never been sent.
93 .PP
94 Several exceptional conditions are handled correctly by the above specification:
95 sending multiple flushes for a single tag,
96 flushing after a transaction is completed,
97 flushing a
98 .BR Tflush ,
99 and flushing an invalid tag.
100 .SH ENTRY POINTS
101 The
102 .MR 9pclient (3)
103 library does not generate
104 .B flush
105 transactions..
106 .MR 9pserve (4)
107 generates
108 .B flush
109 transactions to cancel transactions pending when a client hangs up.