xref: /trafficserver/iocore/eventsystem/I_VIO.h (revision dc0fb99b)
1 /** @file
2 
3   A brief file description
4 
5   @section license License
6 
7   Licensed to the Apache Software Foundation (ASF) under one
8   or more contributor license agreements.  See the NOTICE file
9   distributed with this work for additional information
10   regarding copyright ownership.  The ASF licenses this file
11   to you under the Apache License, Version 2.0 (the
12   "License"); you may not use this file except in compliance
13   with the License.  You may obtain a copy of the License at
14 
15       http://www.apache.org/licenses/LICENSE-2.0
16 
17   Unless required by applicable law or agreed to in writing, software
18   distributed under the License is distributed on an "AS IS" BASIS,
19   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   See the License for the specific language governing permissions and
21   limitations under the License.
22 
23  */
24 
25 #pragma once
26 #define I_VIO_h
27 
28 #if !defined(I_IOBuffer_h)
29 #error "include I_IOBuffer.h"
30 #endif
31 
32 class Continuation;
33 class VConnection;
34 class ProxyMutex;
35 
36 /**
37   Descriptor for an IO operation.
38 
39   A VIO is a descriptor for an in progress IO operation. It is
40   returned from do_io_read() and do_io_write() methods on VConnections.
41   Through the VIO, the state machine can monitor the progress of
42   an operation and reenable the operation when data becomes available.
43 
44   The VIO operation represents several types of operations, and
45   they can be identified through the 'op' member. It can take any
46   of the following values:
47 
48   <table>
49     <tr>
50       <td align="center"><b>Constant</b></td>
51       <td align="center"><b>Meaning</b></td>
52     </tr>
53     <tr><td>READ</td><td>The VIO represents a read operation</td></tr>
54     <tr><td>WRITE</td><td>The VIO represents a write operation</td></tr>
55     <tr><td>CLOSE</td><td>The VIO represents the request to close the
56                           VConnection</td></tr>
57     <tr><td>ABORT</td><td></td></tr>
58     <tr><td>SHUTDOWN_READ</td><td></td></tr>
59     <tr><td>SHUTDOWN_WRITE</td><td></td></tr>
60     <tr><td>SHUTDOWN_READWRITE</td><td></td></tr>
61     <tr><td>SEEK</td><td></td></tr>
62     <tr><td>PREAD</td><td></td></tr>
63     <tr><td>PWRITE</td><td></td></tr>
64     <tr><td>STAT</td><td></td></tr>
65   </table>
66 
67 */
68 class VIO
69 {
70 public:
71   explicit VIO(int aop);
72   VIO();
~VIO()73   ~VIO() {}
74 
75   /** Interface for the VConnection that owns this handle. */
76   Continuation *get_continuation() const;
77   void set_continuation(Continuation *cont);
78 
79   /**
80     Set nbytes to be what is current available.
81 
82     Interface to set nbytes to be ndone + buffer.reader()->read_avail()
83     if a reader is set.
84   */
85   void done();
86 
87   /**
88     Determine the number of bytes remaining.
89 
90     Convenience function to determine how many bytes the operation
91     has remaining.
92 
93     @return The number of bytes to be processed by the operation.
94 
95   */
96   int64_t ntodo() const;
97 
98   /////////////////////
99   // buffer settings //
100   /////////////////////
101   void set_writer(MIOBuffer *writer);
102   void set_reader(IOBufferReader *reader);
103   MIOBuffer *get_writer() const;
104   IOBufferReader *get_reader() const;
105 
106   /**
107     Reenable the IO operation.
108 
109     Interface that the state machine uses to reenable an I/O
110     operation.  Reenable tells the VConnection that more data is
111     available for the operation and that it should try to continue
112     the operation in progress.  I/O operations become disabled when
113     they can make no forward progress.  For a read this means that
114     it's buffer is full. For a write, that it's buffer is empty.
115     If reenable is called and progress is still not possible, it
116     is ignored and no events are generated. However, unnecessary
117     reenables (ones where no progress can be made) should be avoided
118     as they hurt system throughput and waste CPU.
119 
120   */
121   inkcoreapi void reenable();
122 
123   /**
124     Reenable the IO operation.
125 
126     Interface that the state machine uses to reenable an I/O
127     operation.  Reenable tells the VConnection that more data is
128     available for the operation and that it should try to continue
129     the operation in progress.  I/O operations become disabled when
130     they can make no forward progress.  For a read this means that
131     it's buffer is full. For a write, that it's buffer is empty.
132     If reenable is called and progress is still not possible, it
133     is ignored and no events are generated. However, unnecessary
134     reenables (ones where no progress can be made) should be avoided
135     as they hurt system throughput and waste CPU.
136 
137   */
138   inkcoreapi void reenable_re();
139 
140   void disable();
141   bool is_disabled() const;
142 
143   enum {
144     NONE = 0,
145     READ,
146     WRITE,
147     CLOSE,
148     ABORT,
149     SHUTDOWN_READ,
150     SHUTDOWN_WRITE,
151     SHUTDOWN_READWRITE,
152     SEEK,
153     PREAD,
154     PWRITE,
155     STAT,
156   };
157 
158   /**
159     Continuation to callback.
160 
161     Used by the VConnection to store who is the continuation to
162     call with events for this operation.
163 
164   */
165   Continuation *cont = nullptr;
166 
167   /**
168     Number of bytes to be done for this operation.
169 
170     The total number of bytes this operation must complete.
171 
172   */
173   int64_t nbytes = 0;
174 
175   /**
176     Number of bytes already completed.
177 
178     The number of bytes that already have been completed for the
179     operation. Processor can update this value only if they hold
180     the lock.
181 
182   */
183   int64_t ndone = 0;
184 
185   /**
186     Type of operation.
187 
188     The type of operation that this VIO represents.
189 
190   */
191   int op = VIO::NONE;
192 
193   /**
194     Provides access to the reader or writer for this operation.
195 
196     Contains a pointer to the IOBufferReader if the operation is a
197     write and a pointer to a MIOBuffer if the operation is a read.
198 
199   */
200   MIOBufferAccessor buffer;
201 
202   /**
203     Internal backpointer to the VConnection for use in the reenable
204     functions.
205 
206   */
207   VConnection *vc_server = nullptr;
208 
209   /**
210     Reference to the state machine's mutex.
211 
212     Maintains a reference to the state machine's mutex to allow
213     processors to safely lock the operation even if the state machine
214     has closed the VConnection and deallocated itself.
215 
216   */
217   Ptr<ProxyMutex> mutex;
218 
219 private:
220   bool _disabled = false;
221 };
222