xref: /trafficserver/iocore/eventsystem/I_VIO.h (revision a5345da8)
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   Continuation *get_continuation();
82   void set_continuation(Continuation * cont);
83 
84   /**
85     Set nbytes to be what is current available.
86 
87     Interface to set nbytes to be ndone + buffer.reader()->read_avail()
88     if a reader is set.
89   */
90   void done();
91 
92   /**
93     Determine the number of bytes remaining.
94 
95     Convenience function to determine how many bytes the operation
96     has remaining.
97 
98     @return The number of bytes to be processed by the operation.
99 
100   */
101   int ntodo();
102 
103   /////////////////////
104   // buffer settings //
105   /////////////////////
106   void set_writer(MIOBuffer * writer);
107   void set_reader(IOBufferReader * reader);
108   MIOBuffer *get_writer();
109   IOBufferReader *get_reader();
110 
111   /**
112     Reenable the IO operation.
113 
114     Interface that the state machine uses to reenable an I/O
115     operation.  Reenable tells the VConnection that more data is
116     available for the operation and that it should try to continue
117     the operation in progress.  I/O operations become disabled when
118     they can make no forward progress.  For a read this means that
119     it's buffer is full. For a write, that it's buffer is empty.
120     If reenable is called and progress is still not possible, it
121     is ignored and no events are generated. However, unnecessary
122     reenables (ones where no progress can be made) should be avoided
123     as they hurt system throughput and waste CPU.
124 
125   */
126   inkcoreapi void reenable();
127 
128   /**
129     Reenable the IO operation.
130 
131     Interface that the state machine uses to reenable an I/O
132     operation.  Reenable tells the VConnection that more data is
133     available for the operation and that it should try to continue
134     the operation in progress.  I/O operations become disabled when
135     they can make no forward progress.  For a read this means that
136     it's buffer is full. For a write, that it's buffer is empty.
137     If reenable is called and progress is still not possible, it
138     is ignored and no events are generated. However, unnecessary
139     reenables (ones where no progress can be made) should be avoided
140     as they hurt system throughput and waste CPU.
141 
142   */
143   inkcoreapi void reenable_re();
144 
145   VIO(int aop);
146   VIO();
147 
148   enum
149   {
150     NONE = 0, READ, WRITE, CLOSE, ABORT,
151     SHUTDOWN_READ, SHUTDOWN_WRITE, SHUTDOWN_READWRITE,
152     SEEK, PREAD, PWRITE, STAT
153   };
154 
155 public:
156 
157   /**
158     Continuation to callback.
159 
160     Used by the VConnection to store who is the continuation to
161     call with events for this operation.
162 
163   */
164   Continuation * _cont;
165 
166   /**
167     Number of bytes to be done for this operation.
168 
169     The total number of bytes this operation must complete.
170 
171   */
172   ink64 nbytes;
173 
174   /**
175     Number of bytes already completed.
176 
177     The number of bytes that already have been completed for the
178     operation. Processor can update this value only if they hold
179     the lock.
180 
181   */
182   ink64 ndone;
183 
184   /**
185     Type of operation.
186 
187     The type of operation that this VIO represents.
188 
189   */
190   int op;
191 
192   /**
193     Provides access to the reader or writer for this operation.
194 
195     Contains a pointer to the IOBufferReader if the operation is a
196     write and a pointer to a MIOBuffer if the operation is a read.
197 
198   */
199   MIOBufferAccessor buffer;
200 
201   /**
202     Internal backpointer to the VConnection for use in the reenable
203     functions.
204 
205   */
206   VConnection *vc_server;
207 
208   /**
209     Reference to the state machine's mutex.
210 
211     Maintains a reference to the state machine's mutex to allow
212     processors to safely lock the operation even if the state machine
213     has closed the VConnection and deallocated itself.
214 
215   */
216   Ptr<ProxyMutex> mutex;
217 };
218 
219 #include "I_VConnection.h"
220 #endif
221