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