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