xref: /trafficserver/iocore/eventsystem/I_VIO.h (revision e568bb32)
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 #if !defined(I_VIO_h)
26 #define I_VIO_h
27 
28 #include "ts/ink_platform.h"
29 #include "I_EventSystem.h"
30 #if !defined(I_IOBuffer_h)
31 #error "include I_IOBuffer.h"
32 -- -
33   include I_IOBuffer.h
34 #endif
35 #include "ts/ink_apidefs.h"
36   class Continuation;
37 class VConnection;
38 class IOVConnection;
39 class MIOBuffer;
40 class ProxyMutex;
41 
42 /**
43   Descriptor for an IO operation.
44 
45   A VIO is a descriptor for an in progress IO operation. It is
46   returned from do_io_read() and do_io_write() methods on VConnections.
47   Through the VIO, the state machine can monitor the progress of
48   an operation and reenable the operation when data becomes available.
49 
50   The VIO operation represents several types of operations, and
51   they can be identified through the 'op' member. It can take any
52   of the following values:
53 
54   <table>
55     <tr>
56       <td align="center"><b>Constant</b></td>
57       <td align="center"><b>Meaning</b></td>
58     </tr>
59     <tr><td>READ</td><td>The VIO represents a read operation</td></tr>
60     <tr><td>WRITE</td><td>The VIO represents a write operation</td></tr>
61     <tr><td>CLOSE</td><td>The VIO represents the request to close the
62                           VConnection</td></tr>
63     <tr><td>ABORT</td><td></td></tr>
64     <tr><td>SHUTDOWN_READ</td><td></td></tr>
65     <tr><td>SHUTDOWN_WRITE</td><td></td></tr>
66     <tr><td>SHUTDOWN_READWRITE</td><td></td></tr>
67     <tr><td>SEEK</td><td></td></tr>
68     <tr><td>PREAD</td><td></td></tr>
69     <tr><td>PWRITE</td><td></td></tr>
70     <tr><td>STAT</td><td></td></tr>
71   </table>
72 
73 */
74 class VIO
75 {
76 public:
77   ~VIO() {}
78 
79   /** Interface for the VConnection that owns this handle. */
80   Continuation *get_continuation();
81   void set_continuation(Continuation *cont);
82 
83   /**
84     Set nbytes to be what is current available.
85 
86     Interface to set nbytes to be ndone + buffer.reader()->read_avail()
87     if a reader is set.
88   */
89   void done();
90 
91   /**
92     Determine the number of bytes remaining.
93 
94     Convenience function to determine how many bytes the operation
95     has remaining.
96 
97     @return The number of bytes to be processed by the operation.
98 
99   */
100   int64_t ntodo();
101 
102   /////////////////////
103   // buffer settings //
104   /////////////////////
105   void set_writer(MIOBuffer *writer);
106   void set_reader(IOBufferReader *reader);
107   MIOBuffer *get_writer();
108   IOBufferReader *get_reader();
109 
110   /**
111     Reenable the IO operation.
112 
113     Interface that the state machine uses to reenable an I/O
114     operation.  Reenable tells the VConnection that more data is
115     available for the operation and that it should try to continue
116     the operation in progress.  I/O operations become disabled when
117     they can make no forward progress.  For a read this means that
118     it's buffer is full. For a write, that it's buffer is empty.
119     If reenable is called and progress is still not possible, it
120     is ignored and no events are generated. However, unnecessary
121     reenables (ones where no progress can be made) should be avoided
122     as they hurt system throughput and waste CPU.
123 
124   */
125   inkcoreapi void reenable();
126 
127   /**
128     Reenable the IO operation.
129 
130     Interface that the state machine uses to reenable an I/O
131     operation.  Reenable tells the VConnection that more data is
132     available for the operation and that it should try to continue
133     the operation in progress.  I/O operations become disabled when
134     they can make no forward progress.  For a read this means that
135     it's buffer is full. For a write, that it's buffer is empty.
136     If reenable is called and progress is still not possible, it
137     is ignored and no events are generated. However, unnecessary
138     reenables (ones where no progress can be made) should be avoided
139     as they hurt system throughput and waste CPU.
140 
141   */
142   inkcoreapi void reenable_re();
143 
144   VIO(int aop);
145   VIO();
146 
147   enum {
148     NONE = 0,
149     READ,
150     WRITE,
151     CLOSE,
152     ABORT,
153     SHUTDOWN_READ,
154     SHUTDOWN_WRITE,
155     SHUTDOWN_READWRITE,
156     SEEK,
157     PREAD,
158     PWRITE,
159     STAT,
160   };
161 
162 public:
163   /**
164     Continuation to callback.
165 
166     Used by the VConnection to store who is the continuation to
167     call with events for this operation.
168 
169   */
170   Continuation *_cont;
171 
172   /**
173     Number of bytes to be done for this operation.
174 
175     The total number of bytes this operation must complete.
176 
177   */
178   int64_t nbytes;
179 
180   /**
181     Number of bytes already completed.
182 
183     The number of bytes that already have been completed for the
184     operation. Processor can update this value only if they hold
185     the lock.
186 
187   */
188   int64_t ndone;
189 
190   /**
191     Type of operation.
192 
193     The type of operation that this VIO represents.
194 
195   */
196   int op;
197 
198   /**
199     Provides access to the reader or writer for this operation.
200 
201     Contains a pointer to the IOBufferReader if the operation is a
202     write and a pointer to a MIOBuffer if the operation is a read.
203 
204   */
205   MIOBufferAccessor buffer;
206 
207   /**
208     Internal backpointer to the VConnection for use in the reenable
209     functions.
210 
211   */
212   VConnection *vc_server;
213 
214   /**
215     Reference to the state machine's mutex.
216 
217     Maintains a reference to the state machine's mutex to allow
218     processors to safely lock the operation even if the state machine
219     has closed the VConnection and deallocated itself.
220 
221   */
222   Ptr<ProxyMutex> mutex;
223 };
224 
225 #include "I_VConnection.h"
226 #endif
227