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